Guía de Inicio

 

Catálogo de API Products

En nuestro catálogo podrás encontrar los API Products disponibles, con su descripción y una explicación de su funcionalidad, así como también, documentación técnica de cada API. Para ver la documentación técnica, tienes que tener tu sesión iniciada.

 

Regístrate

Los API Products que encontrarás en nuestro catálogo están disponibles para que los pruebes en entorno Sandbox.

Para ello, solo debes registrarte. Desde el botón “Regístrate” de nuestra página principal, completa el formulario. A partir de allí, podrás acceder a tu cuenta y gestionar tus aplicaciones.

Registra tu aplicación

Para consumir nuestros API Products en ambiente Sandbox, debes seguir los siguientes pasos:

  1. Inicia sesión
  2. Crea una aplicación.

 

 

Nombre Aplicación

Debes indicar el nombre que tiene o tendrá tu aplicación que consumirá APIs. Este nombre será mostrado al cliente BCI cuando dé el consentimiento.

URL de devolución de llamada

Aquí debes informar la URL de tu sitio a la cual debe volver el proceso de Oauth (BCI Access) al finalizar

Descripción

¿En qué consiste tu aplicación?

PublicKey

Genera un par de llaves pública y privada, si no sabes cómo al final de esta guía hay un tutorial de como hacerlo. Debes pegar la llave pública en este formulario. La privada guardala pues la usarás cuando consumas las APIs desde tu aplicación.

TppId

Completar con un valor numérico de 5 dígitos que luego se utilizará para informar en las peticiones donde así se lo requieran las APIs publicadas.

Asocia los API Products que te interesa consumir.

Prueba la integración de tu aplicación con los API Products en modo sandbox utilizando las guías técnicas de cada API Product.

Dashboard

Siguiendo estos pasos, habrás registrado tu aplicación correctamente. Luego entonces, podrás ir a tu menú personal y seleccionar “Mis Aplicaciones”. En este panel de control verás todas las aplicaciones que hayas registrado, las llamadas que hayas realizado, etc.

Lo más importante de esta sección es que en ella encontrarás el App ID y App Secret ID, que son tus credenciales para utilizar las APIs de BCI.

Guía de llamada a APIs

 

APIs con Bci Access No Requerido

Si el API Product que deseas conectar, no requiere autorización por medio de Bci Access, como por ejemplo Economic Indicators, el procedimiento de llamada sería de la siguiente manera:

curl --location --request GET '

https://apiprogram.bci.cl/{ambiente}/v1/api-economic-indicators/list?query-date=2019-11-26' \

--header 'Content-Type: application/json' \

--header 'x-apikey: {{tu_App_ID}}'

Donde:

  • {{tu_App_ID}}:  Es el App ID o también llamada Consumer Key que te entrega el API Market al registrar
    tu aplicación.
  • {{ambiente}}: [sandbox | prod]

APIs con Bci Access Requerido

Para consumir a una API con Bci Access, llamadas APIs Privadas, primero debes obtener un código que se usa para obtener un access token y posteriormente hacer la llamada a la API con el access token obtenido. Es importante que recuerdes que este código es válido para un usuario específico y por un tiempo limitado.



Paso 1: Solicitud de token para acceder a AccessRequest

	curl --location --request POST 'https://apiprogram.bci.cl/{{ambiente}}/v1/
	api-oauth/token' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'redirect_uri ={{CallbackUrl}}' \
	--data-urlencode 'client_assertion={{JWT_Oauth}}' \
	--data-urlencode 'grant_type=client_credentials' \
	--data-urlencode 'scope=access-requests'
	

Donde se deben establecer los parámetros requeridos:

Parameter In Name Value Required
header Content-Type application/x-www-form-urlencoded Yes
data-urlencode grant_type client_credentials Yes
data-urlencode redirect_uri {{CallbackUrl}} Url especificada como Url de devolución de llamada
en el API Market para tu aplicación
Yes
data-urlencode scope {{scope}} ámbito para el cual se requiere un acceso.
Los valores de "scopes" están detallados en la documentación
particular de cada producto.
En este caso es access-request
Yes
data-urlencode client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-beare Yes
data-urlencode client_assertion {{JWT_Oauth}} JWT firmado con la clave privada correspondiente
a la clave pública cargada en el developer app.
Campos:
{
"iss": "{{tu_App_ID}}",
"credentials": "tu_App_secret"
}

Ver cómo generar un token jwt.
Yes
 

 

Respuesta:

	{
	   "access_token": "{{access_token}}",
	   "token_type": "Bearer",
	   "expires_in": 3599
	}
	

Paso 2: Llamada a AccessRequest

Utiliza el access token obtenido en el paso anterior para solicitar iniciar un proceso de Access Request para el producto (Scope) que quieras consumir. Ejemplo: customers.

	curl --location --request POST 'https://apiprogram.bci.cl/{{ambiente}}/v1/
	api-access-requests/requests' \
	--header 'Authorization: Bearer {{access_token}} \
	--header 'Content-Type: application/json' \
	--data-raw '{
	   "Data": {
		   "TppId": "{{tu_TppId}}",
		   "Scope": "{{scope}}"
	   }
	}'
	

Donde se deben establecer los parámetros requeridos:

Parameter In Name Value Required
header Authorization Bearer {{access_token}}, donde {{access_token}} es el token recibido en el paso anterior Yes
header Content-Type application/x-www-form-urlencoded Yes
header Content-Type application/json Yes
header {
 "Data": {
    "TppId": "{{TppId}}"
    "Scope": "{{Scope}}"
  }
}
TppId: corresponde al identificador de 5 dígitos que le asignaste a tu aplicación en el API Market.
Scope: ámbito para el cual se requiere un acceso. Los valores de "scopes" están detallados en la documentación particular de cada producto. Ejemplo: "customers".
Yes
 

Respuesta (ejemplo)

	{
		"Request": {
			"RequestId": "5f6a1aa4a485c100076610cf",
			"CreationDateTime": "2020-09-22T12:27:23-03:00",
			"Data": {
				"TransactionFromDateTime": "2020-09-22T12:27:23-03:00",
				"TransactionToDateTime": "2021-03-21T12:27:23-03:00",
				"ExpirationDateTime": "2020-10-22T12:27:23-03:00"
			},
			"Status": "AwaitingAuthorization",
			"TppId": "{{tu_TppId}}",
			"Scope": "customers"
		}
	}
	

Paso 3: Llamada a oAuth Authorize
Ejecutar llamada a:

	curl --location --request POST ‘https://apiprogram.bci.cl/{{ambiente}}/v1/
	api-oauth/authorize?response_type=code&client_id={{tu_App_ID}}&redirect_uri=
	{{CallbackUrl}}&state={{uudiv1}}&nonce={{uuidv4}}&scope={{Scope}}&request=
	{{JWT_Auth}}’
	--header 'Content-Type: application/json' \
	--header 'x-apikey:  {{tu_App_ID}}'
	

Donde {{ambiente}}: [sandbox | prod]

Parameter In Name Value Required
header Content-Type application/x-www-form-urlencoded Yes
data-urlencode grant_type client_credentials Yes
data-urlencode redirect_uri {{CallbackUrl}} Url especificada como Url de devolución de llamada
en el API Market para tu aplicación
Yes
data-urlencode scope {{scope}} ámbito para el cual se requiere un acceso.
Los valores de "scopes" están detallados en la documentación
particular de cada producto.
En este caso es access-request
Yes
data-urlencode client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-beare Yes
data-urlencode client_assertion {{JWT_Oauth}} JWT firmado con la clave privada correspondiente
a la clave pública cargada en el developer app.
Campos:
{
"iss": "{{tu_App_ID}}",
"credentials": "tu_App_secret"
}

Ver cómo generar un token jwt.
Yes
 

