Referência das rotas de negócio

Este catálogo reúne as rotas de negócio dos módulos de cadastro, carteiras, cobrança, comunicação, mandatos, negociação, documentos, financeiro e portal. Ele complementa os guias e o schema OpenAPI da versão do ambiente.

Como interpretar

Nas tabelas de equipe, acrescente /api/v1 ao caminho. A sessão humana ou chave de organização deve satisfazer a permissão indicada, o estado de acesso e os escopos do produto. ou significa que ao menos uma das permissões listadas é exigida. Pessoa indica uma verificação explícita de identidade humana além da permissão; chave de API não executa essa operação.

Na seção Audience, acrescente /api/audience/v1. O usuário precisa de sessão Audience, relationship ativo e autorização específica do portal do credor. Uma membership de equipe ou chave de API não substitui esses requisitos.

O parâmetro com nome terminado em _id não define sozinho o formato. Nas rotas de empresas e membros de uma carteira (/portfolios/{portfolio_id}/companies e /members), a carteira vai pelo código de quatro caracteres ou pelo UUID, e company_id e membership_id (no corpo e no caminho do DELETE) também aceitam um ou outro. Muitos recursos usam o code público de quatro caracteres no caminho e UUID nas associações JSON. Cotações, exceções e outros recursos específicos podem receber UUID. Confirme o schema antes de construir URLs.

Os status e efeitos dependem da regra do comando: exclusão pode ser lógica, uma solicitação pode aguardar aprovação e um recebimento assíncrono pode aguardar processamento. A existência de uma rota não garante que a capacidade ou o conector estejam habilitados.

Devedores e contas

Método	Caminho	Finalidade	Autorização mínima
GET	/debtors	Listar devedores	cobres.debtors.read
POST	/debtors/lookup	Consultar cadastro por CNPJ	cobres.debtors.create ou cobres.debtors.update ou cobres.debtor_accounts.create
POST	/debtors	Cadastrar devedor	cobres.debtors.create
GET	/debtors/{debtor_id}	Consultar devedor	cobres.debtors.read
PATCH	/debtors/{debtor_id}	Editar devedor	cobres.debtors.update
DELETE	/debtors/{debtor_id}	Remover devedor	cobres.debtors.delete
GET	/debtor-accounts	Listar contas por credor	cobres.debtor_accounts.read
POST	/debtor-accounts	Criar ou assegurar conta de devedor	cobres.debtor_accounts.create
GET	/debtor-accounts/{account_id}	Consultar conta	cobres.debtor_accounts.read
DELETE	/debtor-accounts/{account_id}	Remover conta	cobres.debtor_accounts.delete
GET	/debtors/{debtor_id}/addresses	Listar endereços adicionais do devedor (até 20 por devedor)	cobres.debtors.read
POST	/debtors/{debtor_id}/addresses	Cadastrar endereço	cobres.debtors.create ou cobres.debtors.update
GET	/debtors/{debtor_id}/addresses/{address_id}	Consultar endereço	cobres.debtors.read
PATCH	/debtors/{debtor_id}/addresses/{address_id}	Editar endereço	cobres.debtors.update
DELETE	/debtors/{debtor_id}/addresses/{address_id}	Remover endereço	cobres.debtors.delete
GET	/debtors/{debtor_id}/references	Listar referências do devedor (até 50 por devedor)	cobres.debtors.read
POST	/debtors/{debtor_id}/references	Cadastrar referência	cobres.debtors.create ou cobres.debtors.update
GET	/debtors/{debtor_id}/references/{reference_id}	Consultar referência	cobres.debtors.read
PATCH	/debtors/{debtor_id}/references/{reference_id}	Editar referência	cobres.debtors.update
DELETE	/debtors/{debtor_id}/references/{reference_id}	Remover referência	cobres.debtors.delete
GET	/debtors/{debtor_id}/channel-attributes	Listar atributos dos telefones e e-mails conhecidos	cobres.debtors.read
PUT	/debtors/{debtor_id}/channel-attributes	Gravar atributos dos telefones e e-mails (tipo, ramal, ativo, contato)	cobres.debtors.create ou cobres.debtors.update

Origem do cadastro. POST /debtors, PATCH /debtors/{debtor_id}, POST /companies e PATCH /companies/{company_id} aceitam source_system (1 a 64 caracteres) e source_record_id (1 a 80): de onde o registro veio num sistema externo e a chave que ele tinha lá. Os dois vão juntos ou nenhum (422 se vier só um), são aparados, o sistema é guardado e comparado em minúsculas, e a origem é única por organização entre os registros vivos (a mesma origem em outra organização é outro registro). Uma vez definida, a origem não muda nem se limpa: qualquer chamada que cite uma das chaves num registro que já tem origem responde 409 debtor_source_locked ou company_source_locked, e nada mais daquela chamada é gravado. Repetir uma origem de um registro vivo da organização é 409 debtor_source_conflict ou company_source_conflict (o documento ou o CNPJ repetido continua sendo 409 conflict). Para acrescentar a origem a um registro que não tem, use PATCH só com as duas chaves: nada além delas muda. As respostas de GET, POST e PATCH e as linhas de GET /debtors e GET /companies devolvem os dois campos (null sem origem); GET /creditors/{company_id} devolve os da empresa do credor, e POST /creditors também os aceita. O filter das listagens de devedores, empresas, dívidas e acordos aceita source_system e source_record_id (eq, neq, contains, in, is_null; GET /collection/debts aceita só source_record_id) e o q acha pelo source_record_id; em GET /debtors o q tira máscaras como faz com documento e telefone (., -, /, parênteses e espaços), então uma chave com pontuação se acha pelo filter. POST /debtor-accounts também aceita a origem dentro de debtor quando a chamada cria o devedor (mesmos erros); um devedor que já existe é devolvido intacto e a origem enviada é ignorada (use PATCH /debtors/{debtor_id}). Dados extras do sistema de origem vão em metadata, o mapa plano de textos (até 50 entradas, chave de 1 a 64 caracteres, valor de até 500; um PATCH com metadata troca o mapa inteiro).

Dívidas e pesquisa

Método	Caminho	Finalidade	Autorização mínima
GET	/debts	Listar dívidas	cobres.debts.read
POST	/debts	Cadastrar dívida	cobres.debts.create
GET	/debts/{debt_id}	Consultar dívida	cobres.debts.read
PATCH	/debts/{debt_id}	Editar dívida	cobres.debts.update
DELETE	/debts/{debt_id}	Remover dívida	cobres.debts.delete
GET	/search/debts	Pesquisar dívidas por código, documento, nome, referência externa ou número da dívida no sistema de origem (source_record_id; matched diz o que casou)	cobres.debts.read
GET	/debts/{debt_id}/balance	Saldo da dívida em uma data (?on=AAAA-MM-DD; hoje em UTC por padrão): principal e encargos acumulados	cobres.debts.read
GET	/debts/{debt_id}/history	Trilha de alterações da dívida, da mais recente para a mais antiga (limit de 1 a 200, padrão 50; before pagina)	cobres.debts.read
PUT	/debts/{debt_id}/legal	Classificar a situação judicial e a restrição de cobrança (expected_revision, reason, judicial_status, collection_restriction, legal_details)	cobres.debts.update
POST	/debts/{debt_id}/legal-review	Decidir a revisão jurídica (decision: approved ou blocked; expected_revision, reason)	cobres.debts.legal_review
GET	/debts/{debt_id}/workflow-demands	Listar os quadros (demandas) abertos para a dívida e suas atividades	cobres.collection.read

