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

Tipo do documento

document_type diz que documento a nota é, e define quais product_type ela aceita. Se o product_type for omitido, vale o padrão do tipo. Combinação fora da tabela é rejeitada com 422.

O tipo é aceito só se valer para o país da empresa. Na resposta, document_type pode vir null em notas antigas que não puderam ser classificadas. O tipo não muda depois de gravado: o PATCH só aceita document_type numa nota antiga que ainda não tem tipo, e nunca aceita limpá-lo. Nota lançada com o tipo errado precisa ser excluída e lançada de novo.

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.

No Brasil, o br_data do item aceita, além de NCM, CEST, CFOP e CST, os códigos do serviço comprado: federal_service_code (código de tributação nacional, até 10), city_service_code (código de tributação municipal, até 50) e nbs_code (NBS, 9 dígitos). Com product_id, os códigos vazios são completados pelo produto.

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

Chaves de acesso (Brasil)

• A nfse_access_key precisa ter o dígito verificador válido. Com outro document_type, junto da nfe_access_key ou já usada por outra nota ativa, ela é rejeitada (422, ou 409 com o código purchase_invoice_nfse_access_key_exists e o purchase_invoice_id da outra nota).
• A nfe_access_key não é aceita numa nota nfse.

Origem do documento

A resposta da nota traz, quando houver, de onde ela veio. São campos só de leitura:

• nfe_import: a NF-e de origem, com as duplicatas do XML sugeridas como parcelas.
• nfse_import: a NFS-e tomada recebida pelo Ambiente Nacional que criou a nota (origin = created) ou que foi vinculada a uma nota lançada à mão (origin = linked). Traz a chave, o líquido declarado (net_amount), o desconto condicionado não aplicado à nota (conditional_discount) e os avisos da importação (warnings).

Cada imposto traz imported_missing_fields: os campos que o documento importado não declarou. Exemplo: base_amount e rate de uma retenção federal da NFS-e, que vêm como 0.

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",
    "document_type": "nfe",
    "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