Debt Recovery

A API é destinada a gestão de cobranças executadas por escritórios parceiros.

Pré-requisitos

Antes de começar a utilizar a API, é fundamental compreender os requisitos de autenticação e obter as credenciais necessárias.

Certifique-se de revisar a seção de autenticação para garantir uma integração segura e bem-sucedida.

Buscar distribuições

Buscar distribuições de contratos destinadas ao escritório

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/external-agreements/distribution
Method	POST
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Body	initialDistributionDate	Data inicial do filtro
	finalDistributionDate	Data final do filtro

Resposta (Response)

Status	Descrição	Tipo
200	Sem retorno.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
  "partnerName": "string",
  "partnerDocumentNumber": "string",
  "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clients": [
    {
      "clientDocumentNumber": "string",
      "contracts": [
        {
          "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "contractNumber": "string",
          "totalAmount": 0,
          "paymentAmount": 0,
          "debtAmount": 0,
          "originalInstallments": [
            {
              "originalInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "installmentAmount": 0,
              "dueDate": "2025-07-30T13:22:48.295Z",
              "negativated": true,
              "additionalInformation": [
                {
                  "name": "string",
                  "value": "string"
                }
              ]
            }
          ],
          "documents": [
            {
              "url": "string",
              "documentType": "Policy"
            }
          ]
        }
      ]
    }
  ]
}

Registrar um evento

Registra um evento sobre o contrato. Eventos de negociação. Ex: Contato ou não contato com o cliente, promessa de pagamento, agendamento, etc

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/events
Method	POST
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Body	eventId	Id do evento no parceiro - Campo GUID
	ContractId	Id do contrato da pottencial, retornado na api de distribuição
	eventDate	Data do evento
	eventType	Tipo do evento. Enum abaixo
	eventDescription	Descrição do evento, informações adicionais
	eventChannel	Canal do evento. Enum abaixo
	serviceType	Tipo do serviço, se foi receptivo ou ativo. Enum abaixo
	documentBase	Caso seja um evento que contenha anexação de arquivo, aqui deve ser passado o base64 do arquivo
	documentLink	Caso seja um evento que contenha anexação de arquivo, e o arquivo tenha uma url para acessa-lo, aqui vede ser passado essa url
	documentType	Tipo de documento. Enum abaixo

EventType

public enum EventType
    {
        Scheduling = 1,
        PaymentDeclared = 2,
        AttachFile = 3,
        InsufficientRegistration = 4,
        UnknownClient = 5,
        ExternalDebtRecovery = 6,
        ClientContact = 7,
        InboundContact = 8,
        Expense = 9,
        Refund = 10,
        SendLetter = 11,
        SendEmail = 12,
        SendCreditorEmail = 13,
        SendSMS = 14,
        SendWhatsApp = 15,
        Deceased = 16,
        MovedOrLeftCompany = 17,
        DidNotTakeMessage = 18,
        DoesNotRecognizeDebt = 19,
        Notification = 20,
        Note = 21,
        OfferAgreement = 22,
        PaymentPromise = 23,
        Protest = 24,
        VoicemailMessage = 25,
        MessageToThirdParty = 26,
        MessageAtResidence = 27,
        MessageAtWork = 28,
        Complaint = 29,
        UnableToPay = 30,
        FraudSuspicion = 31,
        DebtRecoverySuspension = 32,
        VoicemailPhone = 33,
        DisconnectedPhone = 34,
        NoAnswerPhone = 35,
        NonExistentPhone = 36,
        BusyPhone = 37,
        FaxSignalPhone = 38,
        Other = 39,
        DebtRecoveryReactivation = 40
    }

EventChannel

public enum EventChannel
    {
        Phone = 0,
        Whatsapp = 1,
        Mail = 2,
        SMS = 3,
        Deceased = 4,
        Letter = 5,
        Fax = 6,
        Other = 7,
    }

ServiceType

public enum ServiceType
    {
        Receptiver = 0,
        Active = 1,
        Other = 2,
    }

DocumentType

public enum DocumentType
    {
        Policy = 0,
        Lease = 1,
        Statement = 2,
        Other = 3,
    }

Resposta (Response)

Status	Descrição	Tipo
200	Sem retorno.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Obter eventos de um contrato

Buscar eventos de um determinado contrato .

Requisição (Request)

Url	https://api.pottencial.com.br/contracts/{contractId}/events
Method	GET
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	contractId	Id do contrato.

Resposta (Response)