PATCH /debts/{debt_id} e DELETE /debts/{debt_id} exigem reason (3 a 500 caracteres), gravado na trilha da dívida. A dívida carrega o início da dívida (debt_started_on, opcional; PATCH com null limpa) e o prazo da cobrança (limit_on e window_status: none, open, expiring a até 90 dias do limite, expired). GET /debts e GET /collection/debts aceitam ?window_status= (um ou mais valores, repetidos ou por vírgula) e o filter aceita debt_started_on e due_date (datas YYYY-MM-DD; operadores eq, neq, gt, gte, lt, lte, in, is_null; outro formato é 400 listing_invalid). O q das duas listagens e a busca rápida também acham pelo source_record_id, e GET /collection/debts devolve source_record_id. O saldo de GET /debts/{debt_id}/balance traz accrual_source (none, mandate, portfolio, debt), accrual_stop_on e accrual_frozen.

Carteiras e atribuições

Método	Caminho	Finalidade	Autorização mínima
GET	/portfolios	Listar carteiras	cobres.portfolios.read
POST	/portfolios	Criar carteira	cobres.portfolios.manage
GET	/portfolios/{portfolio_id}	Consultar carteira	cobres.portfolios.read
PATCH	/portfolios/{portfolio_id}	Editar carteira	cobres.portfolios.manage
DELETE	/portfolios/{portfolio_id}	Remover carteira	cobres.portfolios.manage
GET	/portfolios/{portfolio_id}/companies	Listar credores da carteira	cobres.portfolios.read
POST	/portfolios/{portfolio_id}/companies	Adicionar credor à carteira	cobres.portfolios.manage
DELETE	/portfolios/{portfolio_id}/companies/{company_id}	Retirar credor da carteira	cobres.portfolios.manage
GET	/portfolios/{portfolio_id}/members	Listar membros da carteira	cobres.portfolios.read
POST	/portfolios/{portfolio_id}/members	Adicionar membro à carteira	cobres.portfolios.manage
DELETE	/portfolios/{portfolio_id}/members/{membership_id}	Retirar membro da carteira	cobres.portfolios.manage
GET	/portfolios/{portfolio_id}/accounts	Listar contas da carteira	cobres.portfolios.read
POST	/portfolios/{portfolio_id}/accounts	Colocar conta na carteira	cobres.assignments.manage
DELETE	/portfolios/{portfolio_id}/accounts/{account_id}	Retirar conta da carteira	cobres.assignments.manage
POST	/portfolios/{portfolio_id}/accounts/{account_id}/move	Mover conta para outra carteira	cobres.assignments.manage
GET	/portfolios/{portfolio_id}/assignments	Listar atribuições	cobres.assignments.read
POST	/portfolios/{portfolio_id}/assignments	Atribuir conta a membro	cobres.assignments.manage
POST	/portfolios/{portfolio_id}/accounts/{account_id}/unassign	Encerrar atribuição da conta	cobres.assignments.manage
GET	/portfolios/{portfolio_id}/responsibilities	Listar responsabilidades por credor	cobres.assignments.read
POST	/portfolios/{portfolio_id}/responsibilities	Atribuir responsabilidade por credor	cobres.assignments.manage
DELETE	/portfolios/{portfolio_id}/responsibilities/{responsibility_id}	Encerrar responsabilidade por credor	cobres.assignments.manage

Cotações, negociação e acordos

Método	Caminho	Finalidade	Autorização mínima
POST	/debts/{debt_id}/quotes	Criar cotação	cobres.quotes.create
GET	/quotes/{quote_id}	Consultar cotação	cobres.quotes.create
POST	/quotes/{quote_id}/exception	Solicitar exceção: abre o cartão Aprovar proposta, decidido pelas transições da demanda (/requests/demands/{código}/transitions)	cobres.offers.request
GET	/offer-approval-requests/{demand_id}	Consultar a proposta de um cartão Aprovar proposta (código da demanda)	cobres.collection.read
GET	/debts/{debt_id}/negotiation-scenarios	Consultar cenários de negociação	cobres.quotes.create
POST	/debts/{debt_id}/offers/evaluate	Avaliar condições da oferta	cobres.quotes.create
GET	/debts/{debt_id}/negotiation-limits	Consultar limites da negociação	cobres.quotes.create
POST	/quotes/{quote_id}/agreement	Gerar acordo pela cotação	cobres.agreements.create
POST	/debts/{debt_id}/agreements	Abrir acordo da dívida	cobres.agreements.create
GET	/debts/{debt_id}/negotiation-state	Consultar estado da negociação	cobres.quotes.create
GET	/agreements	Listar acordos	cobres.agreements.read
GET	/agreements/breach-queue	Consultar fila de quebra	cobres.agreements.break
GET	/agreements/{agreement_id}	Consultar acordo	cobres.agreements.read
GET	/debts/{debt_id}/agreement	Consultar acordo aberto da dívida	cobres.agreements.read
POST	/debts/{debt_id}/lawsuit	Encaminhar a dívida para ajuizamento (abre o cartão "Ajuizar dívida")	cobres.lawsuits.request
GET	/debts/{debt_id}/lawsuit	Consultar o ajuizamento da dívida	cobres.debts.read
GET	/lawsuit-requests/{demand_id}	Consultar a dívida de um cartão "Ajuizar dívida"	cobres.debts.read
GET	/breach-review-requests/{demand_id}	Consultar o acordo de um cartão "Revisar quebra de acordo" (a quebra é decidida nas transições do cartão)	cobres.agreements.read
POST	/debts/{debt_id}/agreements/import	Importar um acordo negociado fora do COBRES (repetir o mesmo source_record_id na mesma dívida não altera nada: 201 se criou, 200 se já existia)	cobres.agreements.import
POST	/agreements/{agreement_id}/steps/take-over	O COBRES assume uma etapa que um sistema externo ainda cobrava (kind, sequence, reason)	cobres.agreements.import

Conectores, conexões e aprovações financeiras

