Catálogo de erros

Toda mensagem que a API devolve em mensagens, com a causa e o que fazer. Mensagens com valores, como códigos e totais, aparecem aqui com valores de exemplo; o formato é o mesmo.

Este catálogo é conferido por teste automatizado contra o código da API: mensagem nova sem entrada aqui quebra o build.

Transversais

Valem para qualquer endpoint.

Código	Mensagem	Causa	O que fazer
401	Credenciais de integração inválidas.	Cabeçalho ausente, credencial inexistente, secret errado, credencial inativa ou expirada, IP fora da lista. A API não diz qual.	Conferir os dois cabeçalhos e a credencial no ERP. Ver Autenticação.
429	Limite de requisições excedido para esta integração.	Cota por minuto ou por hora esgotada.	Esperar Retry-After segundos e repetir. Ver Limites.
500	Erro interno ao processar a requisição. Tente novamente mais tarde.	Falha não prevista. O detalhe está no log da API.	Repetir. Se persistir, informar data, hora e endpoint ao suporte.
400	Campo de ordenação 'xyz' não é aceito neste endpoint. Aceitos: codigo, descricao.	ordenarPor com nome fora da lista do endpoint.	Usar um dos nomes listados na própria mensagem.
400	Corpo da requisição ausente ou não é um JSON válido.	POST sem corpo, ou com JSON que não se consegue ler.	Enviar o corpo com Content-Type: application/json e conferir a sintaxe.
400	Campo 'itens[0].grade' com valor inválido para o tipo esperado. Confira o tipo na referência.	Um campo do corpo não converte para o tipo do contrato: texto em campo numérico, número entre aspas, data fora do formato. O caminho no JSON vem na mensagem.	Corrigir o tipo do campo. grade e cor, por exemplo, são códigos numéricos, não nomes.
400	Parâmetro 'pagina' com valor 'abc' inválido para o tipo esperado.	Parâmetro de query com valor que não converte para o tipo: texto onde vai número, data fora do formato.	Corrigir o valor do parâmetro.

Pedidos

POST /pedidos. A validação de formato roda primeiro e devolve todos os problemas de uma vez; as conferências contra o ERP rodam depois, uma por vez, na ordem desta tabela.

Formato do pedido

Mensagem	O que fazer
A chave do pedido no e-commerce é obrigatória.	Enviar chavePedidoEcommerce.
A chave do pedido no e-commerce aceita no máximo 100 caracteres.	Encurtar a chave.
O valor total do pedido deve ser maior que zero.	Pedido sem valor não entra.
O pedido precisa de ao menos um item.	Enviar itens.
O pedido precisa de ao menos uma forma de pagamento.	Enviar pagamentos.
A observação aceita no máximo 500 caracteres.	Encurtar observacao.
O código do produto do item deve ser maior que zero.	Preencher produtoId em cada item.
A quantidade do item deve ser maior que zero.	Item com quantidade zero ou negativa.
O valor unitário do item não pode ser negativo.	Corrigir valorUnitario.
A tabela de preço do item deve ser informada.	Preencher tabelaPreco com o código de /tabelas-preco.
O valor do pagamento deve ser maior que zero.	Pagamento zerado ou negativo.
Meio de pagamento não reconhecido. Use a numeração fiscal do ERP.	meioPagamento fora da lista; ver a referência do campo.

Comprador, quando há CPF/CNPJ válido

Mensagem	O que fazer
Com CPF/CNPJ informado, o nome do comprador é obrigatório.	Preencher cliente.nome.
Com CPF/CNPJ informado, o endereço do comprador é obrigatório.	Preencher cliente.endereco.
Com CPF/CNPJ informado, o tipo de destinatário é obrigatório. Consulte os disponíveis em /tipos-destinatario.	Preencher cliente.tipoDestinatarioId.
O código do tipo de destinatário deve ser maior que zero.	Código inválido em tipoDestinatarioId.
O CEP é obrigatório no endereço do comprador.	Preencher endereco.cep.
O logradouro é obrigatório no endereço do comprador.	Preencher endereco.logradouro.
O número é obrigatório no endereço do comprador.	Preencher endereco.numero. Sem número, envie "S/N".
O bairro é obrigatório no endereço do comprador.	Preencher endereco.bairro.
O código IBGE da cidade é obrigatório no endereço do comprador.	Preencher endereco.codigoIbgeCidade.
O código IBGE da cidade tem sete dígitos.	Formato do IBGE: sete dígitos, como 3550308.

Conferências contra o ERP

