Contas a pagar

Uma conta a pagar (/payables) é um valor que o tenant deve a um fornecedor, vinculado a uma conta financeira. É o espelho de Contas a receber: mesma máquina de estado, alocação, parcelamento, vencidas e resumo — trocando "receber" por "pagar".

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

Ciclo de vida

Os status são os mesmos das contas a receber: pending, partial, paid, overdue, cancelled. Um pagável nasce em pending e caminha para paid conforme você aloca transações de débito (paga). A diferença relevante frente aos recebíveis é que o overdue é aplicado automaticamente ao recalcular: se restar saldo e o due_date já passou, o status vai para overdue (inclusive ao alterar a data de vencimento via PATCH).

Assim como em recebíveis, status é um campo bloqueado no PATCH — mude o estado com as ações (allocate, cancel).

Criar uma conta a pagar

Diferente de recebíveis, contas a pagar não têm sales_order_id nem invoice_id para vincular documentos de venda. O vínculo com o fluxo de compras vem por notas de compra (que geram os pagáveis).

curl -X POST https://api.biterp.ai/payables \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": "1a2b3c4d-5e6f-4708-9a0b-1c2d3e4f5a6b",
    "financial_account_id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6071",
    "amount": "1250.000000",
    "issue_date": "2026-07-06",
    "due_date": "2026-08-05",
    "description": "Compra de matéria-prima"
  }'

Pagar: alocar uma transação

Pagar é alocar uma transação de débito ao pagável. POST /payables/{id}/allocate:

As regras espelham as de recebíveis: o pagável não pode estar paid/cancelled; a transação deve ser da mesma conta e ser um débito (negativa); allocated_amount respeita o saldo restante do pagável e da transação. Use DELETE /payables/{id}/allocate/{allocationId} para desfazer.

curl -X POST https://api.biterp.ai/payables/{id}/allocate \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "financial_transaction_id": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
    "allocated_amount": "500.000000",
    "notes": "Pagamento parcial ao fornecedor"
  }'

O que pode ser alterado, por estado

O PATCH aceita campos diferentes conforme o status do pagável. Depois que o dinheiro se moveu — total (paid) ou parcialmente (partial) — o título descreve um fato consumado, e só continua editável o que não altera esse fato:

Um PATCH com algum campo não permitido para o estado atual retorna 422 nomeando o(s) campo(s) rejeitado(s). E se o status mudar enquanto o PATCH estiver em voo — uma baixa ou um cancelamento concorrente —, a atualização é recusada com 409 em vez de ser aplicada com as regras do estado antigo: releia o registro e repita.

Para alterar qualquer outro campo de um título já baixado, desfaça, estorne ou desvincule o pagamento (DELETE /payables/{id}/allocate/{allocationId}, ou as ações de estorno). A edição total volta quando o status recalculado for pending ou overdue — e quem decide entre os dois é o vencimento, não a ausência de valor baixado: com saldo em aberto e vencimento já passado o título fica overdue, que mantém a edição total mesmo com baixa parcial; ainda dentro do prazo e com valor baixado remanescente — várias baixas, ou um estorno parcial —, ele fica partial e continua restrito. Não há beco sem saída — só a obrigação de passar pela operação que corresponde ao que de fato aconteceu.

financial_category_id continua editável depois da baixa de propósito: a categoria contábil existe apenas no título (a transação financeira não tem esse campo), então corrigir uma classificação errada não teria outro caminho a não ser desfazer e refazer o pagamento.

Cancelar

POST /payables/{id}/cancel cancela o pagável. É bloqueado se ele já estiver paid ou cancelled.

Parcelar

POST /payables/installments funciona como em recebíveis (total_amount — decimal como string —, installment_count de 2 a 120, issue_date, first_due_date, supplier_id, financial_account_id), gerando N pagáveis com installment_group_id comum e vencimentos mensais. A sobra de arredondamento vai na última parcela.

Vencidas e resumo

• GET /payables/overdue — pagáveis com status pending/partial e due_date no passado (paginado).
• GET /payables/summary — agregado por status (status, total_count, total_amount), mesmo formato do resumo de recebíveis.

Filtros

Campos filtráveis em GET /payables: reference_code, status, amount, due_date, issue_date, supplier_id, financial_account_id, financial_category_id, payment_method_id, installment_group_id, created_at, updated_at. Ver paginação e filtros.

Referência dos endpoints