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 os campos origin_type, origin_id, sales_order_id nem invoice_id. 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"
  }'

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