APIs privadas

Comercial · vendas

Criar, atualizar, pagar e finalizar vendas
View as Markdown

Comercial · vendas

Esta página concentra as operações privadas de escrita para vendas do Comercial.

Escopo atual:

  • POST /simplificav2/venda
  • PUT /simplificav2/venda/{id}
  • PUT /simplificav2/venda/{id}/pagamentos
  • POST /simplificav2/venda/{id}/finalizar
  • POST /simplificav2/oportunidade/{id}/venda

Autenticação

1Authorization: Bearer {{bearer_token}}
2Content-Type: application/json

Regras gerais

  • todas as chamadas usam JSON;
  • cada chamada opera em uma única venda;
  • POST /venda exige dados básicos e ao menos um item;
  • PUT /venda/{id} faz atualização parcial;
  • campos omitidos continuam com o valor atual;
  • quando itens é enviado no PUT, a lista atual de itens é substituída pela nova lista;
  • é possível atualizar somente os itens;
  • pagamentos usam rota específica;
  • não existe rota de inativação por API para venda.

Criar venda

Rota

  • POST /simplificav2/venda

Campos principais:

  • pessoa_id
  • etapa_negociacao_id
  • origem_id
  • data_venda
  • consultor_sdr_id
  • consultor_closer_id
  • itens

Campos opcionais:

  • data_previsao_entrega
  • endereco_entrega_id
  • observacao
  • observacao_interna
  • vl_acrescimo
  • vl_frete
  • pagamentos

Observações:

  • pagamentos é opcional na criação;
  • quando informado, o total dos pagamentos não pode ser maior que o total da venda;
  • use forma_pagamento_id com base nos identificadores publicados em GET /simplificav2/tipo_pagamento.

Atualizar venda

Rota

  • PUT /simplificav2/venda/{id}

Observações:

  • atualiza somente os atributos enviados;
  • exige venda ativa e em aberto;
  • aceita atualizar dados básicos, totais adicionais e itens;
  • se itens for enviado, os itens atuais são substituídos pela nova lista;
  • esta rota não altera pagamentos.

Atualizar pagamentos da venda

Rota

  • PUT /simplificav2/venda/{id}/pagamentos

Observações:

  • substitui a lista atual de pagamentos da venda;
  • use essa rota para incluir, editar, remover ou refazer pagamentos antes da finalização;
  • aceita ajustar vl_acrescimo e vl_frete na mesma chamada;
  • o total dos pagamentos não pode ser maior que o total da venda;
  • não é permitido substituir pagamentos quando já existirem receitas ativas vinculadas.

Finalizar venda

Rota

  • POST /simplificav2/venda/{id}/finalizar

Observações:

  • aceita {} ou corpo vazio;
  • exige venda ativa e em aberto;
  • exige pagamento total correto;
  • valida aprovação da venda antes da finalização;
  • respeita as regras operacionais de cadastro completo do cliente e de estoque quando elas estiverem ativas no sistema.

Gerar venda a partir da oportunidade

Rota

  • POST /simplificav2/oportunidade/{id}/venda

Observações:

  • gera uma venda em aberto a partir de uma oportunidade ativa e pendente;
  • reaproveita os itens ativos da oportunidade;
  • aceita informar pagamentos iniciais;
  • não finaliza a venda automaticamente.

Resposta de sucesso

Todas as operações usam o mesmo retorno mínimo:

1{
2  "status": "sucesso",
3  "mensagem": "Solicitação executada com sucesso.",
4  "data": {
5    "id": 123
6  }
7}