Paso a paso para consumir el producto de APIs Authorization

Para iniciar el consumo del producto de autorización el primer paso que debes realizar es descargarlo. Para ello ingresa al  API Market y luego dirígete a la sección de Documentación. Acá te mostramos cómo:

 

 

Es importante consultar la información mas relevante, y para realizar pruebas se necesitará la colección de Postman.

 

La información que recibe la API es:

• Cuerpo (Body)
  • grant_type: es el flujo de la aplicación, la aplicación solo recibe el parámetro client_credentials
  • scope: es el alcance que tendrá el token, dependerá de la operación que se va a consumir, se indicará donde consultarlo mas adelante.
• Cabeceras (Headers)
  • Content-Type: Es el tipo de contenido que recibirá la API, el parámetro correcto para generar el token es application/x-www-form-urlencoded.
  • Accept: es el tipo de contenido que se recibirá como respuesta del API, el parámetro correcto es application/vnd.bancolombia.v4+json.
  • Authorization: es la cabecera que comprueba las credenciales, se debe realizar una codificación a base64 de las credenciales, así: client-id:client-secret, se recomienda utilizar la página https://www.base64encode.org/. Luego de codificar la información se debe añadir el prefijo de Basic.

Esta información se debe consultar en el API Market. Allí se visualizan las distintas APIs, cada una requerirá un ámbito distinto, que se encontrará en el apartado de seguridad.

 

Tomemos como ejemplo el producto de Payment Button, que cuenta con una sola API y una sola operación, pero requiere de dos ámbitos que serán Transfer-Intention:write:app y Transfer-Intention:read:app

⚠ Importante: Es necesario que revises el apartado de seguridad antes de generar un token, pues algunos productos requieren información especifica, como es el caso del producto de Remesas (Consignments) que tiene una URL de señal distinta:

 

 

Es recomendable revisar cada operación para tener claro el tipo de seguridad que tiene, ya que no todos los productos requieren el token de authorization, algunas utilizan api key, JWT o varios métodos al mismo tiempo.

Cómo la operación POST/purchase-intention del API Payments Management del producto BNPL que usa tanto token de authorization, como JWT.

 

Te invitamos a explorar nuestros artículos sobre estos métodos de seguridad:

 

• ¿Qué es Json Web Token y cómo funciona?
• ¿Qué debo enviar cuando me solicitan el certificado de la aplicación?
• ¿Cuáles son las diferencias entre OAuth 2.0 y JWT?
• ¿Qué es API Key? 

 

Consumo de la API

Haremos el consumo desde la herramienta Insomnia, en caso de que no tengas claro cómo utilizar la herramienta te recomendamos revisar nuestra guía para entender mejor lo que se explicará a continuación.

 

⚠ Importante:  antes de empezar ten en cuenta que hay distintas formas en la herramienta de utilizar la autenticación, en este artículo solo se explicarán dos de ellas.

 

 

1. Importar la colección de peticiones a la herramienta

Al importar la colección descargada del API Market en la herramienta tendremos la siguiente vista:

 

 

En el primer apartado veremos la información relacionada con el cuerpo de la solicitud, por defecto trae el parámetro grant_type ya incluido, como se mencionó antes su valor será client_credentials. Luego se agregará el parámetro scope, que su valor dependerá del producto, continuando con el ejemplo tomaremos los valores de la API de Payment Button.

 

 

Luego podemos ver que no está incluido el Endpoint, por lo tanto tendremos que agregarlo.

 

 

Finalmente revisaremos las cabeceras de la solicitud:

 

 

Por defecto nos incluye la cabecera Content-Type con el valor requerido; entonces deberemos agregar las cabeceras de Accept y Authorization con sus respectivos valores.

 

 

Al enviar la solicitud recibiremos el token, y una información adicional.

 

 

Lo primero es código de respuesta "200 OK" que nos indica que la solicitud fue enviada correctamente, y el servicio la pudo procesar. En el cuerpo de la respuesta veremos los campos:

• token_type: nos indica el tipo de token, este es un prefijo que se debe incluir al momento de utilizar el token en el producto.
• access_token: es el token en cuestión.
• scope: nos indica el mismo valor que se envió en el cuerpo de la solicitud.
• expires_in: los token por motivos de seguridad tienen una duración limitada, por defecto son 1200 segundos o 20 minutos.
• consented_on: es la fecha de registro del token, codificada por motivos de seguridad.

 

2. Posibles errores

Se puede generar un error si se envía el cuerpo de la solicitud como un JSON. En este caso se debe corregir el cuerpo y enviarlo como URL Encode.

 

 

Otro posible error se genera cuando no envías el base64 y en su lugar envías las credenciales. El API nos indicará que falta el identificador del cliente, dado que no encuentra la cabecera de Authorization.

 

Luego de corregir los posibles errores al momento de generar el token, debemos utilizar el token que autoriza consumir productos según el ámbito con el que se haya generado el token. Continuando el ejemplo con el producto de Payment Button, se omitirá el detalle específico del producto y se explicará como utilizar el token.

 

3. ¿Cómo utilizar el token?

La herramienta nos brinda dos formas de utilizarlo, la primera es utilizando la segunda pestaña destinada a seguridad:

 

 

Seleccionamos como tipo de autorización Bearer Token, la herramienta tiene dos campos, uno para incluir el token y otro para incluir el prefijo, en este caso el prefijo será nuevamente Bearer.

 

 

La segunda opción es incluirlo en una cabecera, el nombre de la cabecera será Authorization, y en el campo se incluirá el prefijo Bearer y seguido el token.

 

 

Escoger una opción será a gusto personal, pero ambas, como se ve en los ejemplos funcionan, lo importante es completar los datos de la manera correcta. El error que podría generar en los productos es un 401 por un error de credenciales: