API de Movimentacoes de Estoque

Rastreie e registre movimentacoes de estoque nos seus armazens. Cada mudanca de inventario e registrada como uma movimentacao.

Endpoints
GET

/stock-movements

stock_movements:read

Obter uma lista paginada de movimentacoes de estoque. Suporta filtros por produto, armazem, tipo e intervalo de datas.

POST

/stock-movements

stock_movements:write

Registrar uma nova movimentacao de estoque. Os niveis de inventario serao atualizados automaticamente.

Referencia de Campos
CampoTipoObrigatorioDescricao

id

string

Nao

Identificador unico da movimentacao de estoque (somente leitura)

productId

string

Sim

Identificador do produto

productSku

string

Nao

SKU do produto (somente leitura)

productName

string

Nao

Nome do produto (somente leitura)

warehouseId

string

Sim

Identificador do armazem

warehouseName

string

Nao

Nome do armazem (somente leitura)

variantId

string

Nao

Identificador da variante do produto (se aplicavel)

quantity

integer

Sim

Quantidade da movimentacao (inteiro positivo)

movementType

string

Sim

IN, OUT, ADJUSTMENT, TRANSFER_OUT ou TRANSFER_IN

reference

string

Nao

Numero de referencia (ex. ordem de compra)

unitCost

integer

Nao

Custo unitario em centavos

batchNumber

string

Nao

Numero do lote

notes

string

Nao

Notas adicionais

createdAt

datetime

Nao

Timestamp ISO 8601 (somente leitura)

Parametros de Consulta (Lista)
CampoTipoObrigatorioDescricao

page

integer

Nao

Numero da pagina (padrao: 1)

limit

integer

Nao

Itens por pagina (padrao: 20, maximo: 100)

productId

string

Nao

Filtrar por ID do produto

warehouseId

string

Nao

Filtrar por ID do armazem

movementType

string

Nao

Filtrar por tipo: IN, OUT, ADJUSTMENT, TRANSFER_OUT, TRANSFER_IN

from

string

Nao

Filtro de data inicial (ISO 8601)

to

string

Nao

Filtro de data final (ISO 8601)

Exemplo
Listar movimentacoes de estoque
bash
curl "https://api.mercozy.com/api/v1/external/stock-movements?page=1&limit=20&movementType=IN" \
  -H "X-API-Key: mk_live_xxxxx"
Criar uma movimentacao de estoque
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"
  }'
Exemplo de Resposta
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"
  }
}