Visión general

El API v1 de Distribuidora Hosana es la interfaz entre el operador logístico de Jaremar y el sistema de distribución de Hosana (Grupo Olympo). Cubre dos flujos de negocio concretos:

1. Inserción de facturas — Jaremar envía a Hosana las facturas que debe distribuir, agrupadas por manifiesto.
2. Consulta de devoluciones — Jaremar consulta las devoluciones que Hosana procesó en bodega, para reconciliarlas.

Actores

Actor	Rol en la integración
Jaremar	Proveedor. Origina las facturas y consume las devoluciones. Consume este API.
Hosana	Distribuidor. Recibe facturas, las despacha por bodega y captura devoluciones.

El ciclo completo de una factura

flowchart LR
    A["Importación<br/>(API)"] --> B["Manifiesto<br/>(por bodega)"]
    B --> C["Ruta"]
    C --> D["Entrega"]
    D --> E["Devolución<br/>(bodega)"]
    E --> F["Depósito<br/>(banco)"]

    style A fill:#e7eaee,stroke:#5d636d,color:#23262c
    style E fill:#e7eaee,stroke:#5d636d,color:#23262c

La integración por API toca los dos extremos del ciclo (resaltados arriba): la importación (insertar facturas) y la devolución (consultar devoluciones). Lo que ocurre entremedio —ruteo, entrega, captura de devoluciones, depósitos— sucede dentro del sistema de Hosana y no se expone por API.

Quién llama a quién

sequenceDiagram
    autonumber
    participant J as Jaremar
    participant H as API Hosana
    J->>H: POST /facturas/insertar (lote del día)
    H-->>J: 200 resumen (insertadas, rechazadas, ...)
    Note over H: Hosana rutea, entrega y<br/>captura devoluciones en bodega
    J->>H: GET /devoluciones/listar (Fecha: dd/MM/yyyy)
    H-->>J: 200 array de devoluciones aprobadas

Las tres bodegas

Toda factura pertenece a una bodega de Hosana, identificada por su código:

Código	Bodega	Departamento (Honduras)
OAC	Copán	Copán
OAS	Santa Bárbara	Santa Bárbara
OAO	Ocotepeque	Ocotepeque

El código de bodega viaja en el campo Almacen de cada factura. Si Jaremar envía un código que no existe en Hosana, ese manifiesto se rechaza (ver catálogo de errores).

Conceptos clave

Manifiesto. Agrupa las facturas de un lote de carga. Lo identifica el campo NumeroManifiesto. Un manifiesto puede contener facturas de fechas distintas (la mezcla está permitida), pero cada factura debe tener una fecha válida (ni futura ni de más de 30 días; ver reglas de fecha). Una vez creado, un manifiesto no acepta facturas nuevas en días posteriores.

Batch / lote. Una sola llamada a insertar puede traer facturas de varios manifiestos distintos. A ese conjunto lo llamamos batch. Si cualquier manifiesto del batch falla ciertas validaciones tempranas, se rechaza el batch completo — no se procesa parcialmente.

Factura. Identificada por Nfactura. Una factura solo puede pertenecer a un manifiesto. Si Jaremar intenta reenviar una factura que ya existe bajo otro manifiesto, se rechaza.

Devolución. En Hosana las devoluciones son absolutas: se auto-aprueban al registrarse en bodega. El API solo expone las devoluciones ya aprobadas.

Versionado

Todos los endpoints viven bajo el prefijo /api/v1/. La versión es parte de la ruta, de modo que una futura v2 podrá convivir con v1 sin romper la integración actual.