Notas de compra

Uma nota de compra (/purchase-invoices) registra um documento recebido de um fornecedor. É o espelho, no lado das compras, da nota de venda: tem itens, impostos e pode gerar contas a pagar após a finalização.

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

Conceitos e campos-chave

Itens da nota de compra

Cada item tem item_description (obrigatório), quantity (string decimal ≥ "0.000001") e unit_price (string decimal ≥ "0"); product_id é opcional (permite lançar itens sem vínculo a um produto do catálogo). Em atualizações, informe id no item para reconciliação.

Unicidade: não pode haver nota de compra ativa com o mesmo fornecedor, série e número de documento — a segunda tentativa é rejeitada.

Planejamento e materialização de contas a pagar

O fluxo financeiro segue o mesmo princípio do pedido de venda: o create não gera títulos reais.

1. POST /purchase-invoices — inclua payables[] opcional (amount, due_date, financial_account_id obrigatório; opcionais financial_category_id, payment_method_id, description). A soma deve bater com net_payable_total. A nota nasce draft com pending_payables no response (somente leitura).
2. POST /purchase-invoices/{id}/finalize — materializa os payables (purchase-invoices:update) e limpa o snapshot. Só então os títulos aparecem em /payables.

Cada parcela carrega a própria financial_category_id (opcional). Não envie financial_account_id nem financial_category_id no cabeçalho da nota.

Criar uma nota de compra (com parcelas planejadas)

curl -X POST https://api.biterp.ai/purchase-invoices \
  -H "Authorization: Bearer sk_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": "1a2b3c4d-5e6f-4708-9a0b-1c2d3e4f5a6b",
    "invoice_number": "12345",
    "invoice_series": "1",
    "product_type": "goods",
    "issue_date": "2026-07-06",
    "due_date": "2026-08-05",
    "items": [
      {
        "item_description": "Matéria-prima X",
        "quantity": "100.000000",
        "unit_price": "12.500000"
      }
    ],
    "payables": [
      {
        "amount": "1250.000000",
        "due_date": "2026-08-05",
        "financial_account_id": "9c8b7a6d-5e4f-4321-8b0a-1d2c3e4f5a6b"
      }
    ]
  }'

Depois, finalize:

curl -X POST https://api.biterp.ai/purchase-invoices/{id}/finalize \
  -H "Authorization: Bearer sk_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

Status e atualização

A nota nasce em status: draft (estados comerciais: draft, finalized). finalized é terminal — não há cancel nem reopen; para corrigir, exclua e recrie.

No PATCH em draft, payables substitui o snapshot por completo ([] limpa). Se o total mudar sem payables, o snapshot só é preservado quando a soma continuar compatível; caso contrário a API retorna 422. Em finalized, alterações financeiras são bloqueadas.

DELETE /purchase-invoices/{id} remove notas draft/finalized e, quando finalizada, exclui em cascata os payables vinculados (bloqueado se algum já estiver parcial ou pago).

Referência dos endpoints