Status	Descrição	Tipo
200	Obtem eventos do contrato
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
	"eventList": [
		{
			"sequentialId": 1275,
			"contractId": "413cd175-a992-49a7-b44d-d5bf4a5201f6",
			"eventDate": "2025-07-16T13:46:29",
			"eventType": "Other",
			"eventDescription": "",
			"eventChannel": "Other",
			"serviceType": "Other",
			"documentBase": "",
			"documentLink": "",
			"documentType": "",
			"documentExtensionType": "",
			"id": "4efd2707-0001-0000-0000-000000000000",
			"createdDate": "2025-07-17T02:00:02.3133333"
		},
		{
			"sequentialId": 1247,
			"contractId": "413cd175-a992-49a7-b44d-d5bf4a5201f6",
			"eventDate": "2025-07-16T12:15:00",
			"eventType": "DisconnectedPhone",
			"eventDescription": "Evento teste - HML",
			"eventChannel": "SMS",
			"serviceType": "Other",
			"documentBase": "",
			"documentLink": "",
			"documentType": "Policy",
			"documentExtensionType": "Pdf",
			"id": "ae9985c8-aca1-4a2f-a059-82862e759c68",
			"createdDate": "2025-07-16T15:24:59.01"
		}
	],
	"message": "",
	"success": true
}

Realizar simulação de um acordo

Obtem resultados referente a uma simulação de acordo.

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/external-agreements/simulation
Method	POST
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Body	client.documentNumber	Número do documento do cliente (CPF/CNPJ)
	simulationDate	Data da simulação
	installmentsNumber	Número de parcelas
	entryAmount	Valor de entrada
	contracts.contractId	ID do contrato (retornado na rota de distribuição)
	contracts.contractNumber	Número do contrato (retornado na rota de distribuição)
	originalInstallments.originalInstallmentId	IDs das parcelas do contrato (retornado na rota de distribuição)
	discount.debtDiscountAmount	Valor do desconto da dívida. Em percentual
	discount.fineDiscountAmount	Valor do desconto de multas. Em percentual
	discount.feeDiscountAmount	Valor do desconto de taxas. Em percentual
	discount.honoraryDiscountAmount	Valor do desconto de honorários. Em percentual

Exemplo

