Preguntas frecuentes - API de Integración Financiera

1. ¿Cuándo quedan disponibles las conciliaciones en la API para la aplicación del cobro?

   Las conciliaciones quedan disponibles solo después del procesamiento completo del Archivo de Liquidación en Koncili. Esto garantiza que los datos ya se validaron y se cruzaron con los pedidos.

2. ¿Qué es conciliar?

   Conciliar es el acto de comparar la información de un mismo pedido en diferentes fuentes - marketplace, archivo de liquidación - para garantizar que haya coherencia.

   Pero existen dos tipos de conciliación que suelen confundirse:

   • La conciliación financiera, que es la de Koncili.
   • La conciliación comercial, que es típica de las áreas de ventas, planificación o estrategia.

   Entender esta diferencia es esencial, porque las dos miradas generan expectativas diferentes - y muchas veces ese es el motivo de confusión entre los usuarios.

3. ¿Qué es exactamente una conciliación financiera?

   Es el proceso de comparar el monto prometido por el marketplace con el monto efectivamente liquidado.
   Si el marketplace informó que pagaría R$ 1.000 y liquidó R$ 980, Koncili señala R$ 20 de diferencia, independientemente del motivo.

   📌 El foco es financiero y objetivo: cuánto entró, cuánto faltó.

4. ¿Y qué es la conciliación comercial?

   La conciliación comercial analiza si el marketplace cumplió lo acordado en términos de reglas, tarifas y comisiones.
   Por ejemplo: el contrato preveía un 10% de comisión, pero la liquidación vino con un 12%.
   El marketplace puede tener razón según sus reglas, pero comercialmente hay una divergencia estratégica.

5. ¿Koncili hace conciliación comercial?

   No.
   Koncili es financiero por esencia: muestra la verdad contable y operativa - lo que realmente se pagó.
   Los análisis comerciales pueden hacerse a partir de estos datos, pero no interfieren en el cálculo de la conciliación. Los Dashboards de Comisión, Campaña y Pendientes pueden ayudar en estos análisis.

6. ¿Puedo automatizar el proceso de aplicación del cobro?

   Sí.
   El ERP puede consumir los endpoints de conciliaciones pendientes (/unresolveds), procesar la aplicación de los cobros y enviar el resultado mediante el endpoint de resolución por lotes (/ resolve/batch).

   Esta automatización se recomienda para sellers con un alto volumen de pedidos.

7. ¿Puedo aplicar el cobro por el monto total de la venta?

   Sí. En ese caso, el ERP registra solo el monto bruto (SALE) en las cuentas por cobrar, y los gastos (comisión, envío, penalidad, etc.) deben registrarse por separado en las cuentas por pagar.

8. ¿Cuál es la forma recomendada de aplicar los cobros?

   Koncili recomienda la aplicación del cobro por el monto neto recibido, pues este modelo garantiza mayor transparencia, evita divergencias con el extracto del marketplace y facilita las auditorías contables.

9. ¿Qué pasa si el ERP no devuelve el estado de la aplicación del cobro?

   Mientras el ERP no confirme el estado (p. ej.: RESUELTO), Koncili seguirá considerando esa conciliación como no resuelta. Esto puede generar retrabajo e inconsistencias.

10. ¿Cuáles son los estados posibles en una aplicación del cobro?

    • PENDIENTE → Aplicación del cobro aún no procesada por el ERP
    • RESUELTO → Aplicación del cobro concluida con éxito en el ERP
    • DIVERGENTE → Hubo una diferencia entre el monto esperado y el monto registrado
    • IGNORADO → El registro no será tratado por el ERP (casos específicos)

11. ¿Puedo procesar varias aplicaciones de cobro a la vez?

    Sí. La API ofrece endpoints de acciones por lotes, que permiten resolver o marcar como leídas múltiples liquidaciones en una única solicitud.

12. ¿Cómo sé qué tipos de liquidación puede generar un marketplace?

    Usa el endpoint:

    GET /externalapi/releasetype/:channelName

    Devuelve todos los tipos de movimientos (SALE, COMISSION, SHIP, etc.) configurados para el marketplace.

13. ¿Necesito homologar mi integración aunque sea un seller con desarrollo propio?

    Sí. Tanto los socios integradores como los sellers con desarrollo propio deben pasar por el proceso de homologación antes de acceder al ambiente de producción.

