Saltar al contenido
Facturador

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:

  • 403 si 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.
  • 409 si no hay stock suficiente con control de stock activo.
  • 401 sin 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.