Casos resueltos

Esta página recorre situaciones reales de principio a fin: qué envía Jaremar, qué responde Hosana y qué debe hacer la integración. Los ejemplos usan datos con el formato real del OPL de Jaremar. Dos de los casos traen su archivo descargable para que los pruebes tal cual en Postman.

Caso 1 — Lote limpio de un manifiesto 200

Dos facturas del manifiesto 800002, bodega OAC.

Response — 200

{
  "success": true,
  "message": "Facturas procesadas correctamente.",
  "batch_uuid": "a1b2c3d4-...",
  "manifiestos": ["800002"],
  "resumen": { "recibidas": 2, "insertadas": 2, "actualizadas": 0, "sin_cambios": 0, "pendientes_revision": 0, "rechazadas": 0 }
}

Acción: ninguna. Guarda el batch_uuid para tu registro.

Caso 2 — Fechas mezcladas, ambas dentro de rango 200

Descargar manifiesto-800003-pasa.json

El manifiesto 800003 trae dos facturas con fechas distintas: una del 2026-06-12 y otra del 2026-05-20. La mezcla de fechas dentro de un manifiesto está permitida, y como ambas están dentro del rango de 30 días, el lote se inserta sin problema.

Response — 200

{
  "success": true,
  "message": "Facturas procesadas correctamente.",
  "batch_uuid": "b2c3d4e5-...",
  "manifiestos": ["800003"],
  "resumen": { "recibidas": 2, "insertadas": 2, "actualizadas": 0, "sin_cambios": 0, "pendientes_revision": 0, "rechazadas": 0 }
}

Acción: ninguna. Mezclar fechas ya no es motivo de rechazo.

Caso 3 — Una factura demasiado antigua 422

Descargar manifiesto-800004-rechaza.json

El manifiesto 800004 trae dos facturas: una del 2026-06-12 (válida) y otra del 2026-04-01 (más de 30 días de antigüedad). La validación es por factura y atómica: esa única factura vieja rechaza el manifiesto completo. Nada entra.

Response — 422

{
  "success": false,
  "motivo": "FECHAS_INVALIDAS",
  "message": "Batch rechazado por errores de fecha en uno o más manifiestos.",
  "accion_requerida": "Revise los manifiestos rechazados. Ninguna FechaFactura puede ser futura ni superar el rango configurado de antigüedad; una sola factura inválida rechaza el manifiesto completo.",
  "resumen": { "total_recibidas": 2, "total_rechazadas": 2, "total_validas": 0, "insertadas": 0 },
  "manifiestos_rechazados": [
    {
      "manifiesto": "800004",
      "motivo": "FECHA_FACTURA_DEMASIADO_ANTIGUA",
      "detalle": {
        "hoy_servidor": "2026-06-13",
        "limite_dias": 30,
        "facturas_antiguas": {
          "002-001-01-04004002": { "fecha": "2026-04-01", "dias": 73 }
        },
        "instruccion": "Una o más facturas superan el límite de 30 días de antigüedad. El manifiesto se rechaza completo; corrija el origen o cargue desde el panel administrativo."
      },
      "total_facturas": 2,
      "facturas": ["002-001-01-04004001", "002-001-01-04004002"]
    }
  ],
  "manifiestos_validos": []
}

Acción: saca del lote la factura 002-001-01-04004002 (la de 2026-04-01) y reenvía el resto. Para cargar una factura tan antigua, coordina con Hosana una carga manual desde el panel.

Caso 4 — Batch mixto: un manifiesto con almacén inválido 422

Jaremar envía dos manifiestos. El 800002 está bien; el 800005 trae un código de bodega inexistente (OAX).

Response — 422

{
  "success": false,
  "motivo": "ALMACENES_DESCONOCIDOS",
  "message": "Uno o más manifiestos fueron rechazados por contener almacenes no registrados en el sistema.",
  "batch_uuid": "c3d4e5f6-...",
  "manifiestos": ["800002", "800005"],
  "resumen": { "recibidas": 42, "insertadas": 28, "actualizadas": 0, "sin_cambios": 0, "pendientes_revision": 0, "rechazadas": 14 },
  "manifiestos_rechazados": [
    {
      "manifiesto": "800005", "total_facturas": 14, "motivo": "ALMACENES_DESCONOCIDOS",
      "almacenes_desconocidos": [
        { "almacen": "OAX", "facturas": ["002-001-01-04005050"], "cantidad": 1 }
      ]
    }
  ]
}

