> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplificagestao.com.br/llms.txt.
> For full documentation content, see https://docs.simplificagestao.com.br/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplificagestao.com.br/_mcp/server.

# Comercial · vendas

# 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

```http
Authorization: Bearer {{bearer_token}}
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:

```json
{
  "status": "sucesso",
  "mensagem": "Solicitação executada com sucesso.",
  "data": {
    "id": 123
  }
}
```