Casos de uso

Como combinar as operações da API Gestão de Cobrança em fluxos práticos. Os cenários abaixo usam apenas comportamentos descritos na documentação da API.

1. Carteira e inclusão de dívidas

Objetivo: organizar as dívidas em uma carteira antes de incluí-las.

{ "name": "Carteira Janeiro" }

2. Consultar dívidas de um devedor

Objetivo: reunir a situação financeira de um devedor pelo documento.

Use o parâmetro opcional debtSituation (abertas ou pagas) para filtrar as parcelas. A resposta pode trazer dados do devedor, valor total das dívidas, total pago, total em aberto, contratos, carteiras, parcelas e a situação de cada dívida.

curl -X GET \
  "https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt/document/CPF/12345678901?debtSituation=abertas" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt/document/CPF/12345678901");
url.searchParams.set("debtSituation", "abertas");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const dados = await resposta.json();
console.log(dados);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt/document/CPF/12345678901",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"debtSituation": "abertas"},
)
resposta.raise_for_status()
print(resposta.json())

3. Confirmar e cancelar pagamento

Objetivo: registrar o pagamento de uma parcela e desfazer uma confirmação incorreta.

[
  {
    "idDebtAPI": "ID_DA_DIVIDA",
    "paidValue": 500.00,
    "payedAt": "2026-01-10",
    "description": "Pagamento confirmado pelo sistema financeiro"
  }
]

4. Priorizar cobrança pela probabilidade de recuperação

Objetivo: focar esforços nas dívidas com maior chance de recuperação, em carteiras com cobrança inteligente.

Parâmetros obrigatórios: idWallet, size e page (inicia em 0). Filtros opcionais:

5. Simular um acordo

Objetivo: obter condições de acordo para as dívidas de um devedor antes de negociar.

O corpo aceita customDebtIds, apiIds ou ambas as listas. A resposta pode trazer devedor, carteiras, quantidade de dívidas, contratos, valores das parcelas, multas e juros, honorários, correção monetária, desconto máximo, valor total e IDs não considerados.

{
  "customDebtIds": ["DIVIDA-123-1"],
  "apiIds": ["ID_DA_DIVIDA"]
}

6. Cadastrar meio de pagamento externo (boleto)

Objetivo: associar um link ou código de boleto a uma dívida.

• POST /external/api/v1/payment/external/id-api (por idAPI) ou .../id-custom-debt (por idCustomDebt).
• Para remover, use DELETE nos mesmos caminhos.

[
  {
    "idAPI": "ID_DA_DIVIDA",
    "code": "00190500954014481606906809350314337370000000100",
    "type": "boleto",
    "link": "https://seu-dominio.com.br/pagamento/123"
  }
]

7. Receber eventos por webhook

Objetivo: reagir a eventos processados de forma assíncrona (status de criação de dívidas, alterações em dívidas e criação de acordos).

A URL de callback deve:

• Aceitar o método POST e usar HTTPS;
• Estar disponível externamente e responder dentro do tempo esperado;
• Validar a autenticidade das requisições;
• Usar chave de idempotência para evitar processamento duplicado;
• Processar o evento em segundo plano e registrar o status.

Boas práticas