Método	Caminho	Finalidade	Autorização mínima
GET	/finance/connectors	Listar conectores disponíveis	cobres.finance.read ou cobres.finance.connections.manage
GET	/finance/connections	Listar conexões	cobres.finance.read ou cobres.finance.connections.manage
POST	/finance/connections	Instalar conexão	Pessoa; cobres.finance.connections.manage
GET	/finance/connections/{connection_id}	Consultar conexão	cobres.finance.read ou cobres.finance.connections.manage
PATCH	/finance/connections/{connection_id}	Editar conexão	Pessoa; cobres.finance.connections.manage
POST	/finance/connections/{connection_id}/test	Testar conexão	Pessoa; cobres.finance.connections.manage
POST	/finance/connections/{connection_id}/activate	Ativar conexão	Pessoa; cobres.finance.connections.manage
POST	/finance/connections/{connection_id}/pause	Pausar conexão	Pessoa; cobres.finance.connections.manage
POST	/finance/connections/{connection_id}/default	Definir conexão padrão	Pessoa; cobres.finance.connections.manage
DELETE	/finance/connections/{connection_id}	Remover conexão	Pessoa; cobres.finance.connections.manage
POST	/finance/connections/{connection_id}/credentials	Alterar credenciais do conector	Pessoa; cobres.finance.connections.manage
POST	/finance/webhooks/{connection_id}	Receber mensagem do provedor	Contrato de autenticação do conector
GET	/finance/approvals	Listar solicitações de aprovação	cobres.finance.read ou cobres.finance.approve ou cobres.finance.manual_payments.request ou cobres.finance.connections.manage
GET	/finance/approvals/pending-count	Contar aprovações pendentes	cobres.finance.read ou cobres.finance.approve
POST	/finance/approvals/{approval_id}/approve	Aprovar solicitação	Pessoa; cobres.finance.approve
POST	/finance/approvals/{approval_id}/reject	Rejeitar solicitação	Pessoa; cobres.finance.approve
POST	/finance/approvals/{approval_id}/cancel	Cancelar solicitação	Pessoa; cobres.finance.read ou cobres.finance.approve ou cobres.finance.manual_payments.request ou cobres.finance.connections.manage

Cobranças e recebimentos

Uma cobrança criada enquanto a conexão do meio de pagamento do credor está pausada ou em_teste espera: nasce aguardando_emissao com a conexão pretendida e failure_code = awaiting_connection (um motivo, não uma falha), com uma única emissão já aberta (número e referência fixos), e sai sozinha quando a conexão volta a ativa. Sem nenhum meio de pagamento do credor, a cobrança nasce falhou com no_connection; a varredura periódica reemite essas cobranças quando a conexão passa a ser determinável e as marca no_connection_review (reemitir escolhendo a conexão) quando há mais de um meio e nenhum padrão. Quando o acordo é pago por inteiro, a operação de cobrança da dívida é encerrada com o motivo paid e as tarefas abertas são canceladas.

Método	Caminho	Finalidade	Autorização mínima
GET	/finance/settings	Consultar configuração financeira	cobres.finance.read ou cobres.finance.connections.manage
PUT	/finance/settings	Salvar configuração financeira	Pessoa; cobres.finance.connections.manage
GET	/finance/charges	Listar cobranças	cobres.finance.read
GET	/finance/charges/{charge_id}	Consultar cobrança	cobres.finance.read ou cobres.finance.charges.issue
GET	/finance/charges/{charge_id}/pdf	Obter documento da cobrança	cobres.finance.read ou cobres.collection.read ou cobres.agreements.read
GET	/finance/charges/{charge_id}/receipt	Obter o recibo do pagamento (PDF) de uma cobrança paga, entrada ou parcela; não paga: 409 finance_charge_not_paid	cobres.finance.read ou cobres.collection.read ou cobres.agreements.read
GET	/agreements/{agreement_id}/finance/catch-up-quote	Cotar o boleto das parcelas atrasadas: em aberto de cada etapa, dias de atraso, multa e juros calculados (steps=installment:2,installment:3, due_on)	Pessoa ou chave; cobres.finance.charges.manage ou cobres.finance.charges.issue
POST	/agreements/{agreement_id}/finance/catch-up	Gerar um boleto com o valor de várias etapas em aberto (steps, due_on, late_fees_cents à escolha, inclusive 0, charge_after_due); os boletos atuais dessas etapas são substituídos	Pessoa; cobres.finance.charges.manage ou cobres.finance.charges.issue
POST	/finance/charges	Criar cobrança	Pessoa; cobres.finance.charges.manage ou cobres.finance.charges.issue
POST	/finance/charges/{charge_id}/reissue	Reemitir cobrança	Pessoa; cobres.finance.charges.manage ou cobres.finance.charges.issue
POST	/finance/charges/{charge_id}/cancel	Cancelar cobrança	Pessoa; cobres.finance.charges.manage
POST	/finance/charges/{charge_id}/resend	Reenviar cobrança	Pessoa; cobres.finance.charges.manage, cobres.finance.charges.issue ou cobres.collection_messages.send
POST	/finance/charges/{charge_id}/refresh	Consultar agora, no provedor, se o boleto foi pago (202; queued é falso quando já há uma consulta na fila)	Pessoa; cobres.finance.charges.manage, cobres.finance.charges.issue ou cobres.collection_messages.send
POST	/finance/charges/{charge_id}/simulate-payment	Simular pagamento conforme ambiente	Pessoa; cobres.finance.charges.manage
GET	/finance/receipts	Listar recebimentos	cobres.finance.read
POST	/finance/receipts/manual	Solicitar recebimento manual	Pessoa; cobres.finance.manual_payments.request
POST	/finance/receipts/{receipt_id}/reversal	Solicitar estorno	Pessoa; cobres.finance.manual_payments.request
GET	/agreements/{agreement_id}/finance	Consultar financeiro do acordo	cobres.finance.read ou cobres.agreements.read ou cobres.collection.read

Lotes, fechamento e repasses

O worker monta o lote do mês seguinte como rascunho a partir do batch_day (padrão 20), só para organizações com a emissão automática ligada; uma pessoa envia e outra aprova, como em um lote montado à mão (quem tenta montar o mesmo mês recebe 409 finance_batch_exists).

Método	Caminho	Finalidade	Autorização mínima
GET	/finance/batches	Listar lotes	cobres.finance.read ou cobres.finance.charges.manage
GET	/finance/batches/{batch_id}	Consultar lote	cobres.finance.read ou cobres.finance.charges.manage
POST	/finance/batches	Montar lote	Pessoa; cobres.finance.charges.manage
POST	/finance/batches/{batch_id}/submit	Submeter lote	Pessoa; cobres.finance.charges.manage
POST	/finance/batches/{batch_id}/cancel	Cancelar lote	Pessoa; cobres.finance.charges.manage
POST	/finance/charges/{charge_id}/drop-from-batch	Retirar cobrança do lote	Pessoa; cobres.finance.charges.manage
GET	/finance/settlements	Listar fechamentos e repasses	cobres.finance.read ou cobres.finance.settlements.prepare
GET	/finance/settlements/{settlement_id}	Consultar fechamento	cobres.finance.read ou cobres.finance.settlements.prepare
GET	/finance/settlements/{settlement_id}/proof	Consultar comprovante do repasse	cobres.finance.read ou cobres.finance.settlements.prepare
POST	/finance/settlements/open	Abrir fechamentos	Pessoa; cobres.finance.settlements.prepare
POST	/finance/settlements/{settlement_id}/submit	Submeter fechamento	Pessoa; cobres.finance.settlements.prepare
POST	/finance/settlements/{settlement_id}/reopen	Reabrir fechamento	Pessoa; cobres.finance.settlements.prepare
POST	/finance/settlements/{settlement_id}/payout	Solicitar registro do repasse	Pessoa; cobres.finance.settlements.prepare
POST	/finance/adjustments	Solicitar ajuste financeiro	Pessoa; cobres.finance.settlements.prepare
POST	/finance/receipts/{receipt_id}/credit-use	Solicitar utilização de crédito	Pessoa; cobres.finance.manual_payments.request
GET	/finance/connections-health	Consultar saúde das conexões	cobres.finance.read ou cobres.finance.connections.manage

Condições financeiras do credor

Método	Caminho	Finalidade	Autorização mínima
GET	/creditors/{company_id}/finance	Consultar condições do credor	cobres.finance.read ou cobres.creditors.finance.manage ou cobres.creditors.read
PUT	/creditors/{company_id}/finance/rule	Salvar regra financeira do credor	Pessoa; cobres.creditors.finance.manage
PUT	/creditors/{company_id}/finance/payout-account	Solicitar alteração de conta de repasse	Pessoa; cobres.creditors.finance.manage
POST	/creditors/{company_id}/finance/payment-methods	Adicionar meio de pagamento	Pessoa; cobres.creditors.finance.manage
PATCH	/creditors/{company_id}/finance/payment-methods/{method_id}	Editar meio de pagamento	Pessoa; cobres.creditors.finance.manage
DELETE	/creditors/{company_id}/finance/payment-methods/{method_id}	Remover meio de pagamento	Pessoa; cobres.creditors.finance.manage

Administração do portal

Método	Caminho	Finalidade	Autorização mínima
GET	/creditors/{company_id}/portal-users	Listar acessos externos do credor	cobres.creditors.read
POST	/creditors/{company_id}/portal-users	Cadastrar acesso externo	cobres.creditors.update
PATCH	/creditor-portal-users/{user_id}	Editar acesso externo	cobres.creditors.update
DELETE	/creditor-portal-users/{user_id}	Remover acesso externo	cobres.creditors.update
POST	/creditor-portal-users/{user_id}/invite	Enviar convite ao portal	cobres.creditors.update
GET	/portal-submissions	Listar envios do portal	cobres.portal_submissions.review
GET	/portal-submissions/pending-count	Contar envios pendentes	cobres.portal_submissions.review
POST	/portal-submissions/{submission_id}/decision	Decidir revisão do envio	cobres.portal_submissions.review

Portal do credor no plano Audience

Método	Caminho	Finalidade	Autorização mínima
GET	/orgs/{org_id}/credor/me	Consultar acesso atual do credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/notifications	Listar notificações do portal	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/notifications/unread-count	Contar notificações não lidas	Audience + vínculo autorizado do credor
POST	/orgs/{org_id}/credor/notifications/read	Marcar notificações como lidas	Audience + vínculo autorizado do credor
POST	/orgs/{org_id}/credor/notifications/read-all	Marcar todas como lidas	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/debts	Listar dívidas visíveis ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/debts/{debt_id}	Consultar dívida visível ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/agreements	Listar acordos visíveis ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/agreements/{agreement_id}	Consultar acordo visível ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/debtors	Listar devedores visíveis ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/debtors/{debtor_id}	Consultar devedor visível ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/dashboard	Consultar indicadores do portal	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/submissions	Listar próprios envios	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/submissions/{submission_id}	Consultar envio	Audience + vínculo autorizado do credor
POST	/orgs/{org_id}/credor/submissions	Enviar cadastro para revisão	Audience + vínculo autorizado do credor
PUT	/orgs/{org_id}/credor/submissions/{submission_id}	Editar envio permitido	Audience + vínculo autorizado do credor
POST	/orgs/{org_id}/credor/submissions/{submission_id}/cancel	Cancelar envio permitido	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/settlements	Listar repasses visíveis ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/settlements/{settlement_id}	Consultar repasse visível ao credor	Audience + vínculo autorizado do credor
GET	/orgs/{org_id}/credor/settlements/{settlement_id}/proof	Consultar comprovante visível ao credor	Audience + vínculo autorizado do credor

Operação de cobrança e tarefas

Método	Caminho	Finalidade	Autorização mínima
GET	/collection/debts	Listar fila de cobrança	cobres.collection.read
GET	/collection/summary	Consultar resumo da operação	cobres.collection.read
GET	/debts/{debt_id}/collection	Consultar posição operacional da dívida	cobres.collection.read
GET	/debts/{debt_id}/collection/journal	Consultar histórico de movimentações	cobres.collection.read
PUT	/debts/{debt_id}/placement	Definir carteira da dívida	cobres.assignments.manage
PUT	/debts/{debt_id}/assignment	Atribuir responsável pela dívida	cobres.assignments.manage
POST	/debtors/{debtor_id}/contact-channels	Adicionar canal de contato localizado (kind: phone, whatsapp ou email; e-mail só no contato do devedor, não no fiador)	cobres.collection_actions.write
POST	/debtors/{debtor_id}/found-contacts	Cadastrar pessoa de contato localizada	cobres.collection_actions.write
GET	/debtors/{debtor_id}/reach	Consultar alcance e qualidade dos contatos (cada canal traz restorable e os bloqueios de WhatsApp vivos em blocks)	cobres.collection.read
POST	/debtors/{debtor_id}/reach/restore	Desfazer "inutilizável": volta à qualidade anterior (channel_id, ou guarantor_id + kind)	cobres.collection_actions.write
POST	/whatsapp-blocks/{block_id}/undo	Desfazer um bloqueio de WhatsApp	cobres.collection_actions.write
GET	/me/attendance-settings	Configurações de atendimento da pessoa (modo do assistente, abrir junto, faixa compacta) e seus WhatsApps	cobres.collection.read
PUT	/me/attendance-settings	Salvar agent_mode (confirm/auto), assistant_open, band_compact	cobres.collection.read
POST	/me/whatsapp-numbers	Incluir WhatsApp de cobrança (number, label); o primeiro fica em uso	Pessoa; cobres.operator_settings.manage
POST	/me/whatsapp-numbers/{number_id}/primary	Pôr o número em uso	Pessoa; cobres.operator_settings.manage
DELETE	/me/whatsapp-numbers/{number_id}	Tirar o número (o em uso passa ao mais antigo)	Pessoa; cobres.operator_settings.manage
GET	/debts/{debt_id}/timeline	Consultar linha do tempo da dívida (cada ação traz event_type_id, effects e metadata; event_type_id filtra; metadata não filtra)	cobres.collection.read
POST	/debts/{debt_id}/actions	Registrar ação manual de cobrança; com event_type_id (então type é opcional) o tipo de evento decide o tipo de ação, controla o resultado, pode exigir a descrição e aplica seus efeitos; metadata é o mapa plano (igual credor, devedor e dívida), gravado uma vez; whatsapp_block: {operator_number_id} marca que a pessoa bloqueou aquele WhatsApp do operador, sem inutilizar o número dela; devolve {id, event_type_id, effects, metadata}	cobres.collection_actions.write
POST	/collection/actions/{action_id}/corrections	Registrar correção de ação	cobres.collection_actions.write
POST	/collection/actions/{action_id}/pin	Fixar o registro no topo da dívida, para todos (até 10 por dívida; pin_limit)	cobres.collection_actions.write
DELETE	/collection/actions/{action_id}/pin	Desafixar o registro	cobres.collection_actions.write
GET	/collection/tasks	Listar tarefas de cobrança (cada tarefa é uma demanda: code, type_name, stage_label, phase, quick_complete)	cobres.collection.read
POST	/debts/{debt_id}/tasks	Criar tarefa da dívida	cobres.collection_tasks.manage
POST	/collection/tasks/{task_id}/complete	Concluir tarefa (transition_key escolhe o desfecho em quadros com mais de um; next_task cria a próxima)	cobres.collection_tasks.manage
POST	/collection/tasks/{task_id}/reschedule	Reagendar tarefa	cobres.collection_tasks.manage
POST	/collection/tasks/{task_id}/cancel	Cancelar tarefa	cobres.collection_tasks.manage
POST	/debts/{debt_id}/transfer	Transferir dívida conforme escopo	cobres.assignments.transfer
POST	/debts/{debt_id}/collection/suspend	Suspender cobrança	cobres.collection.suspend
POST	/debts/{debt_id}/collection/resume	Retomar cobrança	cobres.collection.resume
POST	/debts/{debt_id}/collection/close	Encerrar operação da dívida	cobres.collection.close
POST	/debts/{debt_id}/collection/reopen	Reabrir operação da dívida	cobres.collection.reopen
GET	/debts/{debt_id}/overview	Consultar visão consolidada da dívida (tasks[] com código, quadro, etapa e quick_complete; debt.qualification, debt.tags, debtor.tags, debtor.groups e pinned_events, cada um com event_type_key, event_type_name, group e effects)	cobres.collection.read
GET	/debts/{debt_id}/feed	Consultar feed da dívida (ações, tarefas e e-mails trazem origin: a origem do registro; a ação traz event_type e effects; tipos ocultos da tela de trabalho só com include_hidden=true)	cobres.collection.read

E-mails e assistência de escrita

Uma mensagem que o provedor provadamente não aceitou (conexão recusada, resposta temporária 4xx do SMTP, 429 do provedor HTTP) volta para a fila e é tentada de novo com atraso crescente (60 s, dobrando, até 30 min), no máximo 6 tentativas, depois fica failed; recusa definitiva (5xx do SMTP, 4xx do provedor HTTP) falha na hora; silêncio ou perda da conexão depois de o envio começar (no provedor HTTP, também 5xx e 408) deixa a mensagem unknown, e ela nunca é reenviada às cegas.

Método	Caminho	Finalidade	Autorização mínima
GET	/collection/email-templates	Listar modelos de e-mail	cobres.collection_templates.read ou cobres.collection_templates.manage
POST	/collection/email-templates	Criar modelo de e-mail (visibility: personal, shared ou official; official exige cobres.collection_templates.manage)	cobres.collection_templates.read ou cobres.collection_templates.manage
PATCH	/collection/email-templates/{template_id}	Revisar modelo de e-mail (o autor revisa o próprio; a gestão revisa os oficiais e compartilhados)	cobres.collection_templates.read ou cobres.collection_templates.manage
POST	/debts/{debt_id}/email-drafts	Criar rascunho vinculado à dívida	cobres.collection_messages.send
PATCH	/collection/email-drafts/{message_id}	Editar rascunho	cobres.collection_messages.send
POST	/collection/email-drafts/{message_id}/send	Solicitar envio do rascunho	cobres.collection_messages.send
POST	/collection/email-messages/{message_id}/read	Marcar mensagem como lida	cobres.collection_messages.read
POST	/collection/email-messages/{message_id}/handled	Marcar mensagem como tratada	cobres.collection_messages.read
POST	/collection/inbox/{message_id}/associate	Associar mensagem recebida	cobres.collection_inbox.triage
GET	/collection/inbox	Consultar caixa de entrada da cobrança	cobres.collection_messages.read
POST	/integrations/collection-email/mailersend	Receber mensagem do provedor de e-mail	Token do callback do provedor; sem sessão de equipe
POST	/collection/writing-assistance	Solicitar assistência de escrita	cobres.collection_ai.use
POST	/collection/plan-phrase	Ler a descrição de uma proposta de acordo (não grava)	cobres.quotes.create

Empresas, grupos e marcadores

Empresas são os cadastros que dão origem aos credores. As rotas de /tags servem a vários tipos de alvo; para empresas, use target_kind: "company" (no filter da listagem, no corpo de criação e em /tag-assignments) e as permissões identity.companies.* abaixo. Os marcadores de dívidas e devedores têm rotas próprias em /collection/tags.

Método	Caminho	Finalidade	Autorização mínima
GET	/companies	Listar empresas	identity.companies.read
POST	/companies/lookup	Consultar dados cadastrais por CNPJ	identity.companies.create ou identity.companies.update
POST	/companies	Cadastrar empresa	identity.companies.create
GET	/companies/{company_id}	Consultar empresa	identity.companies.read
PATCH	/companies/{company_id}	Editar empresa	identity.companies.update
DELETE	/companies/{company_id}	Remover empresa	identity.companies.delete
GET	/companies/{company_id}/contacts	Listar contatos da empresa	identity.companies.read
POST	/companies/{company_id}/contacts	Cadastrar contato	identity.companies.create ou identity.companies.update
GET	/companies/{company_id}/contacts/{contact_id}	Consultar contato	identity.companies.read
PATCH	/companies/{company_id}/contacts/{contact_id}	Editar contato	identity.companies.update
DELETE	/companies/{company_id}/contacts/{contact_id}	Remover contato	identity.companies.delete
GET	/company-groups	Listar grupos de empresas	identity.companies.read
POST	/company-groups	Criar grupo de empresas	identity.companies.create ou identity.companies.update
GET	/company-groups/{group_id}	Consultar grupo	identity.companies.read
PATCH	/company-groups/{group_id}	Editar grupo	identity.companies.update
DELETE	/company-groups/{group_id}	Remover grupo	identity.companies.delete
GET	/company-groups/{group_id}/companies	Listar empresas do grupo	identity.companies.read
GET	/tags	Listar marcadores de um tipo de alvo (filter com target_kind)	identity.companies.read (alvo company)
POST	/tags	Criar marcador (target_kind, name de até 40 caracteres, color #rrggbb)	identity.companies.create ou identity.companies.update (alvo company)
PATCH	/tags/{tag_id}	Renomear ou trocar a cor	identity.companies.update (alvo company)
DELETE	/tags/{tag_id}	Excluir marcador	identity.companies.delete (alvo company)
PUT	/tag-assignments	Substituir os marcadores de um alvo (target_kind, target_id, tag_ids)	identity.companies.update (alvo company)

Credores, mandatos e políticas

Método	Caminho	Finalidade	Autorização mínima
POST	/creditors	Cadastrar credor e mandato inicial	cobres.creditors.create
POST	/creditors/from-company	Criar credor a partir da empresa	cobres.creditors.create
GET	/creditors/{company_id}	Consultar credor	cobres.creditors.read
GET	/mandates/{mandate_id}	Consultar mandato	cobres.mandates.read
GET	/mandates/{mandate_id}/commercial	Consultar política comercial	cobres.commercial_policies.read
PUT	/mandates/{mandate_id}/commercial	Editar rascunho comercial	cobres.commercial_policies.update
POST	/mandates/{mandate_id}/commercial/publications	Publicar política comercial	cobres.commercial_policies.publish
POST	/mandates/{mandate_id}/commercial/publications/{publication_id}/cancel	Cancelar publicação comercial	cobres.commercial_policies.cancel
POST	/mandates/{mandate_id}/commercial/publications/{publication_id}/end	Encerrar vigência comercial	cobres.commercial_policies.end
GET	/mandates/{mandate_id}/negotiation	Consultar política de negociação	cobres.negotiation_policies.read
PUT	/mandates/{mandate_id}/negotiation	Editar rascunho de negociação	cobres.negotiation_policies.update
POST	/mandates/{mandate_id}/negotiation/publications	Publicar política de negociação	cobres.negotiation_policies.publish
POST	/mandates/{mandate_id}/negotiation/publications/{publication_id}/cancel	Cancelar publicação de negociação	cobres.negotiation_policies.cancel
POST	/mandates/{mandate_id}/negotiation/publications/{publication_id}/end	Encerrar vigência de negociação	cobres.negotiation_policies.end
POST	/mandates/{mandate_id}/activate	Ativar mandato	cobres.mandates.activate
POST	/mandates/{mandate_id}/close	Encerrar mandato	cobres.mandates.close
GET	/mandates/{mandate_id}/accrual	Consultar a política de acúmulo (última versão e publicações)	cobres.accrual_policies.read
PUT	/mandates/{mandate_id}/accrual	Editar rascunho de acúmulo	cobres.accrual_policies.update
POST	/mandates/{mandate_id}/accrual/publications	Publicar política de acúmulo	cobres.accrual_policies.publish
POST	/mandates/{mandate_id}/accrual/publications/{publication_id}/cancel	Cancelar publicação de acúmulo	cobres.accrual_policies.cancel
POST	/mandates/{mandate_id}/accrual/publications/{publication_id}/end	Encerrar vigência de acúmulo	cobres.accrual_policies.end
PUT	/mandates/{mandate_id}/approval-route	Definir rota de aprovação do mandato	cobres.approval_routes.update
PUT	/portfolios/{portfolio_id}/approval-route	Definir rota de aprovação da carteira	cobres.approval_routes.update
GET / DELETE	/mandates/{mandate_id}/approval-route	Consultar ou remover a mesa do credor	cobres.approval_routes.update
GET / PUT	/mandates/{mandate_id}/legal-desk	Consultar ou definir o jurídico do credor	cobres.approval_routes.update
GET / PUT	/portfolios/{portfolio_id}/legal-desk	Consultar ou definir o jurídico da carteira	cobres.approval_routes.update
GET / DELETE	/portfolios/{portfolio_id}/approval-route	Consultar ou remover a mesa da carteira	cobres.approval_routes.update
GET	/guardrails	Consultar limites gerais	cobres.guardrails.update
PUT	/guardrails	Editar rascunho dos limites gerais	cobres.guardrails.update
POST	/guardrails/publications	Publicar limites gerais	cobres.guardrails.publish
POST	/guardrails/publications/{publication_id}/cancel	Cancelar publicação dos limites	cobres.guardrails.cancel
POST	/guardrails/publications/{publication_id}/end	Encerrar vigência dos limites	cobres.guardrails.end
GET	/policy-template	Consultar modelo de política	cobres.policy_templates.read
PUT	/policy-template	Salvar modelo de política	cobres.policy_templates.update
GET	/portfolios/{portfolio_id}/negotiation-override	Consultar exceção de negociação da carteira	cobres.portfolio_overrides.read
PUT	/portfolios/{portfolio_id}/negotiation-override	Editar exceção de negociação da carteira	cobres.portfolio_overrides.update
POST	/portfolios/{portfolio_id}/negotiation-override/publications	Publicar exceção da carteira	cobres.portfolio_overrides.publish
POST	/portfolios/{portfolio_id}/negotiation-override/publications/{publication_id}/cancel	Cancelar publicação da exceção	cobres.portfolio_overrides.cancel
POST	/portfolios/{portfolio_id}/negotiation-override/publications/{publication_id}/end	Encerrar vigência da exceção	cobres.portfolio_overrides.end
GET	/debts/{debt_id}/negotiation-envelope	Consultar envelope de negociação da dívida	cobres.negotiation_policies.read
GET	/debts/{debt_id}/overrides	Listar as configurações próprias da dívida	cobres.debt_overrides.read
GET	/debts/{debt_id}/overrides/negotiation	Consultar a negociação da dívida (valor efetivo, origem de cada campo e o herdado)	cobres.debt_overrides.read
PUT	/debts/{debt_id}/overrides/negotiation	Definir a negociação própria da dívida	cobres.debt_overrides.manage
DELETE	/debts/{debt_id}/overrides/negotiation	Voltar a herdar a negociação do credor e da carteira	cobres.debt_overrides.manage
GET	/debts/{debt_id}/overrides/commercial	Consultar a comissão e o repasse da dívida	cobres.debt_overrides.read
PUT	/debts/{debt_id}/overrides/commercial	Definir a comissão e o repasse próprios da dívida	cobres.debt_overrides.manage
DELETE	/debts/{debt_id}/overrides/commercial	Voltar à comissão do contrato do credor	cobres.debt_overrides.manage
GET	/debts/{debt_id}/overrides/accrual	Consultar as faixas de acúmulo da dívida	cobres.debt_overrides.read
PUT	/debts/{debt_id}/overrides/accrual	Definir as faixas de acúmulo próprias da dívida	cobres.debt_overrides.manage
DELETE	/debts/{debt_id}/overrides/accrual	Voltar às faixas de acúmulo do credor	cobres.debt_overrides.manage

Níveis de política e prazo da cobrança

A comissão, a negociação e o acúmulo de uma dívida resolvem em quatro níveis: limite geral (guardrail), mandato do credor, carteira e dívida (a dívida vence a carteira, a carteira vence o mandato, o limite geral corta por último). Cada campo diz de onde vem (mandate, portfolio, debt, guardrail). Na negociação, a carteira (a exceção da mesa) substitui o mandato tanto para afrouxar quanto para apertar. Prazo de quebra (breach_after_days, 0 = nunca) e taxa do parcelamento (agreement_monthly_rate_bps) seguem a mesma ordem (mandate, portfolio, debt).

Método	Caminho	Finalidade	Autorização mínima
GET	/portfolios/{portfolio_id}/overrides	Os três tipos da carteira: kind, overridden, revision	cobres.portfolio_overrides.read
GET	/portfolios/{portfolio_id}/overrides/commercial	Comissão e repasse da carteira ({kind, revision, overridden, override, updated_at, open_debts})	cobres.portfolio_overrides.read
PUT	/portfolios/{portfolio_id}/overrides/commercial	Definir a comissão da carteira: {base_rate_bps, components[6], expected_revision?}	cobres.portfolio_overrides.manage
DELETE	/portfolios/{portfolio_id}/overrides/commercial	Voltar ao contrato do credor (?expected_revision=)	cobres.portfolio_overrides.manage
GET	/portfolios/{portfolio_id}/overrides/negotiation	Negociação da carteira ({kind, revision, overridden, override, updated_at, open_debts}; override por campo {mode: inherit} ou {mode: explicit, value}; revision 0 sem override)	cobres.portfolio_overrides.read
PUT	/portfolios/{portfolio_id}/overrides/negotiation	Definir a negociação da carteira: max_installments, min_installment_cents, min_down_payment_bps, max_grace_days, offer_ttl_days, breach_after_days, agreement_monthly_rate_bps, installment_delay_window, max_discount_bps.{principal,penalty,correction,mora_interest,agreement_interest,fees} e expected_revision?; o que falta herda do mandato, exceto a janela já configurada, que é preservada se omitida	cobres.portfolio_overrides.manage
DELETE	/portfolios/{portfolio_id}/overrides/negotiation	Voltar ao que o mandato do credor diz (?expected_revision=)	cobres.portfolio_overrides.manage
GET	/portfolios/{portfolio_id}/overrides/accrual	Acúmulo da carteira	cobres.portfolio_overrides.read
PUT	/portfolios/{portfolio_id}/overrides/accrual	Definir faixas e parada da carteira: {bands?, stop_after_years_from_start?: {mode, value}, expected_revision?}	cobres.portfolio_overrides.manage
DELETE	/portfolios/{portfolio_id}/overrides/accrual	Voltar ao acúmulo do credor	cobres.portfolio_overrides.manage
GET	/debts/{debt_id}/policy	Política efetiva da dívida com a origem de cada campo e effective_accrual (none, from_mandate, from_portfolio, from_debt); o bloco commercial só com cobres.debt_overrides.read	cobres.debts.read
GET	/collection/settings	Configuração da cobrança (collection_window_years, revision)	cobres.collection.read
PUT	/collection/settings	Alterar o prazo da cobrança em anos (1 a 30; padrão 5): {collection_window_years, expected_revision?}	cobres.collection_settings.manage
GET	/collection/policy-gaps/summary	Selo de "dívidas sem regra": dívidas e saldo sem acúmulo, negociação ou comissão definidos	cobres.policy_gaps.read

PUT e DELETE de carteira respondem 200 com o corpo do GET mais changed; no GET /portfolios/{id}/overrides, overridden é verdadeiro só enquanto há uma publicação em vigor com ao menos um campo explicit (apagar ou salvar tudo inherit o desliga); as rotas /portfolios/{portfolio_id}/negotiation-override (salvar e publicar versão) operam sobre a mesma exceção; expected_revision diferente da atual é 409 version_conflict. O acúmulo aceita stop_after_years_from_start (1 a 30, ou {mode: "explicit", value: null} para "nunca para"): o saldo congela em debt_started_on mais esses anos. Erros: 422 debt_started_on_invalid, collection_window_invalid.

A janela de atraso para parcelamento é um campo independente do teto de parcelas, resolvido por dívida, carteira e credor, nessa ordem. Na carteira ou dívida, envie installment_delay_window: {"mode":"explicit","value":{"from_day":2,"to_day":999}} para substituir a janela herdada, {"mode":"explicit","value":null} para permitir parcelamento independentemente do atraso, ou {"mode":"inherit"} para voltar a herdar. Os dias são inclusivos e usam o vencimento registrado da dívida. A omissão preserva uma janela já definida por aquele nível para compatibilidade com clientes antigos; DELETE continua removendo todas as exceções do nível. A janela não substitui a conferência da composição e do vencimento original de dívidas migradas.

Tipos de evento, qualificações, marcadores e grupos

Cada organização tem o seu catálogo de tipos de evento (uma organização nova recebe 32 de semente, em português, na primeira leitura do catálogo), de qualificações da dívida (10 de semente), de marcadores coloridos em dívidas e devedores e de grupos de devedores. Um tipo de evento aponta para um dos quatro tipos de ação manual (phone_attempt, whatsapp_external, inbound_contact, administrative_note) e declara o que o registro faz: descrição obrigatória, lista de resultados (se existe, o resultado do registro é um deles), qualificação a pôr, aviso ao responsável e um efeito (suspend_collection, com effect_days, ou ask_review). As bandeiras allows_attachment, visible_to_outsourced e replicates_on_inclusion e a próxima ação sugerida (suggested_task_*) são guardadas e devolvidas, sem efeito sobre o registro de ações. Toda alteração de catálogo leva expected_revision (obrigatório no PATCH; 409 catalog_version_conflict); o PATCH manda só o que muda. Exclusão devolve 204 e só vale para o que ninguém usou e não é do sistema; o resto se desativa (active: false). Os catálogos respondem {items: [...]}. Os endereços dos catálogos são uuids; dívida e devedor seguem pelo código público.

Método	Caminho	Finalidade	Autorização mínima
GET	/collection/event-types	Listar os tipos de evento (active=true|false filtra)	cobres.event_types.read
POST	/collection/event-types	Criar um tipo (key, name e action_type obrigatórios)	cobres.event_types.manage
GET	/collection/event-types/{event_type_id}	Consultar um tipo	cobres.event_types.read
PATCH	/collection/event-types/{event_type_id}	Alterar um tipo (expected_revision)	cobres.event_types.manage
DELETE	/collection/event-types/{event_type_id}	Excluir um tipo que nenhum registro usou (409 event_type_in_use; do sistema, 409 event_type_system)	cobres.event_types.manage
GET	/collection/qualifications	Listar as qualificações (active filtra)	cobres.qualifications.read ou cobres.debts.qualify
POST	/collection/qualifications	Criar uma qualificação (key, name)	cobres.qualifications.manage
GET	/collection/qualifications/{qualification_id}	Consultar uma qualificação	cobres.qualifications.read
PATCH	/collection/qualifications/{qualification_id}	Alterar uma qualificação (expected_revision)	cobres.qualifications.manage
DELETE	/collection/qualifications/{qualification_id}	Excluir uma qualificação que ninguém usou (409 qualification_in_use, qualification_system)	cobres.qualifications.manage
GET	/debts/{debt_id}/qualification	Qualificação atual da dívida e histórico (quem, quando, fonte, ação)	cobres.qualifications.read ou cobres.debts.qualify
PUT	/debts/{debt_id}/qualification	Pôr (qualification_id) ou limpar (null) a qualificação, com note opcional	cobres.debts.qualify
GET	/collection/tags	Listar os marcadores (com active, debts_count e debtors_count; active=true|false filtra)	cobres.tags.read
POST	/collection/tags	Criar um marcador (name de até 40 caracteres, color #rrggbb; até 200 por organização)	cobres.tags.manage
PATCH	/collection/tags/{tag_id}	Renomear, trocar a cor ou desativar com active: false (expected_revision); um marcador inativo não se põe em registro novo (422 tag_inactive) e fica onde já está	cobres.tags.manage
DELETE	/collection/tags/{tag_id}	Excluir o marcador e tirá-lo de tudo	cobres.tags.manage
GET	/debts/{debt_id}/tags	Marcadores da dívida	cobres.tags.read
PUT	/debts/{debt_id}/tags	Substituir os marcadores da dívida por tag_ids (até 20)	cobres.tags.apply
GET	/debtors/{debtor_id}/tags	Marcadores do devedor	cobres.tags.read
PUT	/debtors/{debtor_id}/tags	Substituir os marcadores do devedor por tag_ids (até 20)	cobres.tags.apply
GET	/collection/debtor-groups	Listar os grupos de devedores (com active e debtors_count; active=true|false filtra)	cobres.tags.read
POST	/collection/debtor-groups	Criar um grupo (name de até 60 caracteres, note; até 100 por organização)	cobres.tags.manage
PATCH	/collection/debtor-groups/{group_id}	Alterar um grupo ou desativá-lo com active: false (expected_revision); grupo inativo não recebe devedor novo (422 group_inactive)	cobres.tags.manage
DELETE	/collection/debtor-groups/{group_id}	Excluir o grupo (os devedores ficam)	cobres.tags.manage
GET	/debtors/{debtor_id}/groups	Grupos do devedor	cobres.tags.read
PUT	/debtors/{debtor_id}/groups	Substituir os grupos do devedor por group_ids (até 20)	cobres.tags.apply

As listagens GET /debts, GET /collection/debts e GET /debtors aceitam os parâmetros tag, group e qualification (um ou mais uuids do catálogo, repetindo o parâmetro ou separando por vírgula, até 20; dentro de um parâmetro valem como OU e entre parâmetros como E; combinam com filter, q e o cursor; em dívidas group é o grupo do devedor da dívida, e em devedores qualification vale quando uma dívida do devedor a tem). Cada linha de dívida traz qualification ({id, key, name, color, set_at} ou null) e tags; cada linha de devedor, tags e groups. GET /debts/{debt_id} traz qualification e tags, e GET /debtors/{debtor_id}, tags e groups. Erros: 409 catalog_version_conflict, event_type_key_taken, event_type_name_taken, event_type_in_use, event_type_system, qualification_key_taken, qualification_name_taken, qualification_in_use, qualification_system, tag_name_taken, group_name_taken; 422 event_type_inactive, event_type_mismatch, event_description_required, event_outcome_invalid, event_effect_invalid, event_types_limit, qualification_inactive, qualifications_limit, tags_limit, tags_applied_limit, groups_limit, tag_inactive, group_inactive. Num PATCH de catálogo, null só limpa qualification_id, default_result, suggested_task_type, suggested_task_text, suggested_task_days e effect_days do tipo de evento (em qualquer outro campo null é "não enviado"); "" limpa description, note e suggested_task_text; a próxima ação sugerida (suggested_task_type e suggested_task_text) vale junta ou nenhuma, e default_result não existe num tipo administrative_note (400 validation_error).

Documentos, contatos e garantidores

Método	Caminho	Finalidade	Autorização mínima
GET	/documents	Listar documentos visíveis	cobres.documents.read
POST	/documents	Associar arquivo ao assunto de negócio	cobres.documents.create
GET	/documents/{document_id}	Consultar metadados do documento	cobres.documents.read
GET	/documents/{document_id}/url	Obter URL assinada do documento	cobres.documents.read
PATCH	/documents/{document_id}	Editar documento	cobres.documents.update
DELETE	/documents/{document_id}	Remover documento	cobres.documents.delete
GET	/debtors/{debtor_id}/contacts	Listar pessoas de contato do devedor	cobres.debtors.read
POST	/debtors/{debtor_id}/contacts	Cadastrar pessoa de contato	cobres.debtors.create ou cobres.debtors.update
GET	/debtors/{debtor_id}/contacts/{contact_id}	Consultar pessoa de contato	cobres.debtors.read
PATCH	/debtors/{debtor_id}/contacts/{contact_id}	Editar pessoa de contato	cobres.debtors.update
DELETE	/debtors/{debtor_id}/contacts/{contact_id}	Remover pessoa de contato	cobres.debtors.delete
GET	/debtors/{debtor_id}/guarantors	Listar garantidores	cobres.debtors.read
POST	/debtors/{debtor_id}/guarantors	Cadastrar garantidor	cobres.debtors.create ou cobres.debtors.update
GET	/debtors/{debtor_id}/guarantors/{guarantor_id}	Consultar garantidor	cobres.debtors.read
PATCH	/debtors/{debtor_id}/guarantors/{guarantor_id}	Editar garantidor	cobres.debtors.update
DELETE	/debtors/{debtor_id}/guarantors/{guarantor_id}	Remover garantidor	cobres.debtors.delete

Aprovação do credor e evidências

Método	Caminho	Finalidade	Autorização mínima
GET	/creditors/{company_id}/approval-settings	Consultar aprovação exigida pelo credor	cobres.creditors.read
PUT	/creditors/{company_id}/approval-settings	Definir aprovação exigida pelo credor	cobres.creditors.update
POST	/quotes/{quote_id}/creditor-approval	Solicitar aprovação da cotação	cobres.offers.request
POST	/creditor-approvals/{approval_id}/cancel	Cancelar solicitação de aprovação	cobres.offers.request
POST	/debts/{debt_id}/approval-evidence	Iniciar upload de evidência	cobres.offers.record_creditor_approval
POST	/quotes/{quote_id}/creditor-approval/record	Registrar decisão com evidência	cobres.offers.record_creditor_approval
GET	/creditor-approvals/{approval_id}/evidence/{file_id}/url	Obter URL da evidência autorizada	cobres.collection.read
POST	/debts/{debt_id}/offers/authorization-text	Preparar texto de autorização da oferta	cobres.quotes.create

Decisão por link de aprovação

Essas duas portas não usam sessão de equipe. O token do link é a credencial para a proposta e deve ser tratado como dado sensível. A primeira decisão encerra os links elegíveis daquela solicitação; o consumidor deve tratar links inválidos ou encerrados conforme a resposta.

Método	Caminho	Finalidade	Autorização mínima
GET	/public/offer-approvals/{token}	Consultar proposta pelo link	Token específico do link; sem login
POST	/public/offer-approvals/{token}/decision	Registrar decisão pelo link	Token específico do link; sem login

Complementos

Veja o guia da API de cobrança para a sequência dos fluxos. Mandatos e aprovações de credor têm regras de domínio próprias; utilize seus contratos antes de alterar limites ou autorizações. Documentos de negócio complementam o fluxo de arquivos, com regras de assunto e escopo adicionais.

Webhooks do provedor financeiro entram pelo contrato do conector. Webhooks de saída são configurados em outra família de rotas. O cadastro de uma integração não autoriza a chamada indiscriminada de portas públicas ou callbacks de outro fluxo.

A implementação de referência está nos routers de api/app/modules/ e no registro api/app/product/manifest.py. Para detalhes de payload e validação, use o OpenAPI de desenvolvimento da versão correspondente. Leia autenticação, paginação, idempotência e erros antes de implementar um cliente.