Registrar devolución
POST /api/inventory/devolutions
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra una devolución: descuenta el stock de cada producto del almacén del establecimiento y deja el movimiento en el kardex (tipo Devolución). En productos con lotes baja la cantidad de cada lote; en productos con series, las series devueltas dejan de estar disponibles.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor). Un vendedor registra en su establecimiento (403 si indica otro).
Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con la devolución creada (mismo formato que Ver devolución).
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
establishment_id |
integer | No | Establecimiento de cuyo almacén sale la mercadería. Por defecto el del usuario; un vendedor solo puede usar el suyo. |
date_of_issue |
YYYY-MM-DD | Sí | Fecha de la devolución. |
time_of_issue |
HH:MM:SS | No | Hora. Por defecto, la actual. |
devolution_reason_id |
integer | Sí | Motivo (de Motivos de devolución). |
observation |
string (máx. 500) | Sí | Detalle: proveedor, documento de referencia, etc. |
items |
array | Sí | Al menos un producto, sin repetir: [{item_id, quantity, series_ids?, lots?}]; quantity > 0. |
items[].series_ids |
array de integer | Si el producto maneja series | Ids de las series devueltas (de Listar series, disponibles y en el almacén); tantas como quantity. |
items[].lots |
array | Si el producto maneja lotes | [{id, quantity}] con los lotes (de Listar lotes); la suma debe ser igual a quantity. |
Reglas:
- Solo productos con inventario (no servicios ni packs).
- Si la empresa controla stock, la cantidad no puede superar el stock del almacén (
409). - Las devoluciones no se editan ni se anulan.
Errores:
403si un vendedor indica otro establecimiento.422{success: false, message: {campo: [errores]}}si falla la validación de campos. Incluye series o lotes faltantes o que no corresponden al producto.409si no hay stock suficiente con control de stock activo.401sin token o con un token inválido.
Cuerpo
Content-Type: application/json
{
"date_of_issue": "2026-11-07",
"devolution_reason_id": "1",
"observation": "Devolución al proveedor DISTRIBUIDORA LIMA SAC, guía 0001-552",
"items": [
{
"item_id": "1",
"quantity": 4
}
]
}
Respuestas
201 — Registrada
{
"success": true,
"data": {
"id": 31,
"number": "DV-31",
"external_id": "6b0d3c2e-8a4f-4b7a-9f51-2c1e7d9a0b44",
"date_of_issue": "2026-11-07",
"time_of_issue": "10:15:00",
"state_type_id": "01",
"establishment": {
"id": 1,
"description": "Tienda Centro"
},
"warehouse": {
"id": 3,
"description": "Almacén - Tienda Centro"
},
"devolution_reason": {
"id": 2,
"description": "Productos dañados"
},
"observation": "Devolución al proveedor DISTRIBUIDORA LIMA SAC, guía 0001-552",
"user": {
"id": 7,
"name": "JUAN PEREZ"
},
"total_quantity": 4.0,
"created_at": "2026-11-07 10:15:03",
"items": [
{
"id": 52,
"item_id": 15,
"description": "GASEOSA 500 ML",
"internal_id": "P0015",
"unit_type_id": "NIU",
"quantity": 4.0,
"series": [],
"lots": []
}
],
"kardex": [
{
"id": 9140,
"item_id": 15,
"warehouse_id": 3,
"quantity": -4.0,
"date_of_issue": "2026-11-07"
}
]
},
"message": "Devolución registrada correctamente"
}
422 — Faltan series
{
"success": false,
"message": {
"items.0.series_ids": [
"CELULAR X10 maneja series: indica 2 serie(s) en series_ids."
]
}
}
409 — Sin stock
{
"success": false,
"message": "El producto GASEOSA 500 ML no tiene suficiente stock!"
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.