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_stockno se ajusta nada y respondesuccess: false,code: stock_changedycurrent_stock; vuelve a leer el stock y confirma.
Errores:
422{success: false, message: {campo: [errores]}}si falla la validación de campos.200consuccess: false:stock_changedo 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.