Listar devoluciones

GET /api/v1/devoluciones/listar

Devuelve todas las devoluciones aprobadas cuya fecha de procesado coincide con la fecha solicitada. Jaremar lo usa típicamente al cierre del día (o de mes) para reconciliar las devoluciones capturadas en bodega.

Solicitud

Atributo	Valor
Método	GET
Ruta	/api/v1/devoluciones/listar
Autenticación	Requerida (ApiKey)
Rate limit	10 por minuto por IP (ver rate limits)

Headers

Header	Obligatorio	Formato	Ejemplo	Descripción
ApiKey	Sí	string	—	Clave de autenticación.
Fecha	Sí	dd/MM/yyyy	17/12/2025	Fecha de procesado de las devoluciones.

Query params

Parámetro	Obligatorio	Default	Descripción
pagina	No	1	Número de página. Hasta 1000 devoluciones por página.

El formato del header Fecha es estricto

Debe ser exactamente dd/MM/yyyy (día/mes/año). El validador detecta incluso fechas con overflow como 99/99/9999 y las rechaza. Cualquier otro formato responde 422.

Postman

• Método GET, URL https://<dominio-hosana>/api/v1/devoluciones/listar
• Pestaña Headers: ApiKey con tu clave, y Fecha con 17/12/2025
• Para paginar, agrega ?pagina=2 al final de la URL

cURL

curl -X GET "https://<dominio-hosana>/api/v1/devoluciones/listar?pagina=1" \
  -H "ApiKey: TU_CLAVE_AQUI" \
  -H "Fecha: 17/12/2025"

PHP

$response = $client->get('devoluciones/listar', [
    'headers' => ['ApiKey' => 'TU_CLAVE_AQUI', 'Fecha' => '17/12/2025'],
    'query'   => ['pagina' => 1],
]);
$devoluciones = json_decode($response->getBody(), true);

foreach ($devoluciones as $d) {
    echo "{$d['devolucion']} · {$d['factura']} · L {$d['total']}\n";
}

Node.js

const res = await fetch(
  "https://<dominio-hosana>/api/v1/devoluciones/listar?pagina=1",
  { headers: { "ApiKey": "TU_CLAVE_AQUI", "Fecha": "17/12/2025" } }
);
const devoluciones = await res.json();

for (const d of devoluciones) {
  console.log(`${d.devolucion} · ${d.factura} · L ${d.total}`);
}

C# / .NET

using var req = new HttpRequestMessage(HttpMethod.Get, "devoluciones/listar?pagina=1");
req.Headers.Add("Fecha", "17/12/2025");
var res = await http.SendAsync(req);
var devoluciones = await res.Content.ReadFromJsonAsync<JsonElement>();

foreach (var d in devoluciones.EnumerateArray())
    Console.WriteLine($"{d.GetProperty("devolucion")} · {d.GetProperty("factura")}");

Cómo se consume al cierre

sequenceDiagram
    autonumber
    participant J as Jaremar
    participant H as API Hosana
    loop por cada página
        J->>H: GET /devoluciones/listar?pagina=N<br/>(Fecha: dd/MM/yyyy)
        H-->>J: array de devoluciones (≤ 1000)
        Note over J: si recibió < 1000 → terminar<br/>si no → pedir página N+1
    end

Respuesta exitosa

HTTP 200 — un array de devoluciones (no un objeto envolvente). Vacío [] si no hubo devoluciones esa fecha.

[
  {
    "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
      }
    ]
  }
]

Formato numérico: 6 decimales fijos

Los campos numéricos total, lineTotal y cantidad se emiten como números JSON con exactamente 6 decimales (por ejemplo 207 se devuelve como 207.000000, y 1 como 1.000000). Es a propósito: replica el contrato del ERP de Jaremar. Son números, no strings — no llevan comillas. Al parsear, trátalos como decimales normales.

Campos de la devolución

Campo	Tipo	Descripción
devolucion	string	Identificador único de la devolución en Hosana.
factura	string	Número de la factura devuelta (Nfactura).
clienteid	string	Identificador del cliente.
cliente	string	Nombre del cliente.
fecha	string|null	Fecha/hora de la devolución, formato YYYY-MM-DDTHH:mm:ss (sin zona).
total	number	Importe total de la devolución. 6 decimales fijos (207.000000).
almacen	string	Código de bodega (OAC, OAS, OAO).
idConcepto	string	Identificador del concepto/motivo de devolución (id de Jaremar, o el código si no hay id).
concepto	string	Descripción del concepto de devolución.
numeroManifiesto	string	Manifiesto al que pertenecía la factura.
fechaProcesado	string|null	Fecha en que Hosana procesó la devolución (ISO sin zona).
horaProcesado	string|null	Hora de procesado.
lineasDevolucion	array	Detalle de productos devueltos.

Campos de cada línea (lineasDevolucion)

Campo	Tipo	Descripción
productoId	string	Identificador del producto.
producto	string	Descripción del producto.
cantidad	number	Cantidad devuelta, con 6 decimales fijos. Ver la regla de cajas vs. unidades abajo.
numeroLinea	string	Número de línea.
lineTotal	number	Importe total de la línea. 6 decimales fijos (207.000000).

Cómo se calcula cantidad: cajas vs. unidades

El valor de cantidad depende del tipo de producto:

• Productos por caja (CJ): cantidad es la cantidad de cajas devueltas.
• Productos por unidad (UN): cantidad es la cantidad de unidades devueltas.

La regla interna: si la cantidad por caja es mayor que cero, se reporta esa; de lo contrario, se reporta la cantidad por unidad.

Errores

Header Fecha faltante

HTTP 422

{ "success": false, "message": "El header Fecha es obligatorio. Formato esperado: dd/MM/yyyy. Ejemplo: 17/12/2025" }

Formato de fecha inválido

HTTP 422

{ "success": false, "message": "Formato de fecha inválido. Se esperaba dd/MM/yyyy. Ejemplo: 17/12/2025" }

Caché y consistencia

Para no recalcular en cada llamada, las respuestas se cachean por fecha:

• Fechas pasadas: caché de 60 minutos (los datos ya no cambian).
• La fecha de hoy: caché de 5 minutos (pueden llegar devoluciones nuevas).

La caché se invalida automáticamente cuando se crea o aprueba una devolución de esa fecha, de modo que nunca recibirás datos obsoletos por más que la ventana de caché siga abierta.

Paginación

Cada página devuelve hasta 1000 devoluciones. Si una fecha tuviera más, solicita las páginas siguientes con ?pagina=2, ?pagina=3, etc., hasta recibir un array más corto que 1000 (o vacío), lo que indica que ya no hay más registros.