API de cadastro e cobrança

A API de cobrança organiza o cadastro antes da operação. A organização possui credores (companies), devedores (debtors), contas de devedor por credor e dívidas. Carteiras e atribuições determinam o alcance operacional.

Rotas de referência

Todas as rotas abaixo usam o prefixo /api/v1.

Método e rota	Uso
GET /companies	Consultar credores da organização
GET, POST /debtors	Listar e cadastrar devedores
GET, PATCH, DELETE /debtors/{debtor_id}	Consultar, editar e remover conforme regras do cadastro
GET, POST /debtor-accounts	Listar e criar contas entre devedor e credor
GET, POST /debts	Listar e cadastrar dívidas
GET, PATCH, DELETE /debts/{debt_id}	Consultar e manter uma dívida; PATCH e DELETE exigem reason (3 a 500 caracteres) no corpo
GET /portfolios	Listar carteiras acessíveis
GET /collection/debts	Consultar a fila operacional de cobrança
GET /debts/{debt_id}/overview	Obter visão consolidada da dívida
GET /debts/{debt_id}/timeline	Consultar a linha do tempo operacional
POST /debts/{debt_id}/actions	Registrar uma ação de cobrança
POST /debts/{debt_id}/tasks	Criar tarefa para a dívida

Leituras de devedores exigem cobres.debtors.read; criação exige cobres.debtors.create. Dívidas usam a família cobres.debts.*. A permissão não elimina o escopo de empresa, carteira e atribuição.

Origem do registro

Devedores, empresas (credores) e dívidas guardam de onde vieram com o mesmo par de campos, source_system e source_record_id, sempre juntos. O texto do sistema de origem é livre (1 a 64 caracteres) e a chave do registro vai de 1 a 80; quem integra escolhe o nome. A origem do devedor e da empresa é única por organização (a da dívida, por credor), não muda depois de definida (409 debtor_source_locked, company_source_locked, debt_source_locked) e repetida é 409 debtor_source_conflict, company_source_conflict ou debt_source_conflict. Quem integra pode acrescentar a origem a um registro já cadastrado sem origem com PATCH só com os dois campos (na dívida, junto com reason). Detalhes na referência da API.

Criar uma dívida

O devedor deve existir e o credor precisa estar no escopo do ator. O exemplo abaixo é um corpo JSON; substitua o UUID e o documento por dados fictícios válidos no seu ambiente de teste.

{
  "company_id": "00000000-0000-4000-8000-000000000001",
  "debtor": {
    "document_type": "cpf",
    "document_number": "52998224725"
  },
  "original_amount_cents": 125000,
  "due_date": "2026-10-15",
  "description": "Título de demonstração",
  "source_system": "erp-demonstracao",
  "source_record_id": "titulo-123"
}

original_amount_cents deve ser positivo. O valor 125000 representa R$ 1.250,00. source_system e source_record_id devem ser informados juntos. Guarde id e code da resposta para associações e caminhos, respectivamente.

Negociação e acordos

POST /debts/{debt_id}/quotes cria uma cotação. /negotiation-scenarios, /negotiation-limits e /offers/evaluate consultam as possibilidades e limites previstos. A geração de acordo passa por operações próprias de cotações e acordos, incluindo aprovação quando exigida.

Não calcule um acordo apenas alterando o valor original da dívida. Use as regras de mandato, negociação e aprovação do produto. Consulte o schema específico antes de enviar propostas e repita consultas após mudanças de estado.

Veja idempotência, financeiro e erros.