A API Assertiva Gestão de Cobrança permite integrar sistemas internos ao ambiente de gestão de dívidas, devedores, carteiras, pagamentos e acordos da Assertiva.

Por meio da API, é possível:

Criar e remover dívidas;
Consultar dívidas por identificador ou documento;
Confirmar e cancelar pagamentos;
Criar, consultar e editar carteiras;
Atualizar dados de devedores;
Consultar probabilidades de recuperação;
Simular acordos;
Cadastrar meios de pagamento externos (Link do boleto ou código de barras);
Receber atualizações por webhooks;
Associar dívidas a carteiras e marcadores.

A integração utiliza o padrão REST, com requisições e respostas no formato JSON.

A documentação completa está disponível na https://integracao.assertivasolucoes.com.br/v3/portal

1. URL base

As requisições devem utilizar a seguinte URL base:

https://api.assertivasolucoes.com.br/gestaodecobranca

Os endpoints da API utilizam o caminho /external/api/v1.

Exemplo:

https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt

2. Autenticação

A API utiliza um Bearer Token temporário, gerado por meio do fluxo OAuth 2.0 client_credentials.

Para gerar o token, são necessárias as credenciais da aplicação:

Client ID;
Secret.

2.1 Endpoint para gerar o token

Método: POST

URL:

https://api.assertivasolucoes.com.br/oauth2/v3/token

2.2 Configuração da requisição

Configure a requisição com:

Authorization: Basic Auth;
Username: Client ID;
Password: Secret;
Content-Type: application/x-www-form-urlencoded;
Parâmetro: grant_type=client_credentials.

Exemplo do corpo:

grant_type=client_credentials

2.3 Exemplo utilizando cURL

curl --request POST \ --url https://api.assertivasolucoes.com.br/oauth2/v3/token \ --user 'SEU_CLIENT_ID:SEU_SECRET' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials'

2.4 Resposta esperada

{ "access_token": "SEU_TOKEN_DE_ACESSO", "token_type": "bearer", "expires_in": 60, "scope": "ALL" }

O campo expires_in informa a validade do token em segundos. A aplicação deve utilizar o valor retornado pela API como referência para renovação.

O material operacional informa uma validade de aproximadamente 30 minutos, enquanto o exemplo da especificação OAuth apresenta expires_in igual a 60 segundos. Para evitar falhas de autenticação, considere sempre o valor efetivamente retornado pelo serviço de autenticação.

2.5 Cabeçalho das requisições

Depois de gerar o token, envie-o em todas as requisições protegidas:

Authorization: Bearer SEU_TOKEN_DE_ACESSO

Para requisições com JSON, utilize também:

Content-Type: application/json

3. Conceitos principais

3.1 Carteira

A carteira agrupa dívidas e define o contexto no qual elas serão gerenciadas.

Cada carteira possui:

Identificador;
Nome;
Status de ativação.

O idWallet é utilizado na criação de dívidas e em consultas relacionadas à recuperação.

3.2 Devedor

O devedor pode ser uma pessoa física ou jurídica, identificado por:

CPF;
CNPJ;
Nome;
Telefones;
Celulares;
E-mails;
Endereço.

3.3 Dívida

A dívida representa uma obrigação financeira e pode conter uma ou mais parcelas.

Cada dívida pode possuir:

Tipo;
Contrato;
Descrição;
Valor;
Parcelas;
Data de vencimento;
Identificador interno;
Identificador personalizado;
Marcadores;
Dados de pagamento.

3.4 Identificadores

A API trabalha principalmente com dois identificadores:

idAPI: identificador gerado internamente pela API;
idCustomDebt: identificador definido pelo sistema integrador.

O idCustomDebt pode ser utilizado para relacionar uma dívida da Assertiva com o identificador correspondente no sistema da empresa.

3.5 Processamento assíncrono

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

4. Criação de dívidas

4.1 Endpoint

Método: POST

Endpoint:

/external/api/v1/debt

URL completa:

https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt

O endpoint recebe uma lista de dívidas. Cada requisição pode conter até 100 dívidas.

4.2 Campos principais

Campo	Obrigatório	Descrição
`canReceiveStatus`	Sim	Indica se o sistema deseja receber atualizações de processamento.
`webhookStatusUrl`	Condicional	URL que receberá os status quando `canReceiveStatus` for `true`.
`filterValue`	Não	Valor livre retornado no callback.
`idWallet`	Sim	Identificador da carteira onde a dívida será incluída.
`debtor`	Sim	Dados do devedor.
`debt`	Sim	Dados da dívida e das parcelas.
`markers`	Não	Lista de marcadores associados ao devedor.

