WMS · Referência · BIX Developers

GET /wms/stock-balances

Saldo atual por loja e produto

Escopo wms.stock.read

Saldo atual do WMS, somando todos os depósitos e endereços de cada loja. Cada item de data é um par (loja, produto). Filtrando uma loja, cada página traz até page_size produtos dela.

O produto é o item de estoque do WMS: product_code e ean aceitam qualquer código do cadastro (a caixa, um EAN alternativo) e chegam ao item que guarda o saldo.

Ordem estável (loja, depois produto): dá para percorrer as páginas sem repetir nem pular linha. Para sincronizar, use updated_since com a data da última leitura.

Parâmetros de consulta

store_code string · lista: Código de integração da loja (o mesmo do ERP).

Separe por vírgula, até 100 valores. Exemplo: 0012
store_id integer · lista: Id da loja no BIX.

Separe por vírgula, até 100 valores. Exemplo: 12
product_code string · lista: Código interno do produto.

Separe por vírgula, até 100 valores. Exemplo: 1001
ean string · lista: Código de barras (EAN) do produto.

Separe por vírgula, até 100 valores. Exemplo: 7891234567890
updated_since string (data-hora): Só pares (loja, produto) cujo saldo mudou a partir desta data/hora (ISO 8601). Data sem hora vale desde 00:00, no fuso de Brasília.

Exemplo: 2026-11-09T10:00:00-03:00
include_zero boolean: Inclui pares com saldo zero (o WMS guarda a linha zerada com a data da última contagem).

Padrão: false Exemplo: false
page integer: Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer: Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

quantity_total: todas as situações do saldo, em todos os depósitos da loja.
quantity_available: situação "Disponível" em depósito que conta como disponível (Avaria e Trânsito, por exemplo, não contam).
quantity_unavailable: quantity_total menos quantity_available (bloqueado, em análise, avaria, trânsito).
updated_at: última mudança de saldo do par (loja, produto).
Quantidades na unidade do item de estoque (product.unit), com até 4 casas decimais. O saldo pode ser negativo onde a zona do depósito aceita.

Erros possíveis

HTTP	code	Quando
400	`invalid_parameter`	Parâmetro com valor inválido (o `detail` diz qual).
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
403	`store_not_allowed`	A chave está restrita a algumas lojas e uma das pedidas não é delas.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/wms/stock-balances?store_code=0012&store_id=12&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://demonstracao.appbix.com.br/external-api/v1/wms/stock-balances?store_code=0012&store_id=12&page_size=100",
    headers={"Authorization": f"Bearer {os.environ['BIX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://demonstracao.appbix.com.br/external-api/v1/wms/stock-balances?store_code=0012&store_id=12&page_size=100",
  { method: "GET", headers: { Authorization: `Bearer ${process.env.BIX_API_KEY}` } }
);
if (!response.ok) throw new Error((await response.json()).code);
console.log(await response.json());

200 Resposta

