API: criar orçamento, venda, OS e pedido — obrigatórios e recálculo do total

Atualizado em 22/10/2026

QUANDO USAR ESTA FONTE
Você está integrando seu sistema ao ERP pelo aplicativo API e precisa criar orçamento, venda, ordem de serviço ou pedido. Aqui estão o endereço certo de cada documento, o que a API exige, e por que o valor total que ela salva às vezes não é o que você mandou. Conceito de venda, situação, estoque, financeiro e cadastro de cliente ou produto são do ERP e se respondem pelas fontes do ERP. Esta fonte cobre só o que a API faz de diferente.

ANTES: CREDENCIAIS E PERMISSÃO
No aplicativo API, na tela Credenciais, você cria uma chave de API e recebe os dois códigos dela, Access Token e Secret Access Token. Os dois valores vão em cabeçalhos da requisição. Faltando um deles a resposta é "Access Token não informado!" ou "Secret Access Token não informado!". Errados, "Access Token e/ou Secret Access Token incorreto(s)!". Nunca envie essas credenciais em conversa de atendimento.
O token já carrega a empresa e, quando o cadastro define, também a loja e o usuário. Por isso você não manda empresa no corpo, e o cliente que você usar precisa ser da mesma empresa do token. O usuário ligado ao token precisa ter permissão para a tela equivalente no ERP, senão a resposta é "Este usuário não possui permissão para acessar este método!". Essa permissão se ajusta no cadastro de usuários do ERP.

CADA DOCUMENTO TEM SEU ENDEREÇO
A lista de endereços de pedido é fechada. São estes, sempre depois de /api:
orcamentos_produtos, orçamento de produto.
orcamentos_servicos, orçamento de serviço.
orcamentos, atalho que cria orçamento de produto e, na consulta, lista orçamento de produto e de serviço juntos.
vendas_produtos, venda de produto.
vendas_servicos, venda de serviço.
vendas, atalho que cria venda de produto e, na consulta, lista venda de produto e de serviço juntas.
ordens_servicos, ordem de serviço.
pedidos, pedido da loja virtual.
O método define a ação: POST no endereço cria, PUT no endereço com o id edita, GET lista ou consulta, DELETE com o id exclui. Existe ainda um POST em endereço/gerar_parcelas, explicado adiante.
Mandar tipo igual a servico no corpo ou na querystring faz os atalhos orcamentos e vendas apontarem para serviço. Mandar tipo igual a produto trava os atalhos em produto.
Venda balcão é a exceção que mais gera chamado: ela não tem endereço próprio e a troca por tipo igual a vendas_balcao só está registrada nas rotas de consulta. Em POST, PUT e DELETE o endereço vendas continua sendo venda de produto. Ou seja, não dá para criar venda balcão pela API.

O QUE É OBRIGATÓRIO PARA CRIAR
cliente_id. Vale para todos os tipos, inclusive ordem de serviço e pedido da loja virtual. Sem ele a resposta é "É necessário informar o cliente_id". Se o id não for de um cliente da empresa do token, é "O cliente_id informado é inválido!". Não vale nome do cliente: tem que ser o id do cadastro.
Itens. A exigência de item mínimo existe só nas quatro famílias de produto e serviço. Orçamento de produto e venda de produto exigem pelo menos um produto, senão "É necessário informar no mínimo um produto!". Orçamento de serviço e venda de serviço exigem pelo menos um serviço, senão "É necessário informar no mínimo um serviço!". Ordem de serviço e pedido da loja virtual não têm essa checagem na API: aceitam produtos, serviços, os dois ou nenhum. Nos itens de serviço você usa servico_id e nome_servico; a API converte internamente. Em produto com variação, mande variacao_id.
Datas. Toda data vai no formato AAAA-MM-DD; fora disso volta "O campo (x) não é uma data válida (y)!". Campo de número inteiro com texto volta "O campo (x) não é um valor inteiro (y)!". Se você não mandar data, a API usa a data de hoje.
Código. Se você mandar codigo, ele é conferido e um código já usado é recusado com a mensagem da checagem. Se não mandar, o ERP numera.
Se a sua empresa tem atributos personalizados obrigatórios para aquele tipo de documento, eles têm que vir na requisição, senão a resposta lista quais faltaram, pelo nome e pelo id.

A API PODE TROCAR A FAMÍLIA DO DOCUMENTO
Isso vale só nos dois atalhos, orcamentos e vendas. Se você não mandar o campo tipo no corpo e mandar só servicos, sem nenhum produto, a própria API troca: orçamento de produto vira orçamento de serviço, e venda de produto vira venda de serviço. É por isso que às vezes o documento aparece no ERP em outra listagem, e não é erro. Se você quer garantir a família, use o endereço específico ou mande o campo tipo.

