Skip to main content
POST
Cria uma nova venda no sistema. O valor total é calculado automaticamente com base nos itens. Se não fornecer um código de pedido, será gerado automaticamente.
Você precisa de uma API key válida no header x-api-key para usar este endpoint.
Cálculo Automático: O valor total da venda é calculado automaticamente somando (quantidade × valor unitário) de cada item.

Headers

string
required
application/json
string
required
API key de autenticação

Body

Informações da Venda

string
required
ID do cliente (UUID)Deve ser um cliente cadastrado e ativo
string
required
ID da representada (UUID)Deve ser uma representada cadastrada
string
default:"PAGA"
Status da vendaValores aceitos:
  • PAGA - Venda paga (padrão)
  • AGUARDANDO PAGAMENTO - Aguardando pagamento
  • CANCELADA - Venda cancelada
  • ENVIADA - Venda enviada
  • ENTREGUE - Venda entregue
string
Data da venda no formato YYYY-MM-DDSe não fornecida, usa a data atual
string
Código do pedidoSe não fornecido, gera automaticamente no formato: PED-YYYY-XXXX

Itens da Venda

array
required
Lista de produtos vendidos

Response

Sucesso

boolean
Indica se a operação foi bem-sucedida
object
Dados da venda criada

Erro

string
Mensagem de erro descritiva

Validações

O sistema aplica as seguintes validações:Campos obrigatórios:
  • clienteId: Deve existir e estar ativo
  • representadaId: Deve existir
  • status: Deve ser um status válido
  • itens: Array com pelo menos um item
Validações dos itens:
  • produtoId: Obrigatório
  • quantidade: Maior que zero
  • valorUnitario: Maior que zero
Validações adicionais:
  • Cliente deve pertencer à mesma empresa da API key
  • Data não pode ser futura

Códigos de Pedido

Se o campo pedido não for fornecido, o sistema gera automaticamente:
  • Formato: PED-YYYY-XXXX
  • YYYY = Ano atual
  • XXXX = Número sequencial
  • Exemplos: PED-2024-0001, PED-2024-0002…
  • O código é único por empresa

Cálculo de Valores

Cálculo Automático do Valor Total:O sistema calcula automaticamente:
  1. Valor total de cada item: quantidade × valorUnitario
  2. Valor total da venda: soma de todos os itens
Exemplo:
Não é necessário (nem possível) enviar o valor total - ele sempre será calculado pelo sistema.