Flujo de devoluciones

Esta guía explica cómo Jaremar debe consumir el endpoint de devoluciones para reconciliar lo que Hosana procesó en bodega.

El ciclo de una devolución

flowchart LR
    A["Factura<br/>entregada"] --> B["Cliente devuelve<br/>en bodega"]
    B --> C["Hosana captura<br/>(se auto-aprueba)"]
    C --> D["Jaremar consulta<br/>GET /devoluciones/listar"]
    D --> E["Reconciliación<br/>en Jaremar"]

    style C fill:#e7eaee,stroke:#5d636d,color:#23262c
    style D fill:#e7eaee,stroke:#5d636d,color:#23262c

En Hosana las devoluciones son absolutas: se aprueban automáticamente al registrarse en bodega. Por eso, en cuanto se captura una devolución, queda disponible para que Jaremar la consulte.

Consulta diaria recomendada

Consulta las devoluciones procesadas de cada fecha al cierre del día (o al inicio del día siguiente). La fecha en el header Fecha (dd/MM/yyyy) corresponde a la fecha de procesado (fechaProcesado), no a la fecha de la factura original.

Para los ejemplos de código en PHP, Node y C#, ver el endpoint de devoluciones.

Paginación

Cada página trae hasta 1000 devoluciones. Para recorrer todo:

flowchart LR
    A[pagina = 1] --> B[GET ...?pagina=pagina]
    B --> C{recibió 1000?}
    C -- sí --> D[pagina = pagina + 1]
    D --> B
    C -- no --> E([terminar])

    style E fill:#dcf3e3,stroke:#1f8a4c,color:#14532d

Reconciliación: cantidades

Al reconciliar las líneas, recuerda la regla de cajas vs. unidades del campo cantidad:

Producto por caja (CJ): cantidad es el número de cajas devueltas.
Producto por unidad (UN): cantidad es el número de unidades devueltas.

Si tu sistema maneja todo en una sola unidad, usa el FactorConversion que enviaste al insertar la factura para convertir cajas a unidades cuando corresponda. (Ver esquema de la línea.)

Idempotencia y consistencia

El endpoint es de solo lectura: consultarlo varias veces no tiene efectos secundarios.
Las respuestas se cachean (60 min para fechas pasadas, 5 min para hoy), pero la caché se invalida automáticamente cuando se registra o aprueba una devolución de esa fecha. No recibirás datos obsoletos.
Si un administrador de Hosana cancela una devolución por error de captura, esa devolución desaparece del listado en la siguiente consulta. Por eso, para fechas recientes conviene una consulta final de confirmación al cabo de uno o dos días.

Campos clave para la reconciliación

Campo	Úsalo para…
`devolucion`	Identificar de forma única la devolución (idempotencia de tu lado).
`factura`	Vincular con la factura original (`Nfactura`).
`numeroManifiesto`	Vincular con el manifiesto.
`idConcepto` / `concepto`	Clasificar el motivo de la devolución.
`total` / `lineTotal`	Cuadrar montos.
`fechaProcesado` / `horaProcesado`	Ubicar la devolución en el tiempo.