14. ¿Cómo funciona el movimiento de envío (SHIP / RETURN_SHIP)?

    • SHIP → puede representar tanto el monto del envío pagado por el cliente y liquidado al seller como un costo de envío descontado.
    • RETURN_SHIP → se refiere a la reversión del envío en casos de devolución o cancelación.

    👉 La forma de aplicar el cobro depende de si tu contabilidad considera el envío como ingreso (cuando se liquida) o gasto (cuando se cobra).

15. ¿Cómo debo tratar las devoluciones (RETURN_SALE / DEVOLUTION)?

    • RETURN_SALE → corresponde a la reversión total o parcial de una venta ya conciliada.
    • DEVOLUTION → monto neto devuelto al marketplace (p. ej.: venta cancelada después de la liquidación).

    👉 Es importante que el ERP registre estos montos para mantener el saldo neto alineado con el extracto del marketplace.

16. ¿Qué son los gastos no vinculados directamente al pedido (p. ej.: PENALTY)?

    • PENALTY → son multas aplicadas por el marketplace, generalmente por retraso o cancelación.
      Estos gastos no están vinculados al flujo normal de venta/reversión, pero deben registrarse para reflejar la realidad financiera.

    👉 Lo ideal es que el ERP tenga una cuenta contable propia para penalidades o gastos operativos de marketplace.

17. ¿Y si el marketplace crea un tipo de movimiento que aún no existe en Koncili?

    Koncili actualiza constantemente los tipos de liquidación por canal. Si surge un movimiento nuevo, podrá aparecer vía API.
    👉 Recomendamos que el ERP esté preparado para tratar nuevos tipos dinámicamente, usando siempre el endpoint /releasetype/:channelName como referencia actualizada.

18. ¿Cómo funciona la aplicación del cobro cuando la venta fue en cuotas, pero el marketplace anticipa la liquidación?

    En algunos marketplaces, el cliente puede comprar en cuotas (p. ej.: 10 cuotas con tarjeta), pero la liquidación al seller se hace de forma anticipada, como si fuera al contado.

    En estos casos:

    • El marketplace ya descuenta las tarifas financieras de anticipación en el momento de la liquidación.
    • El seller recibe el monto neto en una única cuota, aunque el cliente todavía vaya a pagarle al marketplace en varias cuotas.
    • En el ERP, la aplicación del cobro debe reflejar el monto efectivamente recibido, y no el flujo original de las cuotas del cliente.

    👉 Cómo registrarlo en el ERP:

    • Modelo 1 - Total de la venta:
      • Registrar el monto bruto como ingreso y contabilizar la tarifa de anticipación como gasto financiero.
    • Modelo 2 - Monto neto recibido (recomendado):
      • Registrar solo el monto neto ya descontada la tarifa, garantizando que las cuentas por cobrar reflejen el monto real que entró en caja.

    📌 Ejemplo práctico:

    • Venta: R$ 1.000,00 en 10 cuotas
    • Tarifa de anticipación: R$ 50,00
    • Liquidación al seller: R$ 950,00 (al contado)

    En el ERP:

    • Ingreso por venta: R$ 1.000,00
    • Gasto financiero (anticipación): R$ 50,00
    • Liquidación neta recibida: R$ 950,00

19. ¿Qué pasa con las cuentas por cobrar cuando una venta se cancela después de la emisión de la nota fiscal?

    Cuando una venta se cancela después de la emisión de la NF, el seller puede haber registrado ya el monto en las cuentas por cobrar. En este escenario, es necesario ajustar la contabilización para reflejar la cancelación:

    • En Koncili:
      • La cancelación aparece como un movimiento de tipo RETURN_SALE o DEVOLUTION, según el canal.
      • Este movimiento reduce el saldo neto esperado.
    • En el ERP - Tratamiento recomendado:
      • Aplicar el cobro del documento por cobrar original registrado en las cuentas por cobrar (el monto de la venta).
      • Generar la reversión/cancelación correspondiente, para que el ingreso no quede abierto.
      • Registrar la NF de devolución (cuando corresponda), garantizando que el efecto fiscal también se ajuste.

    📌 Ejemplo práctico:

    • Venta original: R$ 500,00 (nota emitida, documento por cobrar creado en las cuentas por cobrar).
    • Cancelación registrada por el marketplace: RETURN_SALE - R$ 500,00.

    👉 En el ERP:

    • Cuentas por cobrar: documento por cobrar de R$ 500,00 con el cobro aplicado.
    • Ingreso: revertido mediante reversión/cancelación.
    • (Si corresponde) NF de devolución registrada.

    ⚠️ Punto de atención:
    Cada empresa puede tener su propia política para tratar las cancelaciones, pero lo más importante es no dejar documentos por cobrar "abiertos" en las cuentas por cobrar que nunca se liquidarán. Esto distorsiona el flujo de caja y el estado de resultados (DRE).

