Saltar al contenido
Facturador

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:

  • 403 si un vendedor pide un almacén que no es el de su establecimiento.
  • 422 si falta item_id, el producto o el almacén no existen, o las fechas no tienen el formato YYYY-MM-DD.
  • 401 sin 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.