4.3 Tipos de dívida

O campo idTypeDebt aceita os seguintes valores:

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

4.4 Exemplo de requisição

[ { "canReceiveStatus": true, "webhookStatusUrl": "https://seu-dominio.com.br/webhooks/dividas", "filterValue": "pedido-12345", "idWallet": 10, "markers": [ "Ativos", "Vencidas" ], "debtor": { "typeDoc": "CPF", "doc": "12345678901", "name": "Nome do Devedor", "cellPhones": [ { "number": "11999999999", "isrecipientsms": true } ], "emails": [ { "email": "devedor@exemplo.com" } ], "address": { "neighborhood": "Centro", "postalCode": "01000000", "city": "São Paulo", "state": "SP", "streetName": "Rua Principal", "houseNumber": "100", "complement": "Sala 1", "defaultAddress": true } }, "debt": { "description": "Contrato de prestação de serviço", "idTypeDebt": 4, "totalFractions": 2, "idContract": "CONTRATO-123", "fractions": [ { "numberFraction": 1, "value": 500.00, "finalDate": "10/01/2026", "idReference": 1, "idCustomDebt": "DIVIDA-123-1" }, { "numberFraction": 2, "value": 500.00, "finalDate": "10/02/2026", "idReference": 2, "idCustomDebt": "DIVIDA-123-2" } ] } } ]

Formatos importantes

Documentos: somente números;
Telefones: 10 ou 11 dígitos com DDD;
Datas das parcelas: DD/MM/YYYY;
Valores: números decimais em reais;
totalFractions: deve corresponder à quantidade informada em fractions.

4.5 Resposta de criação

A API retorna um identificador de requisição e o resultado do processamento:

{ "idRequest": "ID_DA_REQUISICAO", "result": [ { "idDebtorAPI": "ID_DO_DEVEDOR", "filterValue": "pedido-12345", "status": 1, "message": "Registro enviado para processamento" } ] }

5. Status de criação de dívidas

Quando o recebimento de status está habilitado, a API envia uma requisição POST para a URL informada em webhookStatusUrl.

5.1 Status possíveis

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.

5.2 Exemplo de callback

{ "idDebtorAPI": "ID_DO_DEVEDOR", "filterValue": "pedido-12345", "status": 3, "message": "Registro criado com sucesso", "fractions": [ { "numberFraction": 1, "value": 500.00, "finalDate": "10/01/2026", "idReference": 1, "idCustomDebt": "DIVIDA-123-1", "idAPI": "ID_DA_DIVIDA" } ] }

A URL de callback deve:

Aceitar o método POST;
Utilizar HTTPS;
Validar a origem da requisição, quando aplicável;
Responder rapidamente;
Processar o evento de forma idempotente.

6. Exclusão de dívidas

6.1 Excluir por identificador da API

Método: DELETE

Endpoint:

/external/api/v1/debt

O corpo deve conter a lista idDebtsAPI.

{ "idDebtsAPI": [ "ID_DA_DIVIDA_1", "ID_DA_DIVIDA_2" ] }

A API permite excluir até 50 dívidas por requisição, conforme as regras de validação do serviço.

6.2 Excluir por identificador personalizado

Método: DELETE

Endpoint:

/external/api/v1/debt/id-custom-debt

{ "idCustomDebt": [ "DIVIDA-123-1", "DIVIDA-123-2" ] }

Utilize esse recurso quando a integração controlar as dívidas por identificadores próprios.

7. Consulta de dívidas

7.1 Consultar por `idCustomDebt`

Método: GET

Endpoint:

/external/api/v1/debt/id-custom-debt/{idCustomDebt}

Exemplo:

/external/api/v1/debt/id-custom-debt/DIVIDA-123-1

7.2 Consultar por `idAPI`

Método: GET

Endpoint:

/external/api/v1/debt/id-api/{idApi}

Exemplo:

/external/api/v1/debt/id-api/ID_DA_DIVIDA

7.3 Consultar dívidas por documento

Método: GET

Endpoint:

/external/api/v1/debt/document/{docType}/{doc}

Exemplo:

/external/api/v1/debt/document/CPF/12345678901

Parâmetro opcional

Parâmetro	Valores	Descrição
`debtSituation`	`abertas` ou `pagas`	Filtra as parcelas conforme a situação.

A resposta pode apresentar:

Dados do devedor;
Valor total das dívidas;
Valor total pago;
Valor total em aberto;
Contratos;
Carteiras;
Parcelas;
Situação de cada dívida.

8. Confirmação de pagamento

A confirmação de pagamento registra que uma dívida ou parcela foi paga.

