Saltar al contenido principal

Buenas prácticas

Esta página reúne las mejores prácticas para garantizar una integración robusta y eficiente con la API Koncili, evitando errores comunes y optimizando el flujo de conciliación financiera.

1. Validación anticipada de pedidos​

Antes de enviar los movimientos de una conciliación, verifica siempre si los pedidos/ítems existen en el sistema. Esto evita fallas en el proceso y garantiza que solo se procesen transacciones válidas.

Cómo validar:

  • Usa el endpoint GET /order para consultar los pedidos/ítems antes de enviar el movimiento
  • Confirma que marketplaceCode y accountId sean correctos
  • Verifica que el estado del pedido esté dentro de los esperados

2. Garantía de consistencia en los movimientos​

Al enviar los movimientos (releases), deben corresponder a los extracts registrados en los ítems del pedido original

Reglas esenciales:

  1. Mismos tipos:

    • Si el ítem del pedido tiene SALE, el movimiento también debe tener SALE

  2. Mismo marketplaceCode:

    • El código del pedido/ítem debe ser idéntico en el movimiento

  3. Envío completo en una única solicitud:

    • No envíes movimientos parciales. Todos los componentes (SALE, COMISSION, SHIP, etc.) deben incluirse de una sola vez
Valores de los movimientos

Si el valor enviado en los movimientos (releases) no corresponde exactamente al valor prerregistrado en el ítem (extracts), la conciliación se consolidará, pero con divergencia, lo que generará una alerta para análisis posterior.

3. Gestión de períodos y lotes​

La conciliación agrupa pedidos/ítems en un período definido, y esa agrupación debe ser consistente.

Buenas prácticas:

  • Define períodos claros:
    • periodInitDate y periodEndDate deben cubrir todas las fechas de los movimientos; recuerda que Koncili no acepta conciliaciones con períodos superpuestos
  • Revisa la cantidad de movimientos (releasesQtd):
    • Este valor debe ser exactamente igual al total de releases que se enviarán
Riesgos si se ignora
  • Conciliaciones rechazadas por inconsistencia en releasesQtd
  • Error en el proceso de conciliación

4. Manejo de errores y reintentos​

¿Cómo lidiar con los errores?

Implementa reintentos inteligentes:

  • Para errores 4xx, espera antes de intentar de nuevo

  • Usa un backoff exponencial

  • Registra las fallas persistentes:

    • Si un movimiento falla repetidamente, verifica si la información existe en Koncili

5. Monitoreo y logs​

Mantener registros detallados ayuda a identificar y corregir problemas rápidamente.

Recomendaciones

Registra:

  • Timestamps de los envíos
  • IDs de conciliaciones y pedidos/ítems
  • Respuestas de la API (éxitos/errores)

Monitorea:

  • Pedidos/ítems no conciliados
  • Discrepancias entre extracts y releases
¡Importante!

Almacenamiento del X-Trace-ID:

Cada una de las solicitudes a la API de Koncili devolverá en el header un valor único de X-Trace-ID, excepto las solicitudes de autenticación.

Registra y almacena el X-Trace-ID devuelto en todas las respuestas de la API Koncili. Este identificador único es crucial para:

  • Rastreo de transacciones
  • Solución ágil de problemas
  • Auditoría