{
  "data": [
    {
      "store": {
        "id": 12,
        "code": "0012",
        "name": "Loja Centro"
      },
      "product": {
        "id": 345,
        "internal_code": "1001",
        "ean": "7891234567890",
        "description": "ARROZ TIPO 1 5KG",
        "unit": "UN"
      },
      "quantity_total": 120.0,
      "quantity_available": 100.0,
      "quantity_unavailable": 20.0,
      "updated_at": "2026-11-09T10:15:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1234,
    "total_pages": 25,
    "has_next": true
  }
}

GET /wms/bin-stocks

Saldo por endereço

Escopo wms.stock.read

O saldo em cada endereço, por produto, lote, validade e situação: o detalhe que GET /wms/stock-balances soma por loja. Use para saber onde está o estoque.

O produto é o item de estoque do WMS (ver o guia de WMS). Ordem estável por id.

Parâmetros de consulta

store_code string · lista: Código de integração da loja.

Separe por vírgula, até 100 valores. Exemplo: 0012
storage_location string · lista: Código do depósito no WMS.

Separe por vírgula, até 100 valores. Exemplo: 01
product_code string · lista: Código interno do produto.

Separe por vírgula, até 100 valores. Exemplo: 1001
ean string · lista: Código de barras do produto.

Separe por vírgula, até 100 valores. Exemplo: 7891234567890
updated_since string (data-hora): Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_zero boolean: Inclui endereços com saldo zero (guardam a data da última contagem).

Padrão: false Exemplo: false
page integer: Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer: Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

stock_status: available (disponível), quality (em análise) ou blocked (bloqueado).
batch vazio e expiry_date null quando o produto não é controlado por lote.

Erros possíveis

HTTP	code	Quando
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
403	`store_not_allowed`	A chave está restrita a algumas lojas e uma das pedidas não é delas.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/wms/bin-stocks?store_code=0012&storage_location=01&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://demonstracao.appbix.com.br/external-api/v1/wms/bin-stocks?store_code=0012&storage_location=01&page_size=100",
    headers={"Authorization": f"Bearer {os.environ['BIX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://demonstracao.appbix.com.br/external-api/v1/wms/bin-stocks?store_code=0012&storage_location=01&page_size=100",
  { method: "GET", headers: { Authorization: `Bearer ${process.env.BIX_API_KEY}` } }
);
if (!response.ok) throw new Error((await response.json()).code);
console.log(await response.json());

200 Resposta

{
  "data": [
    {
      "id": 9021,
      "store": {
        "id": 12,
        "code": "0012",
        "name": "Loja Centro"
      },
      "storage_location": "01",
      "bin": "05-003-02",
      "product": {
        "id": 345,
        "internal_code": "1001",
        "ean": "7891234567890",
        "description": "ARROZ TIPO 1 5KG",
        "unit": "UN"
      },
      "batch": "L2611",
      "expiry_date": "2027-03-31",
      "stock_status": "available",
      "quantity": 24.0,
      "last_counted_at": "2026-11-08T14:20:00-03:00",
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}

GET /wms/storage-locations

Listar depósitos

Escopo wms.structure.read

Os depósitos do WMS em cada loja (estoque da loja, depósito, avaria...). O code é o que as movimentações usam em storage_location; o erp_code é o código do mesmo depósito no ERP, quando ele existe lá.

type.counts_as_available diz se o saldo do depósito conta como disponível (avaria e trânsito, por exemplo, não contam).

Parâmetros de consulta

store_code string · lista: Código de integração da loja.

Separe por vírgula, até 100 valores. Exemplo: 0012
include_inactive boolean: Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer: Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer: Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

erp_code é null quando o depósito não existe no ERP (uma avaria interna, por exemplo); type é null quando o depósito não tem classificação.

Erros possíveis

HTTP	code	Quando
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
403	`store_not_allowed`	A chave está restrita a algumas lojas e uma das pedidas não é delas.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/wms/storage-locations?store_code=0012&include_inactive=false&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://demonstracao.appbix.com.br/external-api/v1/wms/storage-locations?store_code=0012&include_inactive=false&page_size=100",
    headers={"Authorization": f"Bearer {os.environ['BIX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://demonstracao.appbix.com.br/external-api/v1/wms/storage-locations?store_code=0012&include_inactive=false&page_size=100",
  { method: "GET", headers: { Authorization: `Bearer ${process.env.BIX_API_KEY}` } }
);
if (!response.ok) throw new Error((await response.json()).code);
console.log(await response.json());

200 Resposta

{
  "data": [
    {
      "id": 3,
      "store": {
        "id": 12,
        "code": "0012",
        "name": "Loja Centro"
      },
      "code": "01",
      "name": "Loja",
      "erp_code": "01",
      "type": {
        "code": "LOJA",
        "name": "Estoque da loja",
        "counts_as_available": true
      },
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}

GET /wms/bins

Listar endereços

Escopo wms.structure.read

Os endereços de estoque (rua, prédio, nível, apartamento) de cada depósito. O code é o que as movimentações usam em bin.

Todo depósito tem o endereço ENDERECAR (zona "A endereçar", usage: staging): é para onde vai a entrada enviada sem endereço, à espera de ser guardada pela operação no BIX.

Parâmetros de consulta

store_code string · lista: Código de integração da loja.

Separe por vírgula, até 100 valores. Exemplo: 0012
storage_location string · lista: Código do depósito no WMS.

Separe por vírgula, até 100 valores. Exemplo: 01
updated_since string (data-hora): Só registros alterados a partir desta data/hora (ISO 8601).

Exemplo: 2026-11-10T06:00:00-03:00
include_inactive boolean: Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer: Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer: Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

zone.usage: sales_floor (área de venda), backroom (retaguarda), reserve (pulmão), picking, dock (doca) ou staging (a endereçar).

Erros possíveis

HTTP	code	Quando
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
403	`store_not_allowed`	A chave está restrita a algumas lojas e uma das pedidas não é delas.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/wms/bins?store_code=0012&storage_location=01&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://demonstracao.appbix.com.br/external-api/v1/wms/bins?store_code=0012&storage_location=01&page_size=100",
    headers={"Authorization": f"Bearer {os.environ['BIX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://demonstracao.appbix.com.br/external-api/v1/wms/bins?store_code=0012&storage_location=01&page_size=100",
  { method: "GET", headers: { Authorization: `Bearer ${process.env.BIX_API_KEY}` } }
);
if (!response.ok) throw new Error((await response.json()).code);
console.log(await response.json());

200 Resposta

{
  "data": [
    {
      "id": 801,
      "code": "05-003-02",
      "store": {
        "id": 12,
        "code": "0012",
        "name": "Loja Centro"
      },
      "storage_location": "01",
      "zone": {
        "code": "PR",
        "name": "Prateleira",
        "usage": "sales_floor"
      },
      "aisle": "05",
      "bay": "003",
      "level": "02",
      "position": "",
      "blocked_putaway": false,
      "blocked_removal": false,
      "active": true,
      "updated_at": "2026-11-10T08:30:00-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}

GET /wms/reasons

Listar motivos de movimentação

Escopo wms.structure.read

Os motivos cadastrados no WMS do cliente. Toda entrada e saída enviada pela API leva o code de um motivo que valha para o tipo (types vazio vale para todos). A venda usa o motivo do sistema VENDA sozinha.

Parâmetros de consulta

include_inactive boolean: Inclui os registros desativados (active: false). Use na sincronização incremental para saber o que saiu.

Padrão: false Exemplo: false
page integer: Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer: Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Erros possíveis

HTTP	code	Quando
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/wms/reasons?include_inactive=false&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://demonstracao.appbix.com.br/external-api/v1/wms/reasons?include_inactive=false&page_size=100",
    headers={"Authorization": f"Bearer {os.environ['BIX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://demonstracao.appbix.com.br/external-api/v1/wms/reasons?include_inactive=false&page_size=100",
  { method: "GET", headers: { Authorization: `Bearer ${process.env.BIX_API_KEY}` } }
);
if (!response.ok) throw new Error((await response.json()).code);
console.log(await response.json());

200 Resposta

{
  "data": [
    {
      "code": "COMPRA",
      "name": "Compra",
      "types": [
        "receipt"
      ],
      "requires_note": false,
      "system": false,
      "active": true
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}

GET /wms/movements

Ler o livro de movimentações

Escopo wms.movements.read

Todas as movimentações de estoque do WMS, na ordem em que foram lançadas: entradas, saídas, vendas, transferências, reposições, ajustes, ajustes de inventário e estornos. É por aqui que o ERP replica o que a operação fez no BIX (o acerto de um inventário, por exemplo).

O livro não se altera: correção é um estorno, que aparece como outro lançamento com reversal_of. Para sincronizar, guarde o maior id lido e peça since_id na próxima vez.

Parâmetros de consulta

store_code string · lista: Código de integração da loja.

Separe por vírgula, até 100 valores. Exemplo: 0012
since_id integer: Só lançamentos com id maior que este (cursor da sincronização).

Exemplo: 0
occurred_since string (data-hora): Só lançamentos com data do movimento a partir desta.

Exemplo: 2026-11-10T00:00:00-03:00
type string · lista: Tipo: receipt, issue, transfer, replenishment, sale, adjustment, count_adjustment ou initial_load.

Separe por vírgula, até 100 valores. Exemplo: count_adjustment
product_code string · lista: Código interno do produto.

Separe por vírgula, até 100 valores. Exemplo: 1001
page integer: Página, começando em 1.

Padrão: 1 Exemplo: 1
page_size integer: Itens por página. Acima de 100 a chamada é recusada com invalid_parameter (não é cortada em silêncio).

Padrão: 50 Máximo: 100 Exemplo: 50

Sobre a resposta

from é a origem e to o destino; um dos dois é null conforme o tipo (a entrada não tem origem).
external_id é o que o ERP mandou ao lançar pela API; null para o que nasceu no BIX.
source: web, app, integration (esta API), system ou import (arquivo).
Quantidade na unidade do item de estoque (product.unit).

Erros possíveis

HTTP	code	Quando
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
403	`store_not_allowed`	A chave está restrita a algumas lojas e uma das pedidas não é delas.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X GET "https://demonstracao.appbix.com.br/external-api/v1/wms/movements?store_code=0012&since_id=0&page_size=100" \
  -H "Authorization: Bearer $BIX_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://demonstracao.appbix.com.br/external-api/v1/wms/movements?store_code=0012&since_id=0&page_size=100",
    headers={"Authorization": f"Bearer {os.environ['BIX_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://demonstracao.appbix.com.br/external-api/v1/wms/movements?store_code=0012&since_id=0&page_size=100",
  { method: "GET", headers: { Authorization: `Bearer ${process.env.BIX_API_KEY}` } }
);
if (!response.ok) throw new Error((await response.json()).code);
console.log(await response.json());

200 Resposta

{
  "data": [
    {
      "id": 55120,
      "occurred_at": "2026-11-10T07:40:00-03:00",
      "recorded_at": "2026-11-10T07:41:02-03:00",
      "type": "receipt",
      "from": null,
      "to": {
        "code": "ENDERECAR",
        "storage_location": "01",
        "store": {
          "id": 12,
          "code": "0012",
          "name": "Loja Centro"
        }
      },
      "product": {
        "id": 345,
        "internal_code": "1001",
        "ean": "7891234567890",
        "description": "ARROZ TIPO 1 5KG",
        "unit": "UN"
      },
      "quantity": 48.0,
      "batch": "",
      "expiry_date": null,
      "stock_status": "available",
      "reason": {
        "code": "COMPRA",
        "name": "Compra"
      },
      "document": "NF 123456",
      "note": "",
      "source": "integration",
      "external_id": "NF-123456-1",
      "reversal_of": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false
  }
}

POST /wms/movements

Enviar entradas, saídas e vendas

Escopo wms.movements.write

Lança no WMS o que aconteceu no ERP: entrada (receipt: nota de compra, transferência recebida, devolução), saída (issue: transferência enviada, consumo, perda) e venda (sale). Transferência entre endereços, reposição e ajuste continuam sendo feitos pela operação no BIX.

Sem bin, o lançamento usa o endereço "A endereçar" do depósito: a entrada fica lá até ser guardada na prateleira pela operação, e a saída baixa de lá.

O external_id identifica a linha no ERP e torna o envio seguro de repetir: a mesma linha enviada de novo volta skipped, sem lançar duas vezes; com conteúdo diferente, é recusada.

Envie até 500 itens em {"items": [...]}. Use o cabeçalho Idempotency-Key para poder repetir a chamada (timeout, queda de rede) sem gravar duas vezes.

Corpo da requisição

Objeto JSON com items: uma lista de 1 a 500 itens. Cada item tem:

external_id string obrigatório: Identificador único da linha no ERP (até 80 caracteres), por exemplo nota + item.

Exemplo: NF-123456-1
type string obrigatório: receipt (entrada), issue (saída) ou sale (venda).

Exemplo: receipt
store_code string: Código de integração da loja. Ou store_id.

Exemplo: 0012
store_id integer: Id da loja no BIX. Ou store_code.
storage_location string obrigatório: Código do depósito no WMS (ver GET /wms/storage-locations).

Exemplo: 01
bin string: Código do endereço. Vazio: o "A endereçar" do depósito.
internal_code string: Código interno: quantidade na unidade do item de estoque. Ou ean.

Exemplo: 1001
ean string: Código de barras: quantidade na unidade daquele código (a caixa de 12 conta 12). Ou internal_code.
quantity number obrigatório: Quantidade, maior que zero.

Exemplo: 48
batch string: Lote (até 40 caracteres).
expiry_date string: Validade do lote (AAAA-MM-DD).
reason string: Código do motivo (ver GET /wms/reasons). Obrigatório em receipt e issue; a venda usa VENDA.

Exemplo: COMPRA
document string: Documento de origem (nota, pedido), até 80 caracteres.

Exemplo: NF 123456
note string: Observação (até 255 caracteres).
occurred_at string: Data e hora do movimento no ERP (ISO 8601). Vazio: agora.

Exemplo: 2026-11-10T07:40:00-03:00

Aceita o cabeçalho Idempotency-Key: repetir a chamada com a mesma chave, em 24 horas, devolve a resposta da primeira sem gravar de novo. Ver Envio em lote e idempotência.

Sobre a resposta

A chamada responde 200 sempre que o lote foi processado, mesmo com itens recusados: confira o status de cada item em results (created, updated, skipped ou error).
results vem na ordem de items; index é a posição do item no lote, a partir de 0.
Item com erro não impede os outros: cada um é gravado ou recusado sozinho.
skipped: a linha já tinha sido lançada com este external_id (e o mesmo conteúdo); id é o lançamento existente.
Recusas do WMS trazem códigos próprios em code: wms_insufficient_stock (sem saldo na origem), wms_bin_blocked (endereço bloqueado), wms_idempotency_conflict (o external_id já foi usado com outro conteúdo), wms_invalid_structure (depósito, endereço ou motivo inválido).

Erros possíveis

HTTP	code	Quando
400	`invalid_parameter`	Parâmetro com valor inválido (o `detail` diz qual).
401	`api_key_expired`	A chave passou da data de expiração.
401	`api_key_revoked`	A chave foi revogada na Configuração Global › API.
401	`invalid_api_key`	A chave não existe neste ambiente ou está errada.
401	`missing_api_key`	A chamada veio sem o cabeçalho "Authorization: Bearer <chave>".
403	`insufficient_scope`	A chave não tem o acesso que este endpoint exige.
403	`module_disabled`	O cliente não tem o módulo deste endpoint habilitado.
403	`store_not_allowed`	A chave está restrita a algumas lojas e uma das pedidas não é delas.
409	`idempotency_key_reused`	O `Idempotency-Key` já foi usado, nas últimas 24 horas, numa chamada com outro corpo.
429	`rate_limited`	Limite de chamadas por minuto da chave atingido. Respeite o `Retry-After`.
500	`internal_error`	Erro interno. Tente de novo; se persistir, fale com o suporte.

curl -X POST "https://demonstracao.appbix.com.br/external-api/v1/wms/movements" \
  -H "Authorization: Bearer $BIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"external_id": "NF-123456-1", "type": "receipt", "store_code": "0012", "storage_location": "01", "internal_code": "1001", "quantity": 48, "reason": "COMPRA", "document": "NF 123456", "occurred_at": "2026-11-10T07:40:00-03:00"}, {"external_id": "CUPOM-998877-3", "type": "sale", "store_code": "0012", "storage_location": "01", "bin": "ENDERECAR", "internal_code": "1001", "quantity": 2, "occurred_at": "2026-11-10T09:15:00-03:00"}]}'

import os
import uuid
import requests

payload = {
  "items": [
    {
      "external_id": "NF-123456-1",
      "type": "receipt",
      "store_code": "0012",
      "storage_location": "01",
      "internal_code": "1001",
      "quantity": 48,
      "reason": "COMPRA",
      "document": "NF 123456",
      "occurred_at": "2026-11-10T07:40:00-03:00"
    },
    {
      "external_id": "CUPOM-998877-3",
      "type": "sale",
      "store_code": "0012",
      "storage_location": "01",
      "bin": "ENDERECAR",
      "internal_code": "1001",
      "quantity": 2,
      "occurred_at": "2026-11-10T09:15:00-03:00"
    }
  ]
}

response = requests.post(
    "https://demonstracao.appbix.com.br/external-api/v1/wms/movements",
    json=payload,
    headers={
        "Authorization": f"Bearer {os.environ['BIX_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=60,
)
response.raise_for_status()
for item in response.json()["results"]:
    if item["status"] == "error":
        print(item["index"], item["code"], item["detail"])

const payload = {
  "items": [
    {
      "external_id": "NF-123456-1",
      "type": "receipt",
      "store_code": "0012",
      "storage_location": "01",
      "internal_code": "1001",
      "quantity": 48,
      "reason": "COMPRA",
      "document": "NF 123456",
      "occurred_at": "2026-11-10T07:40:00-03:00"
    },
    {
      "external_id": "CUPOM-998877-3",
      "type": "sale",
      "store_code": "0012",
      "storage_location": "01",
      "bin": "ENDERECAR",
      "internal_code": "1001",
      "quantity": 2,
      "occurred_at": "2026-11-10T09:15:00-03:00"
    }
  ]
};

const response = await fetch("https://demonstracao.appbix.com.br/external-api/v1/wms/movements", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIX_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify(payload),
});
const body = await response.json();
body.results.filter((r) => r.status === "error").forEach((r) => console.log(r));

Corpo da requisição

{
  "items": [
    {
      "external_id": "NF-123456-1",
      "type": "receipt",
      "store_code": "0012",
      "storage_location": "01",
      "internal_code": "1001",
      "quantity": 48,
      "reason": "COMPRA",
      "document": "NF 123456",
      "occurred_at": "2026-11-10T07:40:00-03:00"
    },
    {
      "external_id": "CUPOM-998877-3",
      "type": "sale",
      "store_code": "0012",
      "storage_location": "01",
      "bin": "ENDERECAR",
      "internal_code": "1001",
      "quantity": 2,
      "occurred_at": "2026-11-10T09:15:00-03:00"
    }
  ]
}

200 Resposta

{
  "summary": {
    "total": 2,
    "created": 2,
    "updated": 0,
    "skipped": 0,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "status": "created",
      "id": 55120,
      "code": null,
      "detail": null
    },
    {
      "index": 1,
      "status": "created",
      "id": 55121,
      "code": null,
      "detail": null
    }
  ]
}