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`	string	Não	Desconto em percentual (0 a 100) — decimal `numeric(9,6)` como string
`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").

Cliente embutido nas respostas

Em GET /quotes e GET /quotes/{id}, cada orçamento pode incluir um objeto customer com dados resumidos do cliente vinculado (customer_id). O shape é o mesmo em listagem e detalhe — igual ao de pedidos de venda e notas:

Campo	Tipo	Descrição
`id`	UUID	Identificador do cliente
`legal_name`	string	Razão social ou nome completo
`trade_name`	string	Nome fantasia (pode ser `null`)
`tax_id`	string	Documento fiscal (CPF/CNPJ/EIN…) (pode ser `null`)

"customer": {
  "id": "8f2c1e4a-9b3d-4c7e-a1f2-6d5b8e0c3a71",
  "legal_name": "ACME Comércio Ltda",
  "trade_name": "ACME",
  "tax_id": "12345678000195"
}

Breaking change (2026-08): versões anteriores devolviam ~17 campos no customer embutido (endereço, tax_id_type, metadata, type, website, is_blocked, timestamps, etc.). Esses campos foram removidos do payload de orçamentos. O cadastro completo continua em GET /customers/{id}. Ver o changelog em versionamento.

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.000000",
    "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

A operação Atualizar orçamento aceita os mesmos campos (todos opcionais). Para editar itens, envie o array items: o id de cada item é opcional e determina a reconciliação — quando informado, a linha existente é atualizada; quando ausente, uma nova linha é criada. position é apenas uma dica opcional de ordenação e não define se o item é criado ou atualizado.

Converter em pedido

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

Buscar pelo número do orçamento

Além do UUID, cada orçamento recebe um record_number — um inteiro sequencial por tenant, visível para o usuário e distinto do reference_code. É também o critério de ordenação padrão da listagem.

curl "https://api.biterp.ai/quotes/by-record-number/1042" \
  -H "Authorization: Bearer sk_xxx_yyy"

Retorna 404 se não existir no tenant.

Remover

A operação Remover orçamento faz soft delete e responde 204 No Content. Não há endpoint de restauração — ver DELETE é de mão única.

Consulte a referência OpenAPI de orçamentos para todos os endpoints disponíveis.

Orçamentos

Nesta página