8.1 Confirmar por `idDebtAPI`

Método: POST

Endpoint:

/external/api/v1/debt/confirm-payment

O limite informado na documentação é de até 50 dívidas por requisição.

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

Campos

Campo	Obrigatório	Descrição
`idDebtAPI`	Sim	Identificador da dívida gerado pela API.
`paidValue`	Sim	Valor efetivamente pago.
`payedAt`	Sim	Data do pagamento no formato `YYYY-MM-DD`.
`description`	Não	Descrição do pagamento.

8.2 Confirmar por `idCustomDebt`

Método: POST

Endpoint:

/external/api/v1/debt/confirm-payment/id-custom-debt

[ { "idCustomDebt": "DIVIDA-123-1", "paidValue": 500.00, "payedAt": "2026-01-10", "description": "Pagamento confirmado" } ]

9. Cancelamento da confirmação de pagamento

Caso um pagamento tenha sido confirmado incorretamente, a confirmação pode ser cancelada.

Método: POST

Endpoint:

/external/api/v1/debt/cancel-payment

O corpo pode conter identificadores da API, identificadores personalizados ou ambos:

{ "idsApi": [ "ID_DA_DIVIDA" ], "idsCustomDebt": [ "DIVIDA-123-1" ] }

A resposta informa:

Dívidas processadas com sucesso;
Identificadores inválidos;
Motivos dos registros não processados.

10. Carteiras

As carteiras são utilizadas para organizar as dívidas.

10.1 Criar carteira

Método: POST

Endpoint:

/external/api/v1/wallet

{ "name": "Carteira Janeiro" }

O nome deve:

Ser informado;
Ter no máximo 30 caracteres;
Ser exclusivo dentro da empresa.

10.2 Listar carteiras

Método: GET

Endpoint:

/external/api/v1/wallet

Parâmetros obrigatórios

Parâmetro	Descrição
`size`	Quantidade de itens por página.
`page`	Número da página, iniciando em `0`.

Exemplo:

/external/api/v1/wallet?size=100&page=0

10.3 Consultar carteira por ID

Método: GET

Endpoint:

/external/api/v1/wallet/{idWallet}

10.4 Editar carteira

Método: PUT

Endpoint:

/external/api/v1/wallet/{idWallet}

{ "name": "Carteira Atualizada" }

10.5 Ativar ou desativar carteira

Método: PUT

Endpoint:

/external/api/v1/wallet/{idWallet}/active

{ "active": true }

11. Atualização de dados do devedor

A API permite atualizar informações complementares do devedor.

Método: PATCH

Endpoint:

/external/api/v1/debtor/{idDebtor}

Exemplo:

{ "motherName": "Nome da Mãe", "fatherName": "Nome do Pai", "rgNumber": "123456789", "cellPhones": [ { "number": "11999999999", "isrecipientsms": true } ], "emails": [ { "email": "novoemail@exemplo.com" } ], "address": { "neighborhood": "Centro", "postalCode": "01000000", "city": "São Paulo", "state": "SP", "streetName": "Rua Principal", "houseNumber": "100", "complement": "Sala 1", "defaultAddress": true } }

A atualização pode incluir:

Nome da mãe;
Nome do pai;
RG;
Telefones;
Celulares;
E-mails;
Endereço.

12. Probabilidade de recuperação

Esse recurso retorna dívidas paginadas com informações relacionadas à probabilidade de recuperação e às configurações de comunicação.

Método: GET

Endpoint:

/external/api/v1/debt/recovery-probability/{idWallet}

Parâmetros obrigatórios

Parâmetro	Descrição
`idWallet`	Identificador da carteira.
`size`	Quantidade de registros por página.
`page`	Página consultada, iniciando em `0`.

Parâmetros opcionais

Parâmetro	Valores	Descrição
`probability`	`ideal`, `regular`, `critico`	Filtra pela probabilidade de recuperação.
`notificationStep`	`preventiva`, `no_dia`, `vencida`	Filtra pela etapa de comunicação.

O recurso é aplicável especialmente a carteiras que utilizam cobrança inteligente.

13. Simulação de acordos

A simulação permite obter informações sobre possíveis acordos para as dívidas de um devedor.

Método: POST

Endpoint:

/external/api/v1/agreement/simulation/{document}

O documento deve ser enviado sem pontuação.

Exemplo:

/external/api/v1/agreement/simulation/12345678901

Corpo da requisição

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

É possível informar:

customDebtIds;
apiIds;
Ambas as listas.

A resposta pode apresentar:

Nome e documento do devedor;
Carteiras envolvidas;
Quantidade de dívidas;
Contratos considerados;
Valores das parcelas;
Multas e juros;
Honorários;
Correção monetária;
Desconto máximo;
Valor total da simulação;
IDs inválidos ou não considerados.

14. Meios de pagamento externos

A API permite cadastrar links ou códigos de pagamento associados às dívidas.

14.1 Cadastrar por `idAPI`

Método: POST

Endpoint:

/external/api/v1/payment/external/id-api

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

14.2 Cadastrar por `idCustomDebt`

Método: POST

Endpoint:

/external/api/v1/payment/external/id-custom-debt

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

Regras importantes

O tipo de pagamento documentado é boleto;
O código do boleto deve respeitar o formato exigido;
O domínio utilizado no link deve ser previamente cadastrado junto ao suporte;
Não é permitido adicionar pagamento externo a uma dívida finalizada.

14.3 Remover meio de pagamento por `idAPI`

Método: DELETE

Endpoint:

/external/api/v1/payment/external/id-api

{ "idAPIs": [ "ID_DA_DIVIDA" ] }

14.4 Remover meio de pagamento por `idCustomDebt`

Método: DELETE

Endpoint:

/external/api/v1/payment/external/id-custom-debt

{ "idCustomDebts": [ "DIVIDA-123-1" ] }

15. Webhooks

A API utiliza webhooks para comunicar eventos processados de forma assíncrona.

Os callbacks podem ser utilizados para receber:

Status de criação de dívidas;
Alterações em dívidas;
Criação de acordos.

15.1 Requisitos da URL

A URL de callback deve:

Aceitar o método POST;
Estar disponível externamente;
Utilizar HTTPS;
Responder dentro do tempo esperado;
Possuir autenticação previamente alinhada com o suporte, quando necessário.

15.2 Boas práticas para webhooks

Valide a autenticidade das requisições;
Armazene o payload recebido;
Use uma chave de idempotência para evitar processamento duplicado;
Responda rapidamente e processe o evento em segundo plano;
Registre o status do processamento;
Implemente retentativas internas quando houver falhas;
Não exponha informações sensíveis em logs.

16. Códigos de erro

Código	Significado	Ações recomendadas
`400`	Requisição inválida	Verifique campos obrigatórios, formatos e limites.
`401`	Não autorizado	Gere um novo token e valide as credenciais.
`403`	Acesso proibido	Confirme as permissões do produto e da operação.
`404`	Registro não encontrado	Verifique o identificador ou documento informado.
`500`	Erro interno	Tente novamente e acione o suporte se persistir.

Erros comuns

Lista de dívidas vazia;
Mais de 100 dívidas na criação;
Mais de 50 registros em operações com limite de 50;
Carteira inexistente;
idWallet não informado;
Parcela sem valor ou data;
Data em formato inválido;
CPF ou CNPJ inválido;
Documento enviado com pontuação em um endpoint que exige apenas números;
webhookStatusUrl ausente quando canReceiveStatus é true;
Identificador de dívida inexistente;
Tentativa de operar uma dívida finalizada;
Nome de carteira duplicado;
Nome de carteira com mais de 30 caracteres.

17. Segurança e proteção de dados

A integração pode envolver dados pessoais, informações financeiras e dados de cobrança. Por isso, recomenda-se:

Utilizar os dados somente para finalidades legítimas e autorizadas;
Restringir o acesso por perfil de usuário;
Proteger Client ID, Secret e tokens;
Nunca armazenar credenciais em código público;
Utilizar variáveis de ambiente ou um gerenciador de segredos;
Utilizar HTTPS em todas as comunicações;
Criptografar dados armazenados;
Evitar registrar CPF, CNPJ, tokens e documentos completos em logs;
Controlar o período de retenção das informações;
Manter trilhas de auditoria das operações;
Validar as URLs de webhook;
Não compartilhar dados com sistemas não autorizados.

18. Boas práticas de integração

Armazene os identificadores idRequest, idAPI e idCustomDebt.
Use idCustomDebt para manter a conciliação com o sistema interno.
Valide os dados antes de enviar as requisições.
Controle duplicidade de dívidas, parcelas e pagamentos.
Não repita operações após timeout sem verificar o resultado anterior.
Implemente retentativas com intervalo progressivo para falhas temporárias.
Utilize paginação ao consultar carteiras e dívidas.
Considere o status retornado pelos webhooks como parte do fluxo de processamento.
Implemente idempotência nos endpoints de callback.
Controle a validade do token pelo campo expires_in.
Registre mensagens de erro sem armazenar dados sensíveis.
Separe ambientes de teste e produção.
Faça testes com valores e documentos fictícios antes da liberação.
Mantenha o cadastro de carteiras sincronizado com o sistema interno.