20. ¿Qué hacer si el monto liquidado por el marketplace es diferente del registrado en el ERP (p. ej.: ventas en cuotas con redondeo)?

    En las ventas en cuotas, es común que haya pequeñas diferencias de redondeo entre el monto de la venta registrado en el ERP y el monto efectivamente liquidado por el marketplace.

    📌 Ejemplo práctico:

    • Monto de la venta: R$ 997,37
    • En 7 cuotas → cada cuota calculada por el marketplace puede resultar en decimales diferentes, p. ej.: R$ 142,48 por cuota.
    • 7 x 142,48 = R$ 997,36 → diferencia de R$ 0,01 con respecto al monto original.

    🔹 Cómo lo trata Koncili

    Koncili captura el monto exactamente como lo informa el marketplace en la liquidación.
    Por lo tanto, el monto conciliado puede presentar diferencias mínimas (centavos) con respecto al pedido registrado en el ERP.

    🔹 Cómo debe tratarlo el ERP

    Lo ideal es adoptar una política contable para lidiar con las diferencias de redondeo:

    • Tolerancia de centavos
      • Si la diferencia es pequeña (p. ej.: hasta R$ 0,05 por pedido), el ERP puede aceptar como válido el monto liquidado por el marketplace.
      • El ajuste debe contabilizarse en una cuenta de Diferencias de redondeo o Ajustes financieros.
    • Reversión parcial (si la divergencia es mayor)
      • Si la diferencia es significativa (por encima de la tolerancia definida por la contabilidad), la conciliación debe señalarse como DIVERGENTE.
      • El ERP debe registrar el ajuste y notificar a la contabilidad.

    ⚖️ Buenas prácticas recomendadas

    • Definir una política de tolerancia en el ERP para las diferencias de centavos (p. ej.: hasta R$ 0,05 o 0,1% del monto de la venta).
    • Mapear una cuenta contable específica para registrar las diferencias de redondeo, manteniendo consistentes el estado de resultados (DRE) y el flujo de caja.
    • Auditar regularmente las diferencias acumuladas, principalmente en ventas en cuotas de alto volumen.

    👉 En resumen:

    • Diferencias pequeñas = ajustar automáticamente en la cuenta de redondeo.
    • Diferencias relevantes = marcar como divergencia y tratar manualmente.

21. ¿Por qué, al hacer la llamada a la API, recibo la respuesta {"response": "NO_TOKEN", "operation": "NOOP"}?

    Esta respuesta indica que el token de autenticación (gumgaToken) expiró o no se envió correctamente en el header de la solicitud.

    📌 Motivo:

    • El gumgaToken tiene una validez de 2 horas. Después de ese período, se vuelve inválido y la API no autoriza nuevas llamadas.

    ✅ Cómo resolverlo:

    1. Vuelve a realizar la autenticación en el endpoint POST /public/api/auth/token para generar un nuevo token válido.

    2. Actualiza el header de las siguientes solicitudes con el nuevo gumgaToken.

    💡 Se recomienda que el ERP implemente un mecanismo automático de refresh del token antes de su vencimiento (p. ej.: cada 100-110 minutos) para evitar interrupciones en la comunicación.

22. ¿Por qué recibo el error 403 (Forbidden) aunque el token sea válido?

    Esto ocurre porque la IP de origen de la solicitud no está habilitada para el token usado.

    📌 Motivo:

    • La API Koncili vincula cada token a una lista específica de IPs autorizadas. Si tu IP no está registrada, el acceso se bloqueará.

    ✅ Cómo resolverlo:

    1. Verifica las IPs habilitadas: GET /externalapi/ip-segmentation

    2. Habilita tu IP actual: POST /externalapi/ip-segmentation

    {
      "ip": "TU.IP.DE.ACCESO"
    }

    3. Elimina las IPs antiguas (opcional): DELETE /externalapi/ip-segmentation

    {
      "ip": "IP.A.ELIMINAR"
    }

    💡 Después de agregar la IP, espera algunos minutos a que se propague el permiso antes de hacer nuevas llamadas.

    En casos de IP dinámica, comunícate con erp@koncili.com