Mensagem	Causa	O que fazer
Operação não localizada para processamento.	A filial não tem operação fiscal de venda ativa.	Configuração do ERP; acionar a filial.
Não existe caixa padrão configurado para a filial 1.	A filial não tem caixa que registre lançamentos.	Configuração do ERP; acionar a filial.
Produto informado não existe no cadastro.	Algum produtoId não existe. Vem acompanhada da lista.	Ressincronizar o catálogo.
Códigos não encontrados: 20, 35.	Acompanha a anterior, com os códigos que faltam.	Idem.
Tabela de preço informada não existe no cadastro. Códigos não encontrados: 9.	tabelaPreco de algum item não existe.	Usar um código de /tabelas-preco.
Totalização incorreta: a soma do valor líquido dos itens (159,5) não bate com o valor total do pedido (160).	Soma de valorLiquido difere de valorTotal em mais de um centavo.	Recalcular os rateios. Ver Enviar um pedido.
Pagamentos não fecham: a soma dos pagamentos (100) não bate com o valor total do pedido (160).	Soma de pagamentos[].valor difere de valorTotal em mais de um centavo.	Enviar todos os pagamentos do pedido.
O produto 10 não tem grade ativa na filial, e todo item precisa de uma.	O produto existe mas não tem grade cadastrada nesta filial.	Cadastro do ERP; acionar a filial.
O produto 10 tem mais de uma grade ativa nesta filial; informe qual foi vendida em 'grade'. Disponíveis: 2, 3.	Produto com variações e grade omitida.	Enviar grade com um dos códigos listados.
A grade 5 não está ativa para o produto 10 nesta filial. Disponíveis: 2, 3.	grade não pertence ao produto ou está inativa.	Usar um dos códigos listados.
A cor 9 não está ativa na grade 2 do produto 10.	cor não existe naquela grade.	Usar um código de grades[].cores[] do produto.
A grade 2 do produto 10 tem cores ativas; informe qual foi vendida em 'cor'. Disponíveis: 1, 4.	A grade vendida tem cores e cor foi omitida.	Enviar cor com um dos códigos listados.
Código IBGE de município '3550999' não existe no cadastro.	O município não está no cadastro do ERP.	Conferir o código IBGE; se estiver certo, acionar a filial.
Tipo de destinatário 7 não existe ou está inativo. Consulte os disponíveis em /tipos-destinatario.	tipoDestinatarioId inválido para a filial.	Escolher um de /tipos-destinatario.
Não foi possível gravar o pedido.	A gravação falhou sem causa específica.	Repetir com a mesma chave; se persistir, acionar o suporte.

Aviso em sucesso

Mensagem	Significado
Pedido já processado anteriormente.	Vem com 200 e jaProcessado: true: a chave já tinha entrado, e protocolo é o original. Nada foi criado.

Listagens

Erros de validação dos filtros. Todos são 400 e vêm juntos quando há mais de um.

/pedidos

Mensagem
O protocolo deve ser maior que zero.
A chave do pedido no e-commerce aceita no máximo 100 caracteres.
O código do cliente deve ser maior que zero.
Status de pedido não reconhecido. Aceitos: 20 a 28.
A data final não pode ser anterior à data inicial.

/produtos

Mensagem
O código do produto deve ser maior que zero.
O filtro de descrição aceita no máximo 120 caracteres, que é o tamanho da coluna no ERP.
O filtro de SKU aceita no máximo 50 caracteres, que é o tamanho da coluna no ERP.
O código do grupo deve ser maior que zero.
O código da marca deve ser maior que zero.
O filtro de código de barras aceita no máximo 20 caracteres.

/clientes

Mensagem
O código do cliente deve ser maior que zero.
O filtro de CPF/CNPJ aceita só dígitos, sem ponto, barra ou hífen.
O filtro de CPF/CNPJ aceita no máximo 14 dígitos.
O filtro de nome aceita no máximo 60 caracteres, que é o tamanho da coluna no ERP.

/estoque

Mensagem
O código do produto deve ser maior que zero.
O código da grade deve ser maior que zero.

/codigos-barras

Mensagem
O código de barras aceita no máximo 50 caracteres.
O código do produto deve ser maior que zero.

/grupos

Mensagem
O filtro de nome aceita no máximo 100 caracteres.
A hierarquia deve ser maior que zero.

/tipos-destinatario

Mensagem
O código do tipo de destinatário deve ser maior que zero.
O filtro de descrição aceita no máximo 100 caracteres, que é o tamanho da coluna no ERP.
Indicador de contribuinte não reconhecido. Aceitos: 1, 2 e 9.

/filiais e /fornecedores

Mensagem
O filtro de razão social aceita no máximo 500 caracteres.
O CNPJ aceita no máximo 14 caracteres, só com dígitos.
O filtro de nome aceita no máximo 500 caracteres.
O CPF ou CNPJ aceita no máximo 14 caracteres, só com dígitos.

/marcas, /cores, /grades, /tabelas-preco e /promocoes

Mensagem
O filtro de nome aceita no máximo 500 caracteres.
O filtro de descrição aceita no máximo 500 caracteres.