Contas a receber

Uma conta a receber (/receivables) é um valor que um cliente deve ao tenant, vinculado a uma conta financeira e com data de vencimento. Este recurso é mais do que um CRUD: ele tem uma máquina de estado e o recebimento acontece por alocação de transações.

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

Ciclo de vida

O campo status reflete a situação do recebível:

Um recebível nasce em pending. Conforme você aloca transações (recebe), ele recalcula o status automaticamente: se o valor restante chega a zero, vira paid; se ainda resta algo, vira partial. Remover uma alocação recalcula no sentido inverso (paid → partial → pending). O cancel leva a cancelled.

                        aloca (quita)          aloca (parcial)
   pending ──────────────────► paid    pending ──────────► partial ──► paid
      │                                    │                   │
      │ cancel                             │ remove alocação   │ remove alocação
      ▼                                    ▼                   ▼
  cancelled                            pending             partial/pending

O status overdue não é definido nas suas chamadas — ele é aplicado por uma rotina do sistema quando o vencimento passa e a conta ainda está pending/partial. Você não pode alterar status diretamente (é um campo bloqueado no PATCH); mude o estado usando as ações (allocate, cancel).

Criar uma conta a receber

curl -X POST https://api.biterp.ai/receivables \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "9f1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "financial_account_id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6071",
    "amount": "1500.000000",
    "issue_date": "2026-07-01",
    "due_date": "2026-08-01",
    "description": "Venda de serviços - julho/2026"
  }'

Receber: alocar uma transação

Receber um valor é alocar uma transação de crédito ao recebível. POST /receivables/{id}/allocate:

Regras de validação:

• O recebível não pode estar paid nem cancelled.
• A transação deve pertencer à mesma financial_account_id do recebível e ser um crédito (positiva).
• allocated_amount não pode exceder o valor restante do recebível nem o saldo restante da transação.

O status é recalculado após a alocação, e a transação é marcada como conciliada.

curl -X POST https://api.biterp.ai/receivables/{id}/allocate \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "financial_transaction_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "allocated_amount": "500.000000",
    "notes": "Recebimento parcial via PIX"
  }'

Para desfazer, use DELETE /receivables/{id}/allocate/{allocationId} — a alocação é removida e o status recalculado (204 No Content).

Cancelar

POST /receivables/{id}/cancel cancela o recebível (e suas alocações, de forma atômica). É bloqueado se a conta já estiver paid.

Parcelar

POST /receivables/installments gera várias contas a receber de uma vez, todas com o mesmo installment_group_id:

O total é dividido igualmente (6 casas decimais); as sobras de arredondamento são distribuídas nas primeiras parcelas. O retorno é o array das parcelas criadas.

curl -X POST https://api.biterp.ai/receivables/installments \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "9f1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "financial_account_id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6071",
    "total_amount": "1200.000000",
    "installment_count": 3,
    "issue_date": "2026-07-01",
    "first_due_date": "2026-08-05",
    "reference_code_prefix": "REC-2026-PED-15"
  }'

Vencidas e resumo

• GET /receivables/overdue lista as contas vencidas — critério dinâmico: status pending ou partial e due_date no passado. Retorno paginado.
• GET /receivables/summary retorna um agregado por status, cada linha com a contagem e a soma dos valores:

{
    "data": [
        { "status": "pending", "total_count": 12, "total_amount": "18400.000000" },
        { "status": "paid", "total_count": 30, "total_amount": "52310.500000" }
    ]
}

Filtros

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

Referência dos endpoints