Enviar um pedido

Um pedido fechado na loja entra no ERP como um pré-documento do tipo Pedido E-commerce, na filial da credencial, na situação que a loja informou. Faturar é trabalho do ERP. Este guia percorre o corpo do POST /pedidos, o que a API confere e o que ela devolve.

O recebimento não reserva estoque

O pedido entra, mas a baixa de estoque acontece no faturamento, feito no ERP. Entre um e outro, o saldo em /estoque continua o mesmo. A loja precisa descontar do lado dela o que já vendeu.

O corpo

curl -X POST "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/pedidos" \
-H "Content-Type: application/json" \
-H "X-Api-Key: SUA_API_KEY" -H "X-Api-Secret: SEU_SECRET_KEY" \
-d @pedido.json

pedido.json

{
  "chavePedidoEcommerce": "LOJA-2026-001001",
  "dataEmissao": "2026-09-25T10:30:00",
  "status": 22,
  "observacao": "Entregar no período da tarde.",
  "valorSubTotal": 150.00,
  "valorDescontoItens": 0,
  "valorAcrescimoItens": 0,
  "valorFrete": 10.00,
  "valorTotal": 160.00,
  "cliente": {
    "cpfCnpj": "529.982.247-25",
    "nome": "Maria da Silva",
    "tipoDestinatarioId": 1,
    "email": "maria@exemplo.com",
    "telefone": "(11) 99999-8888",
    "endereco": {
      "cep": "01001-000",
      "logradouro": "Praça da Sé",
      "numero": "100",
      "complemento": "Sala 2",
      "bairro": "Sé",
      "codigoIbgeCidade": "3550308",
      "cidade": "São Paulo",
      "uf": "SP"
    }
  },
  "itens": [
    {
      "numeroItem": 1,
      "produtoId": 10,
      "grade": 2,
      "cor": 1,
      "descricao": "Camiseta básica branca M",
      "quantidade": 2,
      "valorUnitario": 50.00,
      "valorSubTotal": 100.00,
      "valorTotal": 100.00,
      "valorFreteRateado": 6.00,
      "valorLiquido": 106.00,
      "valorCusto": 40.00,
      "tabelaPreco": 1
    },
    {
      "numeroItem": 2,
      "produtoId": 20,
      "descricao": "Boné preto",
      "quantidade": 1,
      "valorUnitario": 50.00,
      "valorSubTotal": 50.00,
      "valorTotal": 50.00,
      "valorFreteRateado": 4.00,
      "valorLiquido": 54.00,
      "valorCusto": 20.00,
      "tabelaPreco": 1
    }
  ],
  "pagamentos": [
    { "meioPagamento": 3, "valor": 160.00 }
  ]
}

A chave

chavePedidoEcommerce é o identificador do pedido na loja: número, código ou o que a plataforma usar, até 100 caracteres. Ela é única por filial, e é por ela que a API reconhece um reenvio. O ERP gera o próprio identificador, o protocolo, que vem na resposta.

Os totais

A API não recalcula o pedido; ela confere que o que a loja mandou fecha. Duas somas precisam bater com valorTotal, com tolerância de um centavo para arredondamento:

Soma	Tem de ser igual a
valorLiquido de todos os itens	valorTotal
valor de todos os pagamentos	valorTotal

valorLiquido de um item é o valor final dele, já com desconto, acréscimo e a parte do frete que lhe cabe (valorFreteRateado). O frete do pedido vai em valorFrete e distribuído nos itens; a soma dos rateios tem de dar o frete. No exemplo, 106 + 54 = 160, e 6 + 4 = 10.

Os campos valorCusto e percentualLucro são informativos: o ERP grava, não confere.

Os itens

Para cada item a API confere, nesta ordem:

1. produtoId existe no cadastro. Todos os que não existirem vêm listados na mensagem de erro.
2. tabelaPreco existe, como em /tabelas-preco.
3. A grade. Todo item precisa de uma, porque o faturamento monta a nota a partir dela. grade é o código numérico, 2, e não o nome, "P"; o nome vai como texto e é recusado com 400.
   • Produto com uma grade ativa na filial: grade pode ser omitida; a API escolhe a única.
   • Produto com mais de uma: grade é obrigatória, e a mensagem de erro lista as disponíveis.
   • Grade informada que não está ativa para o produto naquela filial: recusado.