{
  "client": {
    "documentNumber": "string"
  },
  "simulationDate": "2025-06-26T20:27:28.067Z",
  "installmentsNumber": 0,
  "entryAmount": 0,
  "contracts": [
    {
      "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "contractNumber": "string",
      "originalInstallments": [
        {
          "originalInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      ]
    }
  ],
  "discount": {
    "debtDiscountAmount": 0,
    "fineDiscountAmount": 0,
    "feeDiscountAmount": 0,
    "honoraryDiscountAmount": 0
  }
}

Resposta (Response)

Status	Descrição	Tipo
200	Obtém simulção do acordo.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
  "simulation": {
    "client": {
      "documentNumber": "string"
    },
    "simulationDate": "2025-06-26T21:42:18.284Z",
    "agreementFeeAmount": 0,
    "billetFeeAmount": 0,
    "debtAmount": 0,
    "simulationTotalAmount": 0,
    "simulationMinimalTotalAmount": 0,
    "originalInstallments": [
      {
        "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contractNumber": "string",
        "negociationId": 0,
        "originalInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "installmentNumber": 0,
        "dueDate": "2025-06-26T21:42:18.284Z",
        "debtAmount": 0,
        "fineAmount": 0,
        "feeAmount": 0,
        "expenseAmount": 0,
        "installmentTaxAmount": 0,
        "honoraryAmount": 0,
        "debtDiscountAmount": 0,
        "fineDiscountAmount": 0,
        "feeDiscountAmount": 0,
        "honoraryDiscountAmount": 0,
        "installmentTotalAmount": 0,
        "debtTransferAmount": 0,
        "fineTransferAmount": 0,
        "feeTransferAmount": 0,
        "honoraryTransferAmount": 0,
        "installmentTransferTotalAmount": 0
      }
    ]
  },
  "additionalOptions": [
    {
      "installmentNumber": 0,
      "minimalEntryPercentage": 0,
      "debtDiscountPercentage": 0,
      "fineDiscountPercentage": 0,
      "feeDiscountPercentage": 0,
      "honoraryDiscountPercentage": 0
    }
  ]
}

Registrar um acordo

Cria um acordo. Caso o acordo vá para aprovação, retornará com o agreementStatus ApprovalPending e só será valido após aprovação. Nesse momento em que está aguardando aprovação ele ainda não terá parcelas do acordo

Requisição (Request)

>

Url	https://api.pottencial.com.br/debtrecovery/external-agreements
Method	POST
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Body	client.documentNumber	Número do documento do cliente (CPF/CNPJ)
	client.mail	E-mail hot do cliente
	agreementDate	Data do acordo (Primeira parcela)
	installmentsNumber	Número de parcelas
	entryAmount	Valor de entrada
	contracts.contractId	ID do contrato (retornado na rota de distribuição)
	contracts.contractNumber	Número do contrato (retornado na rota de distribuição)
	originalInstallments.originalInstallmentId	IDs das parcelas do contrato (retornado na rota de distribuição)
	discount.debtDiscountAmount	Valor do desconto da dívida. Em percentual
	discount.fineDiscountAmount	Valor do desconto de multas. Em percentual
	discount.feeDiscountAmount	Valor do desconto de taxas. Em percentual
	discount.honoraryDiscountAmount	Valor do desconto de honorários. Em percentual

Exemplo

{
  "client": {
    "documentNumber": "string",
    "mail": "string"
  },
  "agreementDate": "2025-07-31T12:02:44.594Z",
  "installmentsNumber": 0,
  "entryAmount": 0,
  "contracts": [
    {
      "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "contractNumber": "string",
      "originalInstallments": [
        {
          "originalInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      ]
    }
  ],
  "discount": {
    "debtDiscountAmount": 0,
    "fineDiscountAmount": 0,
    "feeDiscountAmount": 0,
    "honoraryDiscountAmount": 0
  }
}

Resposta (Response)

Status	Descrição	Tipo
200	Acordo criado.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
  "agreement": {
    "agreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "client": {
      "documentNumber": "string"
    },
    "agreementDate": "2025-07-31T12:02:44.596Z",
    "installmentsNumber": 0,
    "agreementMainAmount": 0,
    "agreementFineAmount": 0,
    "agreementFeeAmount": 0,
    "agreementHonoraryAmount": 0,
    "agreementExpenseAmount": 0,
    "agreementInstallmentTaxAmount": 0,
    "agreementDebtDiscountAmount": 0,
    "agreementFineDiscountAmount": 0,
    "agreementFeeDiscountAmount": 0,
    "agreementHonoraryDiscountAmount": 0,
    "agreementTotalAmount": 0,
    "agreementDebtTransferAmount": 0,
    "agreementFineTransferAmount": 0,
    "agreementFeeTransferAmount": 0,
    "agreementInstallmentTransferTotalAmount": 0,
    "agreementStatus": "Active",
    "originalInstallments": [
      {
        "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contractNumber": "string",
        "originalInstallmentId": 0,
        "installmentNumber": 0,
        "dueDate": "2025-07-31T12:02:44.596Z",
        "debtAmount": 0,
        "fineAmount": 0,
        "feeAmount": 0,
        "expenseAmount": 0,
        "honoraryAmount": 0,
        "debtDiscountAmount": 0,
        "fineDiscountAmount": 0,
        "feeDiscountAmount": 0,
        "honoraryDiscountAmount": 0,
        "installmentTotalAmount": 0,
        "debtTransferAmount": 0,
        "fineTransferAmount": 0,
        "feeTransferAmount": 0,
        "installmentTransferTotalAmount": 0
      }
    ],
    "agreementInstallments": [
      {
        "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contractNumber": "string",
        "agreementInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "installmentNumber": 0,
        "installmentAmount": 0,
        "dueDate": "2025-07-31T12:02:44.596Z"
      }
    ]
  }
}

Obter um acordo

Buscar um acordo com seu id

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/external-agreements/{agreementId}
Method	GET
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	agreementId	Id do acordo.

Resposta (Response)

Status	Descrição	Tipo
200	Obtem um acordo
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
  "agreement": {
    "agreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "client": {
      "documentNumber": "string"
    },
    "agreementDate": "2025-07-31T12:13:03.580Z",
    "installmentsNumber": 0,
    "agreementMainAmount": 0,
    "agreementFineAmount": 0,
    "agreementFeeAmount": 0,
    "agreementHonoraryAmount": 0,
    "agreementExpenseAmount": 0,
    "agreementInstallmentTaxAmount": 0,
    "agreementDebtDiscountAmount": 0,
    "agreementFineDiscountAmount": 0,
    "agreementFeeDiscountAmount": 0,
    "agreementHonoraryDiscountAmount": 0,
    "agreementTotalAmount": 0,
    "agreementDebtTransferAmount": 0,
    "agreementFineTransferAmount": 0,
    "agreementFeeTransferAmount": 0,
    "agreementInstallmentTransferTotalAmount": 0,
    "agreementStatus": "Active",
    "originalInstallments": [
      {
        "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contractNumber": "string",
        "originalInstallmentId": 0,
        "installmentNumber": 0,
        "dueDate": "2025-07-31T12:13:03.580Z",
        "debtAmount": 0,
        "fineAmount": 0,
        "feeAmount": 0,
        "expenseAmount": 0,
        "honoraryAmount": 0,
        "debtDiscountAmount": 0,
        "fineDiscountAmount": 0,
        "feeDiscountAmount": 0,
        "honoraryDiscountAmount": 0,
        "installmentTotalAmount": 0,
        "debtTransferAmount": 0,
        "fineTransferAmount": 0,
        "feeTransferAmount": 0,
        "installmentTransferTotalAmount": 0
      }
    ],
    "agreementInstallments": [
      {
        "contractId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contractNumber": "string",
        "agreementInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "installmentNumber": 0,
        "installmentAmount": 0,
        "dueDate": "2025-07-31T12:13:03.580Z"
      }
    ]
  }
}

