Introducción a la API de datos abiertos de Khipu

Suponiendo que ya tiene acceso a la API de datos abiertos de Khipu (consulte nuestro sitio web principal para obtener más información sobre cómo registrarse), en esta sección se explica cómo puede empezar a explorar y crear soluciones utilizando nuestros servicios.

Conceptos clave

Solicitud autenticada

Antes de poder acceder a cualquiera de los recursos disponibles es necesario obtener una clave de autenticación válida, en forma de clave Api. Cada método se explica en la sección Autenticación. No proporcionar una clave válida resultará en una petición errónea.

Callback URL

Puedes especificar un valor Callback URL en cada una de tus peticiones para recibir los datos en un servicio configurado por ti. De esta forma, tu petición se ejecutará a través de un proceso asíncrono, y los datos serán push tan pronto como se obtengan. Consulta la definición de cada método para saber cuáles soportan esta característica (habrá servicios que sólo funcionarán en modo asíncrono, debido al tiempo necesario para procesar los datos).

Utilizar esta opción es la forma preferida de interactuar con nuestros servicios, ya que asegura que se hará todo lo posible por extraer los datos para satisfacer su petición en un plazo de tiempo razonable. Si desea la respuesta inmediatamente y ejecutar el servicio en modo síncrono, omita el campo CallbackUrl pero tenga en cuenta que puede dar lugar a tiempos de espera dependiendo del tamaño del resultado de los datos y de las condiciones de la red.

Para recibir los datos en su endpoint, recuerde:

• Utilizar una URL pública disponible (nuestro servicio push no funcionará si estás ejecutando un servicio con autenticación).
• Su servicio debe ser RESTful, y aceptar el verbo POST .
• Tu servicio debe ser capaz de entender y analizar el JSON que nuestra API le enviará. Comprueba el esquema de respuesta con código de estado HTTP 200 para el método que quieres llamar de forma asíncrona.
• Mantenga un registro de su valor OperationId , ya que servirá para cotejar su solicitud con la respuesta final, y también con fines de soporte y seguimiento.

Duración

Cuando realiza una petición asíncrona, se muestra una respuesta inmediata que contiene un campo LifeSpan que indica el tiempo máximo de que dispone nuestro servicio para enviar los datos a su URL de callback definida. Puede esperar que la respuesta se entregue dentro de este plazo (normalmente será mucho antes). Si algo impide que nuestro servicio se complete con éxito, la respuesta que reciba contendrá la descripción del error, tal y como se detalla en la sección Errores.

Entorno de pruebas

Para determinadas fuentes de datos, ofreceremos un entorno de pruebas con datos ficticios para que pueda probar sus desarrollos e integraciones sin tener en cuenta las solicitudes en la cuota/facturación de su cuenta. Por favor revisar la sección Sandbox para más detalles.

Preparando la primera solicitud

Usaremos un método en la ruta Chile/Banca/Personas/DemoBank como ejemplo para mostrar cómo puedes comenzar a realizar solicitudes en menos de 10 minutos, sin necesidad de una sola línea de código. Comprender este sitio de documentación lo pondrá en un buen camino para integrar nuestras API en sus soluciones.

Las definiciones de OpenAPI se encuentran en la sección API Open Data de la barra lateral izquierda:

Puede expandir el árbol del menú y navegar hasta el servicio deseado. Queremos utilizar el método Transactions de DemoBank:

La sección principal de la documentación tiene tres secciones: Seguridad, Solicitud y Respuestas:

Léalos atentamente para comprender los esquemas y los tipos y longitudes de datos que puede utilizar en sus solicitudes. La solicitud necesita los datos de la cuenta bancaria (credenciales de usuario, normalmente). No usaremos el campo opcional CallbackUrl, ya que queremos ver los datos en la consola.

Si llama al servicio de forma sincrónica (sin el campo CallbackUrl), una respuesta correcta tendrá un código de estado HTTP 200 (el código 202 está reservado para las llamadas asincrónicas). Puede ver los detalles del objeto de respuesta y ejemplos:

La sección de la derecha tiene una consola "Try It" donde puedes ver el servicio en acción. Al pulsar el botón se abrirá el panel de Solicitud/Respuesta, para que puedas verificar su correcto funcionamiento.

Autenticación

Una vez abierto, el panel "Try It" muestra las secciones Security, Body y Target server. Comencemos con Seguridad, eligiendo "Api-Key" en la lista desplegable "Security scheme" disponible:

Cuando ingresa su clave asignada, el candado se vuelve verde y las credenciales se mantienen en su navegador durante la sesión:

Está todo listo para ajustar el contenido del cuerpo.

Completando la solicitud

En "Body", se ofrece una solicitud de muestra con todos los campos disponibles, usaremos "AccountLink" y "AccountNumber", y omitiremos "CallbackUrl" ya que no queremos realizar una llamada asincrónica. Como nota al margen, puede utilizar "Username" y "Password" en lugar de "AccountLink". Para crear un enlace de cuenta reutilizable para la cuenta, vaya a Generador de Account link.

Con todo listo, seleccionas el servidor que deseas ("Production", para este ejemplo) y le das al botón "Send" 🚀.

Procesando la respuesta

Al finalizar, la solicitud cambia a la pestaña "Response" y podrá ver el resultado. En este caso era un código de estado 200. En el cuerpo, "Status": "OK" indica que el servicio funcionó bien y OperationId muestra el identificador único para esta solicitud. El elemento Data tiene todas las transacciones realizadas durante el día actual.

Siguientes pasos

Si nunca antes usó API RESTful, en "Request samples" de la sección derecha de cada definición de servicio encontrará fragmentos de código personalizados en lenguajes de programación populares (también curl) para ayudarlo con su solución. Solo recuerde usar siempre un encabezado para autenticar su solicitud (x-api-key) y otro encabezado para Content-Type: application/json.