La respuesta de esta llamada es un código 302 que re-direccionará tu sitio o app hacia el sitio del Bci ACCESS de Bci. El cliente deberá completar los pasos que se indican y al finalizar el proceso el mismo Bci Access retornará a la url de redirección que indicaste al registrar tu aplicación (CallbackUrl) junto a él código del cliente requerido para la ejecución del último paso. Este codigoCliente dura 30 días y te permitirá consumir el producto asociado al cliente para el cual realizaste el proceso. Te sugerimos almacenarlo para no tener que pasar por el proceso de Oauth nuevamente.

Respuesta:

	{{CallbackUrl}}?code={{codigoCliente}}

Paso 4: Obtención del Authorization Token en  oAuth 
Para finalizar, debes invocar  método token para la generación del Authorization Token que te permitirá acceder a la API deseada.

	curl --location --request POST 'https://apiprogram.bci.cl/{{ambiente}}/v1/
	api-oauth/token' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'grant_type=authorization_code' \
	--data-urlencode 'redirect_uri={{CallbackUrl}}' \
	--data-urlencode 'client_id={{tu_App_ID}}’ \
	--data-urlencode 'code={{codigoCliente}}' \
	--data-urlencode 'scope={{scope}} \
	--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type
	:jwt-bearer' \
	--data-urlencode 'client_assertion={{JWT_Oauth}}'
	

Donde se deben establecer los parámetros requeridos:

Parameter in Name Value
header Content-Type application/json
header x-apikey {{tu_App_ID}}: Es el App ID o también llamado Consumer Key que te entrega el API Market
al registrar tu aplicación.
header ClientId {{tu_App_ID}}: Es el App ID o también llamado Consumer Key que te entrega el API Market
al registrar tu aplicación.
header ResponseType code
header RedirectUri {{CallbackUrl}}: Url que especificaste como url de devolución de llamada en el API Market
para tu aplicación.
header State {{state}}: uuid v.1 generado para esta transacción
header Nonce {{nonce}}: uuid v.1 generado para esta transacción
header Scope {{scope}}: Ámbito para el cual se requiere un acceso. Los valores de "scopes" están detallados
en la documentación particular de cada producto. Ejemplo: "customers"
header Request {{JWT_Auth}}: JWT firmado con la clave privada correspondiente a la clave pública cargada en
el developer app.

{
   "https://api.openbank.com",
   "code",
   "client_id":{{tu_App_ID}},
   "redirect_uri": {{CallbackUrl}},
   "scope": {{scope}},
   "state": {{state}},
   "nonce": {{nonce}},
   "claims": {
      "id_token": {
         "openbanking_intent_id": {
         "value": "urn:openbank:intent:" + {{scope}} + {{requestId}},
         "essential": true
         },
      "acr": {
         "essential": true
         }
      }
   }
}

Los valores de los campos de JWT tu_App_ID, CallbackUrl, scope, state y nonce deben
ser los mismos que ls enviados en la url de la llamada a la API.

Ver cómo generar un token jwt.

 

Respuesta (ejemplo)

	{
	   "access_token": "PPTHdpasasfaguyrrWDH0RC56RBv",
	   "token_type": "Bearer",
	   "refresh_token": "GzXLmCagsmaiiaytinj0LzNp0IGy",
	   "expires_in": 3599
	}
	

Paso Opcional: Obtención del Refresh Access Token a oAuth Authorize

En caso de caducidad del Access Token obtenido, es posible generar un nuevo token a partir del refresh token (recibido previamente)

POST /{{api_env}}/v1/api-oauth/token

Donde {{api_env}}: [sandbox | prod]

	curl --location --request POST '{{host-endpoint}}/{api_env}/v1/api-oauth/token' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'grant_type= refresh_token' \
	--data-urlencode 'client_id={{LOrx7gHAMo4irOqWTSzrB5zNMRxgePJ}}' \
	--data-urlencode 'client_secret={{cdysiRU6}}' \
	--data-urlencode ' refresh_token={{ refresh_token }}'
	

Donde se deben establecer los parámetros requeridos:
 