19. Resumo dos endpoints

Funcionalidade	Método	Endpoint
Gerar token	`POST`	`/oauth2/v3/token`
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 dívida por `idCustomDebt`	`GET`	`/external/api/v1/debt/id-custom-debt/{idCustomDebt}`
Consultar dívida por `idAPI`	`GET`	`/external/api/v1/debt/id-api/{idApi}`
Consultar dívidas por documento	`GET`	`/external/api/v1/debt/document/{docType}/{doc}`
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`
Criar carteira	`POST`	`/external/api/v1/wallet`
Listar carteiras	`GET`	`/external/api/v1/wallet`
Consultar carteira	`GET`	`/external/api/v1/wallet/{idWallet}`
Editar carteira	`PUT`	`/external/api/v1/wallet/{idWallet}`
Ativar ou desativar carteira	`PUT`	`/external/api/v1/wallet/{idWallet}/active`
Consultar probabilidade de recuperação	`GET`	`/external/api/v1/debt/recovery-probability/{idWallet}`
Atualizar devedor	`PATCH`	`/external/api/v1/debtor/{idDebtor}`
Simular acordo	`POST`	`/external/api/v1/agreement/simulation/{document}`
Cadastrar pagamento por `idAPI`	`POST`	`/external/api/v1/payment/external/id-api`
Remover pagamento por `idAPI`	`DELETE`	`/external/api/v1/payment/external/id-api`
Cadastrar pagamento por `idCustomDebt`	`POST`	`/external/api/v1/payment/external/id-custom-debt`
Remover pagamento por `idCustomDebt`	`DELETE`	`/external/api/v1/payment/external/id-custom-debt`

20. Documentação e suporte

Para consultar os esquemas completos, parâmetros, exemplos de resposta e regras de cada endpoint, acesse a https://integracao.assertivasolucoes.com.br/v3/portal

Em caso de dúvidas sobre credenciais, permissões ou funcionamento da integração, entre em contato com a Assertiva pelo e-mail:

atendimento@assertivasolucoes.com.br

API Assertiva Gestão de Cobrança

1. URL base

2. Autenticação

2.1 Endpoint para gerar o token

2.2 Configuração da requisição

2.3 Exemplo utilizando cURL

2.4 Resposta esperada

2.5 Cabeçalho das requisições

3. Conceitos principais

3.1 Carteira

3.2 Devedor

3.3 Dívida

3.4 Identificadores

3.5 Processamento assíncrono

4. Criação de dívidas

4.1 Endpoint

4.2 Campos principais

4.3 Tipos de dívida

4.4 Exemplo de requisição

Formatos importantes

4.5 Resposta de criação

5. Status de criação de dívidas

5.1 Status possíveis

5.2 Exemplo de callback

6. Exclusão de dívidas

6.1 Excluir por identificador da API

6.2 Excluir por identificador personalizado

7. Consulta de dívidas

7.1 Consultar por idCustomDebt

7.2 Consultar por idAPI

7.3 Consultar dívidas por documento

Parâmetro opcional

8. Confirmação de pagamento

8.1 Confirmar por idDebtAPI

Campos

8.2 Confirmar por idCustomDebt

9. Cancelamento da confirmação de pagamento

10. Carteiras

10.1 Criar carteira

10.2 Listar carteiras

Parâmetros obrigatórios

10.3 Consultar carteira por ID

10.4 Editar carteira

10.5 Ativar ou desativar carteira

11. Atualização de dados do devedor

12. Probabilidade de recuperação

Parâmetros obrigatórios

Parâmetros opcionais

13. Simulação de acordos

Corpo da requisição

14. Meios de pagamento externos

14.1 Cadastrar por idAPI

14.2 Cadastrar por idCustomDebt

Regras importantes

14.3 Remover meio de pagamento por idAPI

14.4 Remover meio de pagamento por idCustomDebt

15. Webhooks

15.1 Requisitos da URL

15.2 Boas práticas para webhooks

16. Códigos de erro

Erros comuns

17. Segurança e proteção de dados

18. Boas práticas de integração

19. Resumo dos endpoints

20. Documentação e suporte

7.1 Consultar por `idCustomDebt`

7.2 Consultar por `idAPI`

8.1 Confirmar por `idDebtAPI`

8.2 Confirmar por `idCustomDebt`

14.1 Cadastrar por `idAPI`

14.2 Cadastrar por `idCustomDebt`

14.3 Remover meio de pagamento por `idAPI`

14.4 Remover meio de pagamento por `idCustomDebt`