Pedidos de venda

Como criar pedidos de venda na API de Integrações, vinculá-los a orçamentos e gerar contas a receber.

Um pedido de venda (/sales-orders) é a venda confirmada — a etapa central do fluxo de vendas. Ele pode nascer de um orçamento, gerar contas a receber e ser faturado por uma nota.

Permissão exigida: sales-orders (ações create, read, update, delete).

Ciclo de vida

O status de um pedido é draft, confirmed ou cancelled. Na criação, só draft ou confirmed são aceitos — o padrão é confirmed. As transições permitidas via PATCH:

draft → confirmed (confirmar)
draft ou confirmed → cancelled (cancelar)
confirmed → draft é bloqueado

Um pedido cancelled não é editável.

Conceitos e campos-chave

Campo	Tipo	Obrigatório	Observações
`customer_id`	UUID	Sim*	*Ou o objeto `customer` inline — envie um dos dois
`product_type`	enum	Sim	`goods`, `service` ou `mixed`
`order_date`	date	Sim
`items`	array	Sim	1 a 200 itens
`status`	enum	Não	`draft` ou `confirmed` (padrão `confirmed`)
`reference_code`	string	Não	Auto-gerado (`SOR-…`) se omitido
`operation_type`	string	Não	Tipo de operação (padrão `sale`)
`quote_id`	UUID	Não	Orçamento de origem (`product_type` deve casar)
`delivery_date`	date	Não
`salesperson_name`	string	Não
`discount_amount`	string	Não	Desconto em valor (≥ 0) — decimal `numeric(18,6)` como string
`discount_rate`	number	Não	Desconto em percentual (0 a 100) — segue como número
`receivables`	array	Não	Gera contas a receber (ver abaixo)
`metadata`, `br_data`, `notes`, `description`	—	Não

Itens do pedido

quantity e unit_price são strings decimais (ex.: "2.000000", "450.000000"), como em todos os campos decimais da API.

Cada item referencia um product_id (com item_description, quantity e unit_price) ou traz um objeto product inline, que reaproveita/cria o produto pelo reference_code. quantity é ≥ "0.000001" e unit_price ≥ "0".

Gerando contas a receber

Inclua um array receivables[] para já criar os recebíveis do pedido. Cada item exige amount (decimal como string), due_date (date-time) e financial_account_id (ativo); opcionalmente payment_method_id, financial_category_id e description. A resposta traz has_active_receivables e o array receivables do pedido.

Criar um pedido (a partir de um orçamento, com recebível)

curl -X POST https://api.biterp.ai/sales-orders \
  -H "Authorization: Bearer sk_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8f2c1e4a-9b3d-4c7e-a1f2-6d5b8e0c3a71",
    "quote_id": "b1d2f3a4-5c6e-4718-9a0b-2c3d4e5f6a7b",
    "product_type": "goods",
    "order_date": "2026-07-06",
    "status": "confirmed",
    "salesperson_name": "Ana Souza",
    "items": [
      {
        "product_id": "3a7b9c2d-1e4f-4a6b-8c0d-2f5e7a9b1c3d",
        "item_description": "Cadeira ergonômica",
        "quantity": "2.000000",
        "unit_price": "450.000000"
      },
      {
        "product_id": "5d8e1f3a-6b2c-4d7e-9a0f-1c3b5e7d9a2f",
        "item_description": "Mesa de escritório",
        "quantity": "1.000000",
        "unit_price": "1200.000000"
      }
    ],
    "receivables": [
      {
        "amount": "2100.000000",
        "due_date": "2026-08-06T00:00:00.000Z",
        "financial_account_id": "9c8b7a6d-5e4f-4321-8b0a-1d2c3e4f5a6b"
      }
    ]
  }'

Atualizar

No PATCH, os campos customer_id, quote_id, receivables e operation_type não são editáveis. Além disso, você não pode alterar itens nem descontos quando há recebíveis ativos vinculados ao pedido — cancele/ajuste os recebíveis primeiro.

Remover

DELETE /sales-orders/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints

Método	Endpoint	Referência
POST	`/sales-orders`	Criar pedido
GET	`/sales-orders`	Listar pedidos
GET	`/sales-orders/{id}`	Buscar por ID
PATCH	`/sales-orders/{id}`	Atualizar pedido
DELETE	`/sales-orders/{id}`	Remover pedido

Pedidos de venda

Nesta página