Notas de compra

Como registrar notas de compra na API de Integrações, vinculá-las a fornecedores e gerar contas a pagar.

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.

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

Conceitos e campos-chave

Campo	Tipo	Obrigatório	Observações
`supplier_id`	UUID	Sim	Fornecedor — precisa existir (não há cadastro inline)
`supplier_document_number`	string	Sim	Número do documento do fornecedor (≤ 60)
`product_type`	enum	Sim	`goods`, `service` ou `mixed`
`purchase_date`	date	Sim
`items`	array	Sim	1+ itens
`reference_code`	string	Não	Auto-gerado (`PINV-…`) se omitido
`supplier_document_series`	string	Não	Série do documento
`financial_account_id`	UUID	Não
`financial_category_id`	UUID	Não
`operation_type`	string	Não	Padrão `purchase`
`received_date`, `due_date`	date	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
`taxes`	array	Não	Impostos por item
`payables`	array	Não	Gera contas a pagar (ver abaixo)
`description`, `notes`, `metadata`, `br_data`, `us_data`	—	Não

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.

Gerando contas a pagar

Inclua um array payables[] (amount — decimal como string —, due_date, financial_account_id; opcionais payment_method_id, description). A soma de payables[].amount deve ser exatamente igual ao total líquido da nota (net_payable_total). Se houver mais de um, viram parcelas. Os pagáveis nascem pending, ligados ao supplier_id; consulte-os no recurso /payables (não vêm no corpo da nota).

Criar uma nota de compra (com conta a pagar)

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",
    "supplier_document_number": "12345",
    "supplier_document_series": "1",
    "product_type": "goods",
    "purchase_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"
      }
    ]
  }'

Status e atualização

A nota nasce em status: draft (estados comerciais: draft, finalized, cancelled). No PATCH, status e reference_code não são editáveis, e você não pode alterar itens, impostos ou descontos quando há contas a pagar ativas vinculadas. DELETE /purchase-invoices/{id} remove notas draft/finalized.

Referência dos endpoints

Método	Endpoint	Referência
POST	`/purchase-invoices`	Criar nota de compra
GET	`/purchase-invoices`	Listar notas de compra
GET	`/purchase-invoices/{id}`	Buscar por ID
PATCH	`/purchase-invoices/{id}`	Atualizar
DELETE	`/purchase-invoices/{id}`	Remover