4. A cor. Grade com cores ativas exige cor, mesmo que seja uma só; omitida, o pedido é recusado e a mensagem lista as disponíveis. cor precisa estar ativa naquela grade. Grade sem cores não aceita o campo.

Os códigos de grade e cor são os mesmos que /produtos devolve em grades[].codigo e grades[].cores[].codigo. A API copia o nome da grade e da cor para dentro do pedido, então renomear o cadastro depois não altera o que foi vendido.

descricao é opcional: vazia, entra a descrição de cadastro do produto. Como todo cadastro do ERP, é gravada em maiúsculas. numeroItem é renumerado em sequência a partir de 1, na ordem crescente do que a loja mandou.

O comprador

cliente é opcional, e o que decide o comportamento é o CPF/CNPJ:

Sem cpfCnpj, ou com um inválido, o pedido entra sem destinatário e nenhum cliente é cadastrado. Serve para venda sem identificação. Os demais campos de cliente são ignorados.

Com CPF ou CNPJ válido pelo dígito verificador, o comprador vira destinatário do pedido, e aí:

• nome, endereco e tipoDestinatarioId passam a ser obrigatórios. No endereço: cep, logradouro, numero, bairro e codigoIbgeCidade com sete dígitos.
• tipoDestinatarioId é o código de um tipo em /tipos-destinatario, que precisa estar ativo. É a classificação fiscal do comprador: contribuinte, isento ou não contribuinte, e se a operação é interna ou interestadual. Escolha pelo que o comprador declarou e pela UF dele.
• codigoIbgeCidade precisa existir no cadastro de municípios do ERP. cidade é informativo.
• inscricaoEstadual vazia indica não contribuinte; o texto ISENTO indica contribuinte isento.
• natureza (1 física, 2 jurídica) pode ser omitida: é deduzida do tamanho do documento.

A API procura um cliente com aquele documento na filial. Existindo, o pedido aponta para ele. Não existindo, cadastra o cliente com o endereço, o e-mail e o telefone do pedido, e o pedido aponta para o novo. Nome, nome fantasia e inscrição estadual são gravados em maiúsculas, como todo cadastro do ERP; e-mail, em minúsculas; telefone e CEP, só dígitos.

Máscaras são aceitas em cpfCnpj, cep e telefone. Textos maiores que a coluna do ERP são cortados, não recusados: nome e logradouro têm 60 caracteres.

Status

status é a situação do pedido na loja, na numeração do ERP. Omitido, entra como 21, Pedido Efetuado.

Valor	Situação
20	Pedido aguardando pagamento
21	Pedido efetuado
22	Pedido pago
23	Pedido em separação
24	Pedido em produção
25	Pedido pronto para retirada
26	Pedido enviado
27	Pedido entregue
28	Pedido cancelado

Hoje a API só recebe o status no envio. Não há endpoint para atualizá-lo depois.

A resposta

{
  "sucesso": true,
  "mensagens": [],
  "dados": {
    "protocolo": 4321,
    "chavePedidoEcommerce": "LOJA-2026-001001",
    "status": 22,
    "statusDescricao": "PEDIDO PAGO",
    "jaProcessado": false
  }
}

Guarde o protocolo junto do pedido na loja: é o código do pré-documento no ERP e o que a equipe da filial vê na tela.

Reenvio

Reenviar um pedido com a mesma chavePedidoEcommerce nunca cria outro. A resposta é 200 com o protocolo original, jaProcessado: true e o aviso "Pedido já processado anteriormente." em mensagens. O conteúdo do reenvio é ignorado: o que vale é o que entrou primeiro.

É o que permite tratar uma falha de conexão sem risco: se a resposta não chegou, reenvie o mesmo pedido e use o protocolo que voltar. O mesmo vale para dois envios simultâneos: só um é gravado, e o outro recebe o protocolo dele.

Quando é recusado

Um 400 com a causa em mensagens. Nada é gravado: se a recusa aconteceu depois de a API começar a cadastrar o comprador, o cadastro é desfeito junto. As mensagens estão todas no catálogo de erros, com o que fazer em cada uma.

Acompanhar

curl "https://teste-api-ecommerce.objetivaweb.app.br/api/v1/pedidos?chavePedidoEcommerce=LOJA-2026-001001"

GET /pedidos lista os pedidos da filial com itens, pagamentos e comprador. Filtre por protocolo, chavePedidoEcommerce, cliente, status ou período de emissão. O status devolvido é o do pré-documento no ERP, sempre na faixa de 20 a 28; statusDescricao traz o texto.