Saltar al contenido
Facturador

Ajustar a stock real

POST /api/inventory/adjust

Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).

Fija el stock de uno o varios productos al valor contado (inventario físico). Se registra la diferencia como ingreso (si sube) o salida (si baja) en el kardex.

Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).

Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success.

Cuerpo (JSON):

Campo Tipo Obligatorio Descripción / valores permitidos
warehouse_id integer Sí Almacén.
inventory_transaction_id string Sí Motivo del ajuste (de adjust_reasons). Si su sentido no coincide con la diferencia se usa el motivo genérico de ajuste por diferencia.
comments string No Comentario (máx. 500).
items array Sí [{item_id, system_stock, real_stock}]. system_stock = stock que leíste antes de contar; real_stock ≥ 0 = stock contado.

Reglas:

  • Control de concurrencia: si el stock actual de algún producto ya no coincide con system_stock no se ajusta nada y responde success: false, code: stock_changed y current_stock; vuelve a leer el stock y confirma.

Errores:

  • 422 {success: false, message: {campo: [errores]}} si falla la validación de campos.
  • 200 con success: false: stock_changed o producto con lotes/series.

Cuerpo

Content-Type: application/json

{
  "warehouse_id": "1",
  "inventory_transaction_id": "13",
  "comments": "Conteo físico noviembre",
  "items": [
    {
      "item_id": "1",
      "system_stock": 20,
      "real_stock": 18
    }
  ]
}

Respuestas

200 — Ajustado

{
  "success": true,
  "data": {
    "items": [
      {
        "item_id": 15,
        "previous_stock": 20.0,
        "new_stock": 18.0,
        "difference": -2.0
      }
    ]
  },
  "message": "Stock actualizado con éxito"
}

200 — Stock cambió

{
  "success": false,
  "code": "stock_changed",
  "item_id": 15,
  "current_stock": 19.0,
  "message": "El stock cambió desde que abriste el producto. Revisa el valor actual y vuelve a confirmar."
}

422 — Stock negativo

{
  "success": false,
  "message": {
    "items.0.real_stock": [
      "El stock real debe ser mayor o igual a 0."
    ]
  }
}

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.