Acción: corrige OAX por un código válido (OAC/OAS/OAO) y reenvía solo el 800005.

Caso 5 — Reintento de un batch ya procesado 200

Jaremar tuvo un timeout y reenvía el mismo batch el mismo día.

Response — 200

{
  "success": true,
  "message": "Este batch ya fue procesado anteriormente el día de hoy.",
  "batch_uuid": "b2c3d4e5-...",
  "resumen": { "recibidas": 2, "insertadas": 2, "actualizadas": 0, "sin_cambios": 0, "pendientes_revision": 0, "rechazadas": 0 }
}

Acción: ninguna. Tu envío original sí había entrado.

Caso 6 — Agregar a un manifiesto de un día anterior 422

Jaremar intenta agregar una factura al manifiesto 800001, que en Hosana fue creado un día anterior. Un manifiesto ya creado no acepta facturas nuevas en días posteriores.

Response — 422

{
  "success": false,
  "motivo": "MANIFIESTOS_FECHA_INVALIDA",
  "message": "Batch rechazado completamente. Contiene facturas de manifiestos creados en días anteriores que ya no aceptan nuevas facturas.",
  "resumen": { "total_recibidas": 1, "total_rechazadas": 1, "total_validas": 0, "insertadas": 0 },
  "manifiestos_rechazados": [
    {
      "manifiesto": "800001", "fecha_original": "2026-06-12", "fecha_intento": "2026-06-13",
      "total_facturas": 1, "facturas_afectadas": ["002-001-01-04000987"],
      "instruccion": "El manifiesto #800001 fue creado el 2026-06-12 y ya no acepta facturas nuevas. Reenvíe estas facturas en un nuevo número de manifiesto."
    }
  ]
}

Acción: reenvía esa factura bajo un número de manifiesto nuevo.

Caso 7 — Factura ya existente en otro manifiesto 422

El manifiesto 800006 incluye la factura 002-001-01-04003001, que ya está registrada bajo el 800003 (del Caso 2).

Response — 422

{
  "success": false,
  "motivo": "FACTURAS_DUPLICADAS_EN_OTRO_MANIFIESTO",
  "message": "Uno o más manifiestos fueron rechazados por contener facturas que ya existen en otros manifiestos.",
  "resumen": { "recibidas": 1, "insertadas": 0, "actualizadas": 0, "sin_cambios": 0, "pendientes_revision": 0, "rechazadas": 1 },
  "manifiestos_rechazados": [
    {
      "manifiesto": "800006", "total_facturas": 1, "motivo": "FACTURAS_DUPLICADAS_EN_OTRO_MANIFIESTO",
      "mensaje": "El manifiesto #800006 contiene facturas que ya existen en otros manifiestos. Reenvíelo limpio.",
      "facturas_duplicadas": [{ "factura": "002-001-01-04003001", "manifiesto_existente": "800003" }]
    }
  ]
}

Acción: la factura 002-001-01-04003001 ya pertenece al 800003. Quítala del 800006 y reenvía el 800006 limpio.

Caso 8 — Consulta de devoluciones del día 200

Request — GET /api/v1/devoluciones/listar con header Fecha: 09/06/2026

Response — 200 (respuesta real del endpoint)

[
  {
    "devolucion": "1",
    "factura": "002-001-01-04001002",
    "clienteid": "98065403",
    "cliente": "PULPERIA ESMERALDA",
    "fecha": "2026-06-09T00:00:00",
    "total": 255.000000,
    "almacen": "OAC",
    "idConcepto": "BE-03",
    "concepto": "Error de Entrega (Motorista)",
    "numeroManifiesto": "800002",
    "fechaProcesado": "2026-06-09T00:00:00",
    "horaProcesado": "11:04:31",
    "lineasDevolucion": [
      {
        "productoId": "50470402",
        "producto": "CENTELLABARRA ROSADO 400GX3X4",
        "cantidad": 5.000000,
        "numeroLinea": "1",
        "lineTotal": 75.000000
      },
      {
        "productoId": "50470403",
        "producto": "CENTELLABARRA AMARILL 400GX3X4",
        "cantidad": 1.000000,
        "numeroLinea": "2",
        "lineTotal": 180.000000
      }
    ]
  }
]

Acción: reconcilia usando devolucion como llave de idempotencia. Los importes y cantidades vienen con 6 decimales fijos (255.000000, 5.000000) — trátalos como números decimales normales. La cantidad es en cajas para productos CJ y en unidades para productos UN.