Orçamentos

Como criar e manter orçamentos (quotes) com itens na API de Integrações, e sua relação com pedidos de venda.

Um orçamento (/quotes) é uma proposta comercial: um cliente, uma lista de itens e valores, com validade. É a primeira etapa do fluxo de vendas — sem compromisso financeiro até virar um pedido.

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

Conceitos e campos-chave

Campo	Tipo	Obrigatório	Observações
`customer_id`	UUID	Sim	Cliente da proposta
`product_type`	enum	Sim	`goods`, `service` ou `mixed`
`items`	array	Sim	1 a 200 itens (ver abaixo)
`status`	enum	Não	`pending`, `approved`, `rejected`, `expired`
`reference_code`	string	Não	Auto-gerado (`QTE-…`) se omitido
`quote_date`	date	Não
`valid_until`	date	Não	Validade da proposta
`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; ex.: `10` = 10%) — segue como número
`description`, `tax_notes`, `payment_notes`	string	Não
`metadata`	object	Não

Itens do orçamento

quantity e unit_price são strings decimais (numeric(18,6)), como em pedidos e notas — o mesmo payload de itens vale para os três recursos.

Campo	Tipo	Obrigatório	Observações
`product_id`	UUID	Sim	Produto do catálogo (não há produto inline)
`item_description`	string	Sim	Máx. 256 caracteres
`quantity`	string	Sim	Decimal positivo (ex.: `"2.000000"`, `"0.500000"`)
`unit_price`	string	Sim	Decimal ≥ 0 (ex.: `"450.000000"`)
`discount_amount`	string	Não	Decimal ≥ 0

Os totais (subtotal, total_discount, total) são calculados pela API e retornados como strings decimais na resposta (ex.: "2100.000000").

Criar um orçamento

curl -X POST https://api.biterp.ai/quotes \
  -H "Authorization: Bearer sk_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8f2c1e4a-9b3d-4c7e-a1f2-6d5b8e0c3a71",
    "product_type": "goods",
    "quote_date": "2026-07-06",
    "valid_until": "2026-07-20",
    "salesperson_name": "Ana Souza",
    "discount_rate": 5,
    "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"
      }
    ]
  }'

Atualizar

PATCH /quotes/{id} aceita os mesmos campos (todos opcionais). Para editar itens, envie o array items com position no item que deseja alterar; itens sem position são criados.

Não há endpoint de conversão. Para transformar um orçamento em venda, crie um pedido de venda enviando o quote_id — a API valida que o product_type do pedido casa com o do orçamento. Ver o fluxo de vendas.

Remover

DELETE /quotes/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints

Método	Endpoint	Referência
POST	`/quotes`	Criar orçamento
GET	`/quotes`	Listar orçamentos
GET	`/quotes/{id}`	Buscar por ID
PATCH	`/quotes/{id}`	Atualizar orçamento
DELETE	`/quotes/{id}`	Remover orçamento