POR QUE O TOTAL SALVO NÃO É O QUE VOCÊ MANDOU
A API não confia no total enviado: ela recalcula, sempre, na criação e na edição. Se o valor gravado veio diferente, quase sempre é isso.
Por item: quantidade vazia vira 1, valor de venda vazio vira zero, e o total do item é quantidade vezes valor de venda, menos o desconto. Desconto em valor e desconto em porcentagem não convivem no item: se você mandar desconto em valor maior que zero, a porcentagem é zerada. O total que você mandar dentro do item é ignorado e sobrescrito.
No pedido: o total é a soma dos produtos, mais a soma dos serviços, mais o frete, mais outros valores, menos o desconto em valor. Só depois disso, se houver desconto em porcentagem, ele é aplicado sobre esse resultado. Repare na diferença: no item um desconto anula o outro, mas no pedido os dois se somam. Mandar os dois no pedido achando que só um vale é uma causa clássica de total menor que o esperado.
As somas de produtos e de serviços saem dos itens já recalculados, nunca dos valores que vieram no corpo.
A resposta do POST devolve o pedido como ele ficou salvo. Compare o total dela com o seu antes de abrir chamado.

PARCELAS E CONDIÇÃO DE PAGAMENTO
Há dois caminhos. Se você enviar a lista de pagamentos, a API respeita as suas parcelas; parcela sem data de vencimento assume hoje, e plano de contas inexistente ou não informado cai no plano de contas padrão daquele tipo de documento.
Se você não enviar nenhuma parcela, a API gera sozinha: divide o total pelo número de parcelas informado, uma parcela quando você não informa, e espaça pelo intervalo de dias. Quando você manda a forma de pagamento e não manda o intervalo, a API busca na forma de pagamento o intervalo da primeira parcela e o intervalo entre parcelas, e usa esses valores. Se aquela forma de pagamento não for encontrada nessa busca, a API descarta a forma e segue sem ela. Intervalo de 30 é tratado como mês cheio. Sem data da primeira parcela, a contagem começa hoje; sem intervalo nenhum, todas as parcelas caem na mesma data.
Você também pode ver as parcelas antes de salvar: POST em endereço/gerar_parcelas devolve a prévia sem gravar nada. Atenção: essa prévia usa o valor_total que você mandar no corpo, ela não soma seus itens. Sem valor_total, ela devolve parcelas zeradas.
Em condicao_pagamento envie a_vista ou parcelado: são os dois valores que a API converte, e é assim que ela devolve na resposta. Outro valor não gera mensagem de erro, apenas não é convertido.

EDITANDO UM PEDIDO
O PUT vai no endereço da família do pedido com o id. O id tem que ser de pedido da mesma empresa do token.
Mandar loja_id diferente da loja em que o pedido foi cadastrado é recusado com mensagem própria: alterações na loja do pedido não são permitidas. Ou você omite loja_id, ou manda o mesmo.
Os itens enviados substituem os que estavam lá, não somam. O que você não enviar, a API repõe do pedido que já existe: atributos, equipamentos, produtos, parcelas e endereços. Mas os totais são calculados antes dessa reposição, só com o que você enviou. Ou seja, editar sem mandar os itens pode devolver o pedido com os itens antigos e o total recalculado sem eles. Por isso, na edição, mande o documento completo do jeito que ele deve ficar.
E lembre que a API recalcula os valores também aqui, com a mesma conta da criação. Se o ERP vai aceitar essa alteração de valores é outra história: pedido em situação que lança estoque ou financeiro não tem os valores alterados, e essa é regra do ERP, igual à da tela.

O QUE COSTUMA DAR ERRADO
Postar em vendas e o documento sair como venda de serviço. É a troca automática de família, porque foram só serviços e sem o campo tipo.
Tentar criar venda balcão. Não existe pela API; o endereço cai em venda de produto.
Mandar nome do cliente em vez de cliente_id, ou um cliente de outra empresa. Volta cliente_id inválido.
Mandar produto em endereço de serviço, ou serviço em endereço de produto. Volta a exigência de item mínimo, porque a família não bate com o que foi enviado.
Total diferente do sistema de origem. É recálculo, e o culpado costuma ser desconto duplicado no pedido ou desconto informado no item junto com valor total do item.
Parcelas com valor errado. A prévia de gerar_parcelas divide o valor_total que você mandou, não os itens.
Data em formato brasileiro. Use AAAA-MM-DD.
Resposta "Falha ao salvar pedido." ou "Falha ao atualizar pedido.". São mensagens genéricas de exceção; revise o corpo enviado campo a campo antes de acionar o suporte.
Erro de permissão, de plano ou bloqueio por excesso de requisições. Nada disso é o seu corpo de requisição: é o usuário do token, o plano da conta ou o limite de chamadas.

ONDE ISSO NÃO SE RESOLVE
Situação do pedido, lançamento de estoque, lançamento no financeiro, limite de crédito do cliente, numeração e nota fiscal seguem as regras do ERP, iguais às da tela. A API só monta o documento e entrega para o mesmo motor. Se a dúvida é sobre a regra em si, ela se responde pelas fontes do ERP.