Primeira requisição

Este passo a passo leva você até a criação da primeira dívida, usando o endpoint POST /external/api/v1/debt com um único devedor e duas parcelas como exemplo.

Pré-requisitos

Credenciais

Ter suas credenciais de aplicação (Client ID e Secret).

Token de acesso

Ter gerado um token de acesso — veja Autenticação.

Carteira

Ter uma carteira ativa e o seu idWallet (crie uma com POST /external/api/v1/wallet).

Monte o corpo da criação

O endpoint recebe uma lista de dívidas (até 100 por requisição). Campos principais de cada item:

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.

Os valores abaixo são fictícios, apenas para ilustração. Use dados reais só em produção. Documentos apenas com números, telefones com 10 ou 11 dígitos com DDD, datas das parcelas em DD/MM/YYYY e totalFractions igual à quantidade de fractions.

Faça a chamada

POST /external/api/v1/debt

curl -X POST \
  "https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "canReceiveStatus": true,
      "webhookStatusUrl": "https://seudominio.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" }]
      },
      "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" }
        ]
      }
    }
  ]'

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const dividas = [
  {
    canReceiveStatus: true,
    webhookStatusUrl: "https://seudominio.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" }]
    },
    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" }
      ]
    }
  }
];

const resposta = await fetch("https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(dividas)
});
const dados = await resposta.json();
console.log(dados.idRequest);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

dividas = [
    {
        "canReceiveStatus": True,
        "webhookStatusUrl": "https://seudominio.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"}],
        },
        "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"},
            ],
        },
    }
]

resposta = requests.post(
    "https://api.assertivasolucoes.com.br/gestaodecobranca/external/api/v1/debt",
    headers={"Authorization": f"Bearer {access_token}"},
    json=dividas,
)
resposta.raise_for_status()
print(resposta.json()["idRequest"])

Entenda a resposta

A API retorna um idRequest e o resultado do processamento por registro. Guarde o idRequest e o idCustomDebt para conciliar depois.

Exemplo de resposta (dados fictícios)

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

Acompanhe pelo webhook de status

Como a criação é assíncrona, com canReceiveStatus: true a API envia um POST para a sua webhookStatusUrl a cada atualização:

Código	Status	Descrição
`1`	Em fila	Registro enviado para a fila de processamento.
`2`	Erro	Erro de validação ou dados inconsistentes.
`3`	Criado	Registro criado com sucesso.

Exemplo de callback de status (dados fictícios)

{
  "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 POST, usar HTTPS, responder rapidamente e processar o evento de forma idempotente.

Principais respostas de erro

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

Causas comuns de 400: lista de dívidas vazia, mais de 100 dívidas, idWallet não informado, carteira inexistente, parcela sem valor ou data, data em formato inválido, CPF/CNPJ inválido, documento com pontuação ou webhookStatusUrl ausente quando canReceiveStatus é true.

Próximo passo

Veja como consultar, confirmar pagamentos, simular acordos e usar os webhooks nos casos de uso.