Kardex de un producto
GET /api/inventory/kardex
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Devuelve los movimientos de stock de un producto (compras, ventas, notas de venta, pedidos, guías, traslados, devoluciones y ajustes) con el saldo acumulado de cada fila. Sin warehouse_id un administrador ve todos los almacenes con un saldo conjunto.
Quién puede usarlo: cualquier usuario autenticado. Un administrador consulta todos los almacenes (o el que indique en warehouse_id); un vendedor solo el almacén de su establecimiento: si pide otro almacén responde 403.
Formato de respuesta: listado con paginación por cursor {success, data[], pagination: {next_cursor, has_more}}. Además trae meta: item, warehouse (null = todos), date_start, date_end, opening_balance (saldo antes de date_start), page_opening_balance (saldo antes de la primera fila de la página) y page_closing_balance (saldo después de la última).
Parámetros de la URL (query):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
item_id |
integer | Sí | Producto. |
warehouse_id |
integer | No | Almacén. Un vendedor solo puede indicar el suyo (por defecto, el suyo). |
date_start |
YYYY-MM-DD | No | Desde (fecha de registro del movimiento). |
date_end |
YYYY-MM-DD | No | Hasta; igual o posterior a date_start. |
limit / cursor |
integer / string | No | Paginación por cursor (limit de 1 a 100, por defecto 15). |
Paginación por cursor: envía limit (1 a 100, por defecto 15). La respuesta trae pagination.next_cursor; para la página siguiente repite la misma consulta agregando cursor=<next_cursor>. Cuando pagination.has_more es false no hay más páginas.
Saldo entre páginas: el saldo se calcula en el servidor en cada página partiendo del saldo inicial del rango, así que el balance de la primera fila de la página 2 continúa exactamente el de la última fila de la página 1 (page_opening_balance de una página = page_closing_balance de la anterior).
Campos de cada fila:
| Campo | Tipo | Descripción |
|---|---|---|
id |
integer | Id del movimiento. Las filas van en el orden en que se registraron. |
date_of_issue |
string | Fecha del documento de origen (YYYY-MM-DD). |
registered_at |
string | Fecha y hora en que se registró el movimiento. |
warehouse |
object | Almacén del movimiento {id, description}. |
type |
string | Tipo legible: Compra, Venta, Nota de venta, Anulación Venta, Pedido, Traslado, Devolución, Stock Real, motivo de inventario, etc. |
origin |
object | Documento que generó el movimiento: type (document comprobante, sale_note nota de venta, purchase compra, purchase_settlement liquidación de compra, order_note pedido, dispatch guía, devolution devolución, inventory movimiento de inventario), id, number (serie-número) y transfer_id (si es un traslado, su id en Traslados). id es null si el documento ya no existe. |
related_documents |
array | Documentos relacionados [{type, number}] (p. ej. la nota de venta de la que salió la factura). |
quantity |
number | Cantidad registrada (positiva entra, negativa sale). |
input / output |
number | Lo que el movimiento sumó o restó al saldo. Siempre se cumple balance = saldo anterior + input - output. |
balance |
number | Saldo acumulado después de la fila. |
affects_balance |
boolean | false cuando el movimiento no cambia el saldo (p. ej. una factura que viene de una nota de venta que ya descontó el stock). |
note |
string o null | Explica por qué la fila no afecta el saldo. |
Errores:
403si un vendedor pide un almacén que no es el de su establecimiento.422si faltaitem_id, el producto o el almacén no existen, o las fechas no tienen el formatoYYYY-MM-DD.401sin token o con un token inválido.
Parámetros
| Parámetro | Dónde | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
item_id |
query | sí | 1 |
Producto. |
warehouse_id |
query | sí | 1 |
Almacén. |
date_start |
query | sí | 2026-11-01 |
Desde YYYY-MM-DD. |
date_end |
query | sí | 2026-11-30 |
Hasta YYYY-MM-DD. |
limit |
query | no | 50 |
Filas por página. |
cursor |
query | no | Valor de pagination.next_cursor de la respuesta anterior para obtener la página siguiente. |
Respuestas
200 — Kardex
{
"success": true,
"data": [
{
"id": 9101,
"date_of_issue": "2026-11-03",
"registered_at": "2026-11-03 09:12:40",
"warehouse": {
"id": 3,
"description": "Almacén - Tienda Centro"
},
"type": "Compra",
"origin": {
"type": "purchase",
"id": 812,
"number": "F001-4520",
"transfer_id": null
},
"related_documents": [],
"quantity": 24.0,
"input": 24.0,
"output": 0,
"balance": 30.0,
"affects_balance": true,
"note": null
},
{
"id": 9115,
"date_of_issue": "2026-11-04",
"registered_at": "2026-11-04 16:40:02",
"warehouse": {
"id": 3,
"description": "Almacén - Tienda Centro"
},
"type": "Nota de venta",
"origin": {
"type": "sale_note",
"id": 3311,
"number": "NV01-1532",
"transfer_id": null
},
"related_documents": [],
"quantity": -3.0,
"input": 0,
"output": 3.0,
"balance": 27.0,
"affects_balance": true,
"note": null
},
{
"id": 9120,
"date_of_issue": "2026-11-05",
"registered_at": "2026-11-05 10:02:11",
"warehouse": {
"id": 3,
"description": "Almacén - Tienda Centro"
},
"type": "Venta",
"origin": {
"type": "document",
"id": 20457,
"number": "B001-998",
"transfer_id": null
},
"related_documents": [
{
"type": "sale_note",
"number": "NV01-1532"
}
],
"quantity": -3.0,
"input": 0,
"output": 0,
"balance": 27.0,
"affects_balance": false,
"note": "Stock descontado en la nota de venta NV01-1532"
}
],
"pagination": {
"next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"has_more": true
},
"meta": {
"item": {
"id": 15,
"internal_id": "P0015",
"description": "GASEOSA 500 ML",
"unit_type_id": "NIU"
},
"warehouse": {
"id": 3,
"description": "Almacén - Tienda Centro"
},
"date_start": "2026-11-01",
"date_end": "2026-11-30",
"opening_balance": 6.0,
"page_opening_balance": 6.0,
"page_closing_balance": 27.0
}
}
403 — Otro almacén
{
"success": false,
"message": "Solo puedes consultar el almacén de tu establecimiento."
}
422 — Falta el producto
{
"success": false,
"message": {
"item_id": [
"El campo item id es obligatorio."
]
}
}
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.