Saltar al contenido principal

Roadmap

Guía de integración - API de Integración Financiera - Koncili

Esta guía presenta el flujo completo para la integración con la API de Integración Financiera de Koncili. Sigue los pasos en orden para implementar correctamente la integración en tu ERP

Información importante​

  • Rate Limit: 3 solicitudes por minuto en la API de conciliaciones.
  • Paginación: 100 registros por solicitud.
  • Ejecución: El proceso debe ejecutarse diariamente.
  • Buenas prácticas: Marca siempre los registros como leídos después de procesarlos.
  • Monitoreo: Monitoreamos el uso de la API y, si hay uso indebido, el acceso se bloqueará o adoptaremos políticas de cobro por acceso.

Flujo de integración​

1. Obtener las credenciales de acceso​

El primer paso es obtener el usuario y la contraseña para la autenticación en la API de Koncili. Consulta la página Flujo de autenticación para más información.

Importante

Guarda tus credenciales en un lugar seguro y nunca las compartas en repositorios públicos.

2. Autenticación y refresh token​

Realiza el proceso de conexión con la API y configura el sistema de refresh token para mantener la sesión activa.

Importante

Para saber más sobre la autenticación, accede a la documentación Autenticación para más información.

3. Obtener las conciliaciones no resueltas​

Usa la API para buscar las conciliaciones finalizadas y analizadas. Consulta para más información: Obtiene las conciliaciones no resueltas

GET/externalapi/orderextract/unresolveds
Observación

Esta API devuelve 100 registros por solicitud y tiene un rate limit de 3 solicitudes por minuto. Planifica tus llamadas adecuadamente.

Importante

Respeta el rate limit para evitar bloqueos temporales. Recomendamos implementar un control de solicitudes.

4. Anotar los IDs de los registros​

Extrae y almacena los IDs de los registros recibidos para usarlos en las siguientes etapas del proceso.

5. Marcar las liquidaciones como leídas​

Después de guardar los registros en tu ERP, márcalos como leídos en la API de Koncili por lotes. Consulta la página Actualiza liquidaciones en Koncili como leídas por lotes para más información.

PUT/externalapi/orderextract/read/batch

Request Body:

request.json
[
  49185461, 123132, 132123,2123
]
Observación

Después de guardar los registros en el ERP, marcarlos como leídos en Koncili es una buena práctica, pues evita leerlos de nuevo, además de no tener que desarrollar controles para leer los 100 registros siguientes.

6. Control del flujo diario​

Después de leer todos los registros del día, es decir, cuando la variable 'count' devuelva 0, detén el flujo de conexión con la API.

// Lógica de control
if (response.count === 0) {
    console.log("Todos los registros fueron procesados");
    // Programar la próxima ejecución para el día siguiente
    scheduleNextRun();
} else {
    // Continuar el procesamiento
    processNextBatch();
}
Importante

El flujo debe reiniciarse al día siguiente. Implementa una programación automática para ejecutar este proceso diariamente.

7. Resolver las liquidaciones en Koncili​

Inicia el procesamiento en el ERP aplicando el cobro de las cuentas por cobrar. Después de aplicarlo, marca los registros como resueltos en Koncili por lotes. Consulta la página Resuelve liquidaciones en Koncili por lotes para más información.

PUT/externalapi/orderextract/resolve/batch

Request Body:

request.json
[
  49185461, 123132, 132123,2123
]
Observación

Este es el paso final del flujo. Después de aplicar el cobro de las cuentas en el ERP, es esencial marcar los registros como resueltos en Koncili para mantener la sincronización.

API adicional: consultar los registros conciliados

Si necesitas consultar los registros ya conciliados (con el cobro aplicado en el ERP), usa esta API. Consulta la página Obtiene las conciliaciones resueltas

GET/externalapi/orderextract/concilieds

Esta API devuelve los registros que ya se marcaron como resueltos en el paso 7.