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:

Value

  • application/x-www-form-urlencoded

Required

  • Yes

Value

  • client_credentials

Required

  • Yes

Value

  • {{CallbackUrl}} Url especificada como Url de devolución de llamada
    en el API Market para tu aplicación

Required

  • Yes

Value

  • {{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

Required

  • Yes

Value

  • urn:ietf:params:oauth:client-assertion-type:jwt-beare

Required

  • Yes

Value

  • {{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.

Required

  • 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:

Value

  • Bearer {{access_token}}, donde {{access_token}} es el token recibido en el paso anterior

Required

  • Yes

Value

  • application/x-www-form-urlencoded

Required

  • Yes

Value

  • application/json

Required

  • Yes

Value

  • 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".

Required

  • 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]

Value

  • application/x-www-form-urlencoded

Required

  • Yes

Value

  • {{CallbackUrl}} Url especificada como Url de devolución de llamada
    en el API Market para tu aplicación

Required

  • Yes

Value

  • {{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

Required

  • Yes

Value

  • urn:ietf:params:oauth:client-assertion-type:jwt-beare

Required

  • Yes

Value

  • {{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.

Required

  • 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:

Value

  • application/json

Value

  • {{tu_App_ID}}: Es el App ID o también llamado Consumer Key que te entrega el API Market
    al registrar tu aplicación.

Value

  • {{tu_App_ID}}: Es el App ID o también llamado Consumer Key que te entrega el API Market
    al registrar tu aplicación.

Value

  • code

Value

  • {{CallbackUrl}}: Url que especificaste como url de devolución de llamada en el API Market
    para tu aplicación.

Value

  • {{state}}: uuid v.1 generado para esta transacción

Value

  • {{nonce}}: uuid v.1 generado para esta transacción

Value

  • {{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"

Value

  • {{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:

Value

  • application/x-www-form-urlencoded

Required

  • Yes

Value

  • refresh_token

Required

  • Yes

Value

  • {{client_id}}: valor del apikey

Required

  • Yes

Value

  • {{code}}: valor del api secret

Required

  • Yes

Value

  • {{refresh_token}}: valor del refresh obtenido en el paso 4

Required

  • 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:

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:

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:

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.