Convenções
O que vale para todos os endpoints. Lido uma vez, evita a maior parte das dúvidas na referência.
O envelope
Toda resposta JSON tem a mesma forma:
{
"sucesso": true,
"mensagens": [],
"dados": { }
}
| Campo | Conteúdo |
|---|---|
sucesso | true quando a operação foi atendida. false vem sempre com a causa em mensagens. |
mensagens | Lista de textos. Em erro, uma linha por problema; em sucesso, um aviso, como "Pedido já processado anteriormente.". Vazia quando não há nada a dizer. |
dados | O conteúdo. Ausente ou null quando sucesso é false. Nas listagens é uma página; no pedido, o protocolo. |
Desserialize toda resposta como esse envelope, inclusive 401, 429 e 500. A única exceção é o
download de imagem, cujo 200 é o arquivo.
Paginação
Toda listagem é paginada e aceita os mesmos quatro parâmetros de query:
| Parâmetro | Padrão | Regra |
|---|---|---|
pagina | 1 | Começa em 1. Valor menor vira 1. |
tamanhoPagina | 50 | Máximo 200, ou 100 em /clientes, /estoque, /pedidos e /produtos. Acima do máximo é reduzido, não recusado. |
ordenarPor | o campo padrão do endpoint | Um dos nomes aceitos pelo endpoint, abaixo. Outro nome devolve 400 com a lista. |
descendente | false | Inverte a ordenação. |
A página devolvida traz o suficiente para iterar:
{
"itens": [ ],
"paginaAtual": 1,
"tamanhoPagina": 50,
"totalItens": 1234,
"totalPaginas": 25,
"temProxima": true
}
Percorra enquanto temProxima for true. totalItens é contado a cada chamada, então um cadastro
inserido no meio da leitura pode mudar o total entre uma página e outra.
curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/produtos?pagina=2&tamanhoPagina=100&ordenarPor=descricao&descendente=false"
Ordenação por endpoint
O primeiro nome de cada linha é o padrão.
| Endpoint | ordenarPor aceitos |
|---|---|
/clientes | codigo, razaoSocial, nomeFantasia, cpfCnpj |
/codigos-barras | codigo, codigoProduto |
/cores | codigo, descricao |
/estoque | produto, grade, quantidade |
/filiais | codigo, razaoSocial |
/fornecedores | codigo, descricao |
/grades | codigo, descricao |
/grupos | codigo, descricao, hierarquia |
/marcas | codigo, descricao |
/pedidos | protocolo, chavePedidoEcommerce, dataEmissao, valorTotal |
/produtos | codigo, descricao, sku, dataUltimaAtualizacao |
/promocoes | codigo, descricao, dataInicial, dataFinal |
/tabelas-preco | codigo, descricao |
/tipos-destinatario | codigo, descricao |
Filtros por endpoint
Filtro omitido não filtra. Filtro de texto busca por conteúdo, sem diferenciar maiúsculas, salvo
onde a referência diz "exato". ativo aceita true ou false; omitido, traz ativos e inativos.
| Endpoint | Filtros |
|---|---|
/clientes | codigo, cpfCnpj, nome, ativo |
/codigos-barras | codigo, codigoProduto, ativo |
/cores | nome, ativo |
/estoque | produto, grade, comSaldo, ativo |
/filiais | razaoSocial, cnpj, ativo |
/fornecedores | nome, cpfCnpj, ativo |
/grades | nome, ativo |
/grupos | nome, codigo, ativo, hierarquia |
/marcas | nome, ativo |
/pedidos | protocolo, chavePedidoEcommerce, cliente, status, dataInicial, dataFinal |
/produtos | codigo, descricao, sku, grupo, marca, codigoBarras, exportarParaEcommerce, ativo, alteradoApartirDe |
/promocoes | descricao, ativo, vigentesEm |
/tabelas-preco | nome, ativo |
/tipos-destinatario | codigo, descricao, contribuinte, ativo |
Filtros de documento, como cpfCnpj e cnpj, aceitam só dígitos: sem ponto, barra ou hífen.
Enums
Todo enum do ERP sai em dois campos: o número, que é o valor gravado e o que não muda, e um
campo *Descricao com o texto que o ERP mostra.
{ "status": 22, "statusDescricao": "PEDIDO PAGO" }
Guarde e compare pelo número. Exiba o texto. A lista de valores de cada enum está na descrição do campo na referência, e nos filtros e no pedido você envia só o número.
Datas
ISO 8601, sem fuso horário, na hora local da filial: 2026-09-25T10:30:00. Data pura, como
2026-09-25, vale em filtros de período e significa o dia inteiro em dataFinal. Não envie sufixo
Z nem deslocamento; a API não converte.
Números
Número é número: 160.00, não "160.00". Decimal com ponto. Valor entre aspas num campo numérico é
400, no envelope, com a mensagem "Campo '...' com valor inválido para o tipo esperado" e o caminho do
campo no JSON. Valores monetários vêm com até quatro casas; a API não arredonda o que a loja envia.
Textos
O ERP guarda cadastros em maiúsculas, e é assim que descrições, nomes e razões sociais voltam. Filtros de texto ignoram a caixa. No pedido, a descrição do item vai para maiúsculas; nome e endereço do comprador são gravados como vieram, cortados no tamanho da coluna quando passam; e-mail vai para minúsculas.
Códigos
codigo é sempre o identificador no ERP, estável, inteiro. Referencie sempre por ele: grupo no
produto é o codigo de /grupos, tabelaPreco no item do pedido é o codigo de /tabelas-preco,
e assim por diante. Nomes mudam; códigos não.
Campos desconhecidos
Campo novo em resposta entra na versão corrente sem aviso prévio de versão. Configure o seu cliente para ignorar o que não conhece. Campo novo em requisição é sempre opcional na mesma versão.
Cabeçalhos de resposta
| Cabeçalho | Quando |
|---|---|
api-supported-versions | Em toda resposta que chegou a um endpoint. Lista as versões da API no ar. |
Retry-After | No 429, em segundos. |
Content-Disposition: inline; filename=... | No download de imagem. |