Parameter In Name Value Required
header Content-Type application/x-www-form-urlencoded yes
data-urlencode grant_type refresh_token yes
data-urlencode client_id {{client_id}}: valor del apikey yes
data-urlencode client_secret {{code}}: valor del api secret yes
data-urlencode refresh_token {{refresh_token}}: valor del refresh obtenido en el paso 4 yes

 

 

Respuesta:

	{
	  "access_token": "string",
	  "token_type": "string",
	  "refresh_token": "string",
	  "expires_in": 0,
	  "id_token": "string"
	}
	

Errores 
Todas nuestras APIs responderán con los siguientes códigos de retorno:

HTTP Code Leyenda
200 Success
400 Bad Request
401 Missing/Invalid Access Token
403 Invalid Scope
404 Not Found
406 Invalid Accept Header
429 Quota Limit Exceeded
500 Internal Server Error

 

Formato de Respuesta de Error:

	{
	  "Error": {
		"Status": "string",
		"Code": "string",
		"Title": "string",
		"DeveloperMessage": "string",
		"Sources": {
		  "Parameter": "string"
		}
	  }
	}
	

Únete como partner

Una vez que has probado las APIs en modo Sandbox y habiéndolas integrado con tu aplicación puedes ir a la opción “Únete como partner” que encontras en el menú superior.

 

 

Esta sección del sitio te permitirá comunicarte con el equipo de API Program para convertirte en un Partner de Bci y comenzar a utilizar las APIs en tu aplicación con datos reales. 

Como generar Token JWT para llamada a oauth/token

El JWT Token requerido para invocar a la api-oauth y obtener un token, debe contener la siguiente información:

Header Payload
{
   "alg": "RS256",
   "expiresIn": "1h"
}
{
   "iss": {{tu_App_ID}},
   "credentials": {{tu_App_secret}}
}

 

Este token de solicitud de Access Request debe ser firmado por tu clave privada RSA. 

Como generar Token JWT para llamada a oauth/authorize

El JWT Token requerido para invocar a la api-oauth authorize y obtener el código del cliente, debe contener la siguiente información:

Header Payload
{
   "alg": "RS256",
   "expiresIn": "1h"
}
{
   "iss": "https://api.openbank.com",
   "response_type": "code",
   "client_id": {{tu_App_ID}},
   "redirect_uri": {{CallbackUrl}},
   "scope": {{scope}},
   "state": {{state}},
   "nonce": {{nonce}},
   "claims": {
      "id_token": {
         "openbanking_intent_id": {
            "value": "urn:openbank:intent:" + {{scope}} + ":" + {{requestId}},
            "essential": true
         },
      "acr": {
         "essential": true
         }
      }
   }
}
 

Donde su payload debe contener las credenciales API Key y Secret API Key, entregadas al momento de registrar una app en nuestro portal.

Este token de solicitud de Access Request debe ser firmado por tu llave privada RSA. 

Cómo generar un par de llave pública y llave privada 

 

El JTW mencionado en el paso anterior requiere de una llave privada. Esta se puede general como se indica a continuación.

Llave privada

Ejecuta en una consola el siguiente comando para generar tu llave privada
openssl genrsa -out private.pem 2048

Esto dejará un archivo llamado private.pem en la ruta en la que hayas ejecutado el comando. El archivo contendrá el string que corresponde a tu llave/clave privada. Utilizaras este string para generar  los JTW con los que consumirás las APIs.

Llave pública

Ejecuta en la consola dentro de la misma ruta anterior el comando: openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Esto dejará un archivo llamado public.pem en la ruta en la que hayas ejecutado el comando. El archivo contendrá el string que corresponde a tu llave pública. La utilizaras para registrar tu aplicación aquí en el API Market. 

 

GLOSARIO DE TÉRMINOS

Entorno Sandbox:
También llamado entorno de pruebas, es un ambiente con las mismas características que el productivo donde se pueden ejecutar las API con datos de prueba ficticios.

BCI ACCESS
Aplicación que garantiza la autenticación de clientes Bci para el otorgamiento de consentimientos a terceros sobre el uso de información personal; así como también, la comprobación de identidad con un segundo factor de seguridad.