Open Finance
/
Access Token
Última actualización

Access Token

Un Access Token (token de acceso) es el mecanismo que se utiliza en Khipu para permitir que los propietarios de la información otorguen su consentimiento para acceder a sus datos.

Para las APIs de OpenData de Khipu, existen dos casos de uso principales:

  1. Quieres interactuar con nuestras APIs en nombre tuyo o de tu organización. Por ejemplo, para obtener los estados de cuenta bancarios de tu propia empresa desde uno de tus bancos.

  2. Quieres interactuar con nuestras APIs en nombre de tus usuarios. Por ejemplo, deseas usar nuestras APIs en el proceso de incorporación (onboarding) de tu aplicación.

Descripción general

Es un flujo de tres pasos que puede resumirse de la siguiente manera:

  1. Usa el endpoint /link/token/create para obtener un LinkToken.
  2. Lanza un widget khipu utilizando LinkToken para permitir que los usuarios generen un PublicToken temporal.
  3. Usa el endpoint /public/token/exchange para intercambiar el PublicToken por un AccessToken de larga duración

Guía paso a paso

Vamos a profundizar en los detalles de cada paso.

Paso uno: Obtener un LinkToken

Para obtener un LinkToken, deberás llamar al endpoint /link/token/create para alguna de las instituciones disponibles.

Ejemplo de Request

POST https://api.khipu.com/link/token/create
Content-Type: application/json
x-api-key: <A VALID API-KEY>

{
  "InstitutionId": "<VALID INSTITUTION ID>"
}

Ejemplo de Respuesta

{
  "OperationId": "<A large string>",
  "Status": "OK",
  "Data": {
    "LinkToken": "<A very large string>"
  },
  "AdditionalInformation": null,
  "Error": null,
  "LifeSpan": null
}

Acá presentamos una lista de las instituciones actualmente disponibles:

  • Chile
    • Banca
      • Business
        • Banco BICE: cl_banking_business_bancobice
        • Banco de Chile: cl_banking_business_banconexion
        • BancoEstado: cl_banking_business_bancoestado
        • Banco Internacional: cl_banking_business_bancointernacional
        • Banco Santander: cl_banking_business_bancosantander
        • Banco Security: cl_banking_business_bancosecurity
        • BCI: cl_banking_business_bancobci
        • Consorcio: cl_banking_business_bancoconsorcio
        • Itaú: cl_banking_business_bancoitau
        • Scotiabank: cl_banking_business_bancoscotiabank
      • Entrepreneur
        • BCI: cl_banking_entrepreneur_bancobci
      • Personal
        • Demobank
        • Banco BICE: cl_banking_personal_bancobice
        • Banco de Chile: cl_banking_personal_bancochile
        • BancoEstado: cl_banking_personal_bancoestado
        • Banco Falabella: cl_banking_personal_bancofalabella
        • Banco Ripley: cl_banking_personal_bancoripley
        • Banco Santander: cl_banking_personal_bancosantander
        • Banco Security: cl_banking_personal_bancosecurity
        • BCI: cl_banking_personal_bancobci
        • Consorcio: cl_banking_personal_bancoconsorcio
        • Itaú: cl_banking_personal_bancoitau
        • Scotiabank: cl_banking_personal_bancoscotiabank
        • Copeuch: cl_banking_personal_bancocoopeuch
    • Servicios
      • AFC: cl_services_afc
      • CMF: cl_services_cmf
      • RNDPA: cl_services_rndpa
      • SII: cl_services_sii
      • TGR: cl_services_tgr

Paso dos: Permitir que el usuario genere un PublicToken

Con el LinkToken generado en el paso anterior, debes invocar el Khipu Web Widget (KWS), donde el usuario final ingresará sus credenciales y otorgará su consentimiento para acceder a los datos, generando así un PublicToken.

Para hacerlo, sigue estos pasos:

Incluye la biblioteca de KWS en tu página

<head>
    ...
    <script src="https://js.khipu.com/v1/kws.js"></script>
    ...
</head>

Agrega un elemento ancla

<div id="khipu-web-root"></div>

Configura un Widget Khipu

<script>
    // Define a callback function to handle the result
    const callback = (result) => {
      console.log('Callback handler', result);
      // Send the result to your backend
      sendTheResultToMyBackend(result);
    };

    let khipu = new Khipu();
    const options = {
        mountElement: document.getElementById('khenshin-web-root'), // the anchor element
        modal: true, // Set to false if you want it embedded
        modalOptions: {
          maxWidth: 450,
          maxHeight: 750,
        },
        options: {
          style: {
              primaryColor: '#8347AD',
              fontFamily: 'Roboto',
          },
        },
    }
    khipu.init(options, callback);
</script>

Si el usuario completa con éxito el proceso de autenticación y otorga su consentimiento, el result será un objeto JSON con la siguiente estructura:

{
  "OperationId": "<A large string>",
  "Status": "OK",
  "Data": {
    "PublicToken": "<A very large string>"
  },
  "AdditionalInformation": null,
  "Error": null,
  "LifeSpan": null
}

Por otro lado, si el usuario encuentra una falla o error, e result tendrá la siguiente estructura:

{
  "OperationId": "<A large string>",
  "Status": "OK",
  "Data": null,
  "AdditionalInformation": null,
  "Error": {
    "Code": "<An error code>",
    "Type": "DO_NOT_RETRY",
    "Description": "<An explanation of the error that you can show to your user>"
  },
  "LifeSpan": null
}

Inicia el Khipu Widget con el LinkToken del Paso Uno

<script>
  // Pass the LinkToken obtained in Step One as an argument
  khipu.getPublicToken(<LinkToken>);
</script>

El PublicToken será recibido por la función callback que hayas proporcionado, y deberás enviarlo a tu backend para su procesamiento posterior.

Paso tres: Intercambiar el PublicToken por un AccessToken

Finalmente, necesitarás intercambiar el PublicToken generado en el Paso dos por un AccessToken de larga duración. Para eso, simplemente haz un POST request al endpoind /public/token/exchange.

Ejemplo Request

POST https://api.khipu.com/public/token/exchange
Content-Type: application/json
x-api-key: <A VALID API-KEY>

{
"PublicToken": "<The PublicToken obtained in Step Two>"
}

Ejemplo Response

{
  "OperationId": "<A large string>",
  "Status": "OK",
  "Data": {
    "AccessToken": "<A very large string>"
  },
  "AdditionalInformation": null,
  "Error": null,
  "LifeSpan": null
}

A partir de ahora, puedes utilizar el AccessToken en todos los endpoints de las APIs de OpenData de Khipu para interactuar en nombre de ese usuario con la institución correspondiente.

Anterior
Siguiente