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

1
Authorization: Bearer {{bearer_token}}
2
Content-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
}