API: enviar pedidos e clientes e consultar dados
Referência prática dos recursos da API v1: paginação, sincronização incremental, criação de pedido sem duplicar e códigos de erro.
3 min de leitura · Avançado · atualizado em 06/10/2026
Este guia é para quem desenvolve a integração. Todos os endereços começam em /api/v1, usam JSON e exigem o cabeçalho Authorization: Bearer SUA_CHAVE (veja "API: criando uma chave e fazendo a primeira chamada").
Consultas (GET)
| Endereço | O que traz | Filtros |
|---|---|---|
/clientes, /clientes/{id} |
clientes | q (nome/código), documento |
/fornecedores, /fornecedores/{id} |
fornecedores | q |
/produtos, /produtos/{id} |
produtos com preços por tabela | q (nome, código, código de barras), ativo |
/estoque/saldos |
físico, reservado e disponível por depósito | produto_id, deposito_id, variacao_id |
/pedidos-venda, /pedidos-venda/{id} |
pedidos (com itens no detalhe) | status, cliente_id, referencia_externa |
/titulos, /titulos/{id} |
títulos | direcao (obrigatório: receber ou pagar), status, vencimento_de, vencimento_ate |
/notas-fiscais, /notas-fiscais/{id}, /notas-fiscais/{id}/xml |
NF-e e o XML autorizado | status, pedido_venda_id |
Paginação e sincronização incremental
Toda lista é paginada: use pagina e por_pagina (até 100). A resposta traz dados e paginacao (pagina, por_pagina, total, ultima_pagina).
Para manter outro sistema atualizado sem baixar tudo, guarde a hora da última sincronização e peça só o que mudou: ?atualizado_apos=2026-10-05T10:00:00Z.
Enviar clientes (POST e PATCH)
POST /clientes com tipo_pessoa (fisica, juridica ou estrangeira), documento (CPF/CNPJ) ou id_estrangeiro, e nome. Podem ir também nome_fantasia, email e telefone. O CPF/CNPJ é validado e não pode repetir na organização. PATCH /clientes/{id} altera nome e contato; o restante do cadastro (endereços, crédito, tributação) continua nas telas.
Enviar pedidos de venda (POST)
POST /pedidos-venda cria um rascunho: o pedido passa pelas mesmas regras de crédito, margem e aprovação de qualquer pedido, nas telas do sistema.
{
"cliente_id": "UUID do cliente",
"referencia_externa": "ML-123456",
"condicao_pagamento_id": "opcional",
"itens": [
{ "produto_id": "UUID do produto", "quantidade": 3 },
{ "produto_id": "UUID", "quantidade": 1, "preco_unitario": 89.9, "desconto_percentual": 5 }
]
}
Sempre mande referencia_externa com o código do pedido na loja ou no marketplace. Se a sua integração repetir o envio (queda de rede, nova tentativa), o sistema não cria outro pedido: devolve o que já existe com status 200 e o aviso "Pedido já recebido com esta referência". Um pedido novo responde 201.
Se algum item for recusado (produto sem preço, bloqueado para venda, fora de estoque conforme as regras...), nada é gravado e a resposta diz qual item e por quê.
Respostas e erros
| Código | Significado |
|---|---|
| 200 / 201 | deu certo / criado |
| 401 | chave ausente, errada, expirada, revogada, pausada ou usuário inativo |
| 403 | a chave não tem o escopo, ou o usuário dono não tem permissão |
| 404 | não existe nesta empresa |
| 422 | dados inválidos (a resposta lista os campos) ou regra de negócio recusou |
| 429 | limite de chamadas por minuto: aguarde e tente de novo |
Toda resposta de erro é JSON com a mensagem em erro.
Os valores monetários e quantidades vão como número (ponto decimal); datas como AAAA-MM-DD e horários em ISO 8601. O fuso é o do servidor (Brasília).
Quer avaliar este guia ou usar o sistema? Entre ou cadastre-se.