API de Movimientos de Stock

Rastrea y registra movimientos de stock en tus almacenes. Cada cambio de inventario se registra como un movimiento.

Endpoints

GET

/stock-movements

stock_movements:read

Obtener una lista paginada de movimientos de stock. Soporta filtros por producto, almacen, tipo y rango de fechas.

POST

/stock-movements

stock_movements:write

Registrar un nuevo movimiento de stock. Los niveles de inventario se actualizan automaticamente.

Referencia de Campos

Campo	Tipo	Obligatorio	Descripción
id	string	No	Identificador unico del movimiento de stock (solo lectura)
productId	string	Sí	Identificador del producto
productSku	string	No	SKU del producto (solo lectura)
productName	string	No	Nombre del producto (solo lectura)
warehouseId	string	Sí	Identificador del almacen
warehouseName	string	No	Nombre del almacen (solo lectura)
variantId	string	No	Identificador de variante del producto (si aplica)
quantity	integer	Sí	Cantidad del movimiento (entero positivo)
movementType	string	Sí	IN, OUT, ADJUSTMENT, TRANSFER_OUT o TRANSFER_IN
reference	string	No	Numero de referencia (ej. orden de compra)
unitCost	integer	No	Costo unitario en centavos
batchNumber	string	No	Numero de lote
notes	string	No	Notas adicionales
createdAt	datetime	No	Marca de tiempo ISO 8601 (solo lectura)

Parametros de Consulta (Lista)

Campo	Tipo	Obligatorio	Descripción
page	integer	No	Numero de pagina (predeterminado: 1)
limit	integer	No	Elementos por pagina (predeterminado: 20, maximo: 100)
productId	string	No	Filtrar por ID de producto
warehouseId	string	No	Filtrar por ID de almacen
movementType	string	No	Filtrar por tipo: IN, OUT, ADJUSTMENT, TRANSFER_OUT, TRANSFER_IN
from	string	No	Filtro de fecha inicio (ISO 8601)
to	string	No	Filtro de fecha fin (ISO 8601)

Ejemplo

Listar movimientos de stock

bash

curl "https://api.mercozy.com/api/v1/external/stock-movements?page=1&limit=20&movementType=IN" \
  -H "X-API-Key: mk_live_xxxxx"

Crear un movimiento de stock

bash

curl -X POST "https://api.mercozy.com/api/v1/external/stock-movements" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product-uuid",
    "warehouseId": "warehouse-uuid",
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "notes": "Initial stock"
  }'

Ejemplo de Respuesta

json

{
  "data": {
    "id": "sm_abc123",
    "productId": "product-uuid",
    "productSku": "WDG-001",
    "productName": "Premium Widget",
    "warehouseId": "warehouse-uuid",
    "warehouseName": "Main Warehouse",
    "variantId": null,
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "unitCost": null,
    "batchNumber": null,
    "notes": "Initial stock",
    "createdAt": "2025-12-15T10:30:00Z"
  }
}