Quebra de acordo

Necessario passar o Id do acordo para realizar a quebra. Não existe cancelamento ou alteração. Caso haja necessidade de alteração é necessário quebrar e gerar um novo

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/external-agreements/{agreementId}
Method	DELETE
Query	agreementId	Id do acordo
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.

Resposta (Response)

Status	Descrição	Tipo
200	Sem retorno.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Criar boleto

Realiza criação de boletos de um acordo. Caso já exista, será retornado também

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/external-agreements/{agreementId}/boleto
Method	POST
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	AgreementId	Id do acordo.
Body	agreementInstallmentId	Id das parcelas que terão o boleto gerado.

Resposta (Response)

Status	Descrição	Tipo
200	Retorno dos boletos.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

[
  {
    "agreementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agreementInstallmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "string",
    "base64": "string",
    "digitableLine": "string",
    "barCode": "string"
  }
]

Cancelar boleto do acordo

Realiza o cancelamento de boletos de um acordo.

Requisição (Request)

Url	https://api.pottencial.com.br/debtrecovery/external-agreements/{agreementId}/boleto-cancel
Method	POST
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	AgreementId	Id do acordo.
Body	agreementInstallmentId	Id das parcelas que terão o boleto gerado.

Resposta (Response)

Status	Descrição	Tipo
200	Cancelamento com sucesso.
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
429	Quantidade de requisições excede o limite permitido para o período.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Webhooks

Disponibilizamos alguns webhooks para serem utilizados. Para configuração e autenticação: Webhooks

AgreementBroken

Receberá uma notificação em caso de quebra de acordo

Campo	Tipo
RequestId	Identificado do request
EventId	Id do acordo quebrado
PartnerId	Id do escritório
EventType	Tipo do evento (Webhook)

Exemplo

[
  {
    "RequestId": "0df23ac1-eaf8-4607-a679-d78b9d2f91f0",
    "EventId": "218a0fcb-ebcb-486f-b50d-11aa0beb493c",
    "PartnerId": "6d8f0788-7299-45c5-ab0a-c1caa73e6271",
    "EventType": "AgreementBroken"
  }
]

AgreementApproved

Receberá uma notificação caso um acordo que estava pendente de aprovação for aprovado

Campo	Tipo
RequestId	Identificado do request
EventId	Id do acordo aprovado
PartnerId	Id do escritório
EventType	Tipo do evento (Webhook)

Exemplo

[
  {
    "RequestId": "0df23ac1-eaf8-4607-a679-d78b9d2f91f0",
    "EventId": "218a0fcb-ebcb-486f-b50d-11aa0beb493c",
    "PartnerId": "6d8f0788-7299-45c5-ab0a-c1caa73e6271",
    "EventType": "AgreementApproved"
  }
]

InstallmentPaid

Receberá uma notificação caso uma parcela do acordo for paga

Campo	Tipo
RequestId	Identificado do request
EventId	Id da parcela paga
PartnerId	Id do escritório
EventType	Tipo do evento (Webhook)

Exemplo

[
  {
    "RequestId": "0df23ac1-eaf8-4607-a679-d78b9d2f91f0",
    "EventId": "218a0fcb-ebcb-486f-b50d-11aa0beb493c",
    "PartnerId": "6d8f0788-7299-45c5-ab0a-c1caa73e6271",
    "EventType": "InstallmentPaid"
  }
]

InstallmentChargeback

Receberá uma notificação caso um pagamento de uma parcela do acordo for estornado

Campo	Tipo
RequestId	Identificado do request
EventId	Id da parcela estornada
PartnerId	Id do escritório
EventType	Tipo do evento (Webhook)

Exemplo

[
  {
    "RequestId": "0df23ac1-eaf8-4607-a679-d78b9d2f91f0",
    "EventId": "218a0fcb-ebcb-486f-b50d-11aa0beb493c",
    "PartnerId": "6d8f0788-7299-45c5-ab0a-c1caa73e6271",
    "EventType": "InstallmentChargeback"
  }
]

Resolução de erros

ErrorResult

Representa um resultado de erro na chamada da plataforma.

Campo	Tipo	Regras	Descrição
errors	Lista de ErrorMessage	Opcional	Lista de erros da solicitação.

ErrorMessage

Contém informações de um erro.

Campo	Tipo	Regras	Descrição
code	string	Opcional	Código de identificação do erro.
message	string	Opcional	Descrição do erro.