API Distribuidora Hosana

Documentación técnica del API v1 para la integración entre Jaremar y Distribuidora Hosana.

El API tiene dos usos: Jaremar envía las facturas que Hosana debe distribuir, y consulta las devoluciones que Hosana procesa en bodega. Esta documentación cubre ambos, más los endpoints de apoyo (health check y consulta de estado de un manifiesto).

flowchart LR
    J["Jaremar"]
    subgraph H["Hosana · API v1"]
        direction TB
        I["Importación"] --> M["Manifiesto<br/>por bodega"]
        M --> R["Ruta y entrega"]
        R --> D["Devolución"]
    end
    J -- "POST /facturas/insertar" --> I
    D -- "GET /devoluciones/listar" --> J

Empezar

Inicio rápido De cero a tu primera factura insertada, en Postman o desde código.

Probar con Postman La colección lista para importar y cómo armar cada petición.

Insertar facturas El endpoint principal y su pipeline de validación completo.

Listar devoluciones Consulta de las devoluciones aprobadas de una fecha.

Antes de integrar

Conviene leer estas tres páginas: explican la mayoría de los rechazos que verás.

Reglas de fecha (V1–V4) La causa más frecuente de rechazos en la inserción.

Catálogo de errores Cada motivo de rechazo, su payload y la acción correctiva.

Casos resueltos Escenarios completos con el request y el response exactos.

Datos básicos

La URL base es https://<dominio-hosana>/api/v1/. Todas las llamadas, salvo el health check, llevan el header ApiKey. El cuerpo y las respuestas son JSON. Las fechas se interpretan en hora de Honduras (America/Tegucigalpa, UTC-6). El detalle está en convenciones del API.