Portal do Desenvolvedor

Gestão de Cobrança — dívidas, carteiras e acordos via API

Integre seus sistemas ao ambiente de gestão de dívidas, devedores, carteiras, pagamentos e acordos da Assertiva. Crie e consulte dívidas, confirme pagamentos, simule acordos e acompanhe a recuperação.

A URL base é https://api.assertivasolucoes.com.br/gestaodecobranca, com os endpoints sob o caminho /external/api/v1. A API usa REST, recebe JSON e exige um token OAuth2 no cabeçalho Authorization: Bearer.

Conceitos principais

Como o produto é organizado

Carteira

Agrupa dívidas e define o contexto de gestão. Possui identificador, nome e status de ativação. O idWallet é usado na criação de dívidas e em consultas de recuperação.

Devedor

Pessoa física ou jurídica identificada por CPF/CNPJ, com nome, telefones, celulares, e-mails e endereço.

Dívida

Obrigação financeira com uma ou mais parcelas. Tem tipo, contrato, descrição, valor, vencimento, marcadores e dados de pagamento.

Identificadores

idAPI é gerado pela API; idCustomDebt é definido pelo integrador para conciliar com o sistema interno.

A criação de dívidas pode ser processada de forma assíncrona: a API retorna o identificador da requisição e os registros são acompanhados por webhook.

O que dá para fazer

Dívidas

Operação	Método	Endpoint
Criar dívidas	`POST`	`/external/api/v1/debt`
Excluir dívidas por idAPI	`DELETE`	`/external/api/v1/debt`
Excluir dívidas por idCustomDebt	`DELETE`	`/external/api/v1/debt/id-custom-debt`
Consultar por idCustomDebt	`GET`	`/external/api/v1/debt/id-custom-debt/{idCustomDebt}`
Consultar por idAPI	`GET`	`/external/api/v1/debt/id-api/{idApi}`
Consultar por documento	`GET`	`/external/api/v1/debt/document/{docType}/{doc}`
Probabilidade de recuperação	`GET`	`/external/api/v1/debt/recovery-probability/{idWallet}`

Pagamentos e acordos

Operação	Método	Endpoint
Confirmar pagamento por idAPI	`POST`	`/external/api/v1/debt/confirm-payment`
Confirmar pagamento por idCustomDebt	`POST`	`/external/api/v1/debt/confirm-payment/id-custom-debt`
Cancelar confirmação de pagamento	`POST`	`/external/api/v1/debt/cancel-payment`
Simular acordo	`POST`	`/external/api/v1/agreement/simulation/{document}`
Cadastrar pagamento externo por idAPI	`POST`	`/external/api/v1/payment/external/id-api`
Cadastrar pagamento externo por idCustomDebt	`POST`	`/external/api/v1/payment/external/id-custom-debt`
Remover pagamento externo por idAPI	`DELETE`	`/external/api/v1/payment/external/id-api`
Remover pagamento externo por idCustomDebt	`DELETE`	`/external/api/v1/payment/external/id-custom-debt`

Carteiras e devedores

Operação	Método	Endpoint
Criar carteira	`POST`	`/external/api/v1/wallet`
Listar carteiras	`GET`	`/external/api/v1/wallet`
Consultar carteira por ID	`GET`	`/external/api/v1/wallet/{idWallet}`
Editar carteira	`PUT`	`/external/api/v1/wallet/{idWallet}`
Ativar/desativar carteira	`PUT`	`/external/api/v1/wallet/{idWallet}/active`
Atualizar devedor	`PATCH`	`/external/api/v1/debtor/{idDebtor}`

Conceitos

Tipos de dívida

O campo idTypeDebt aceita:

Código	Tipo
`1`	Banco ou cartão
`2`	Utilities (água, luz e gás)
`3`	Varejo
`4`	Prestação de serviços

Status de criação de dívidas

Quando o recebimento de status está habilitado, a API envia um POST para webhookStatusUrl com um destes status:

Código	Status	Descrição
`1`	Em fila	O registro foi enviado para a fila de processamento.
`2`	Erro	Ocorreu um erro de validação ou há dados inconsistentes.
`3`	Criado	O registro foi criado com sucesso.

Limites e formatos

Regras importantes

Criação: até 100 dívidas por requisição;
Exclusão e confirmação de pagamento: até 50 registros;
Documentos: somente números;
Telefones: 10 ou 11 dígitos com DDD;
Datas das parcelas: DD/MM/YYYY; pagamento: YYYY-MM-DD;
Nome de carteira: obrigatório, até 30 caracteres e exclusivo na empresa;
totalFractions deve corresponder à quantidade em fractions.

Segurança

Proteção de dados

A integração envolve dados pessoais, financeiros e de cobrança. Proteja Client ID, Secret e tokens (use variáveis de ambiente ou um gerenciador de segredos), use HTTPS e não registre CPF, CNPJ, tokens ou documentos completos em logs.

Próximos passos

Continue a integração

Autenticação

Gere o token de acesso — pré-requisito de todas as chamadas.

Primeira requisição

Crie sua primeira dívida, passo a passo.

Casos de uso

Combine as operações em fluxos reais de cobrança.