1 Visão geral
A Collections API recebe email e
cpf de um devedor e retorna uma avaliação
de prioridade de recuperação, canal de contato recomendado, propensão de pagamento e estratégia de cobrança.
Recovery Index (0–1000)
recovery_index.score — quanto maior, maior a prioridade de recuperação.
Elegibilidade de contato
contact_eligibility indica se o devedor pode ser acionado e eventuais restrições.
Canal recomendado
recommended_contacts traz o melhor canal e a qualidade do contato disponível.
Estratégia de cobrança
collection_strategy sugere abordagem, prioridade e próxima ação.
2 Autenticação
Troque sua X-Api-Key por um
access_token (Bearer, válido por 1h).
curl -X POST https://collections.autentify.com.br/v1/auth/token \
-H "X-Api-Key: ak_live_xxx"
Resposta:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600,
"expires_at": 1781234567
}
Reaproveite o token até pouco antes de expires_at — gerar tokens em excesso pode ser limitado por rate limit.
3 Analisar cobrança
POST /v1/analyze
Authorization: Bearer <access_token>
Content-Type: application/json
{
"payload": {
"email": "cliente@empresa.com",
"cpf": "12345678901"
}
}
Notas de contrato
request_idé opcional; se ausente, a API gera automaticamente.schema_versioné opcional (defaultv1).channelé opcional para chamadas externas e assumeapi.cpfaceita com ou sem máscara; é normalizado para 11 dígitos.
4 Resposta completa
Exemplo real de retorno do endpoint /v1/analyze:
{
"request_id": "col_8f2a71c9d4",
"recovery_assessment": {
"classification": "HIGH_RECOVERY_PRIORITY",
"score": 876,
"recommended_action": "PRIORITIZE_COLLECTION"
},
"recovery_index": {
"name": "Autentify Recovery Index",
"score": 876,
"class": "HIGH_RECOVERY_PRIORITY",
"label": "Alta prioridade de recuperação"
},
"contact_eligibility": {
"status": "ELIGIBLE",
"restrictions": []
},
"recommended_contacts": {
"primary_channel": "PHONE",
"phones": [
{
"rank": 1,
"number": "+55 11 9XXXX-4321",
"contact_potential": "HIGH",
"whatsapp_available": true,
"best_contact_window": "18:00-21:00"
},
{
"rank": 2,
"number": "+55 11 9XXXX-8765",
"contact_potential": "MEDIUM",
"whatsapp_available": false,
"best_contact_window": "09:00-12:00"
}
],
"email": {
"address": "t********@gmail.com",
"cpf_link": "CONFIRMED",
"link_strength": "VERY_HIGH",
"deliverability_status": "VALID",
"channel_quality": "HIGH"
},
"recommended_contact": {
"value": "+55 11 9XXXX-4321",
"best_contact_window": "18:00-21:00"
}
},
"payment_propensity": {
"classification": "VERY_HIGH",
"score": 798
},
"collection_profile": {
"digital_affinity": {
"level": "HIGH",
"label": "Alta afinidade digital"
},
"negotiation_capacity": {
"level": "MODERATE",
"label": "Capacidade indicativa de negociação moderada"
},
"collection_insight": "Perfil com boa aderência a abordagens digitais na régua de cobrança.",
"negotiation_insight": "Perfil com sinal intermediário de capacidade econômica, sugerindo abordagem de cobrança com opções flexíveis de negociação."
},
"recovery_cluster": {
"code": "HIGH_RECOVERY_POTENTIAL",
"label": "Alto potencial de recuperação",
"description": "Registro com alta prioridade para acionamento no primeiro ciclo de cobrança."
},
"collection_strategy": {
"suggested_approach": "WHATSAPP_THEN_PHONE",
"recommended_priority": "HIGH_PRIORITY_QUEUE",
"action_recommendation": "Priorizar contato via WhatsApp seguido de telefone na janela de maior potencial."
},
"reasons": [
"Registro elegível para acionamento de cobrança",
"Registro analisado com sinais suficientes para priorização operacional",
"Perfil avaliado conforme política de cobrança vigente"
],
"executive_summary": {
"headline": "Contato com alta prioridade de recuperação",
"summary": "O e-mail analisado apresenta vínculo confirmado com o CPF em uma das fontes de validação utilizadas pela Autentify e está válido para acionamento digital. Isso torna o registro prioritário para cobrança. A propensão estimada de pagamento ajusta sua posição dentro da fila de recuperação. Recomenda-se incluí-lo na régua prioritária e utilizar os canais complementares disponíveis."
}
}
5 Dicionário de campos
Raiz da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| request_id | string | Identificador único da requisição. |
recovery_assessment & recovery_index
| Campo | Tipo | Descrição |
|---|---|---|
| recovery_assessment.classification | string | Classificação: LOW_RECOVERY_PRIORITY, MEDIUM_RECOVERY_PRIORITY, HIGH_RECOVERY_PRIORITY. |
| recovery_assessment.score | integer | Score de recuperação, de 0 a 1000. |
| recovery_assessment.recommended_action | string | Ação recomendada: LOW_PRIORITY_QUEUE, PRIORITIZE_COLLECTION, IMMEDIATE_CONTACT. |
| recovery_index.name | string | Nome do índice ("Autentify Recovery Index"). |
| recovery_index.score | integer | Mesmo score de recovery_assessment.score. |
| recovery_index.class | string | Mesma classificação de recovery_assessment.classification. |
| recovery_index.label | string | Rótulo amigável em PT-BR para exibição. |
contact_eligibility
| Campo | Tipo | Descrição |
|---|---|---|
| status | string | ELIGIBLE ou NOT_ELIGIBLE — se o devedor pode ser acionado. |
| restrictions | array | Lista de restrições aplicáveis (vazia quando não há). |
recommended_contacts
| Campo | Tipo | Descrição |
|---|---|---|
| primary_channel | string | Canal recomendado: EMAIL, PHONE, WHATSAPP. |
| phones[] | array | Telefones qualificados, ordenados por rank (vazio quando nenhum é encontrado). |
| phones[].rank | integer | Posição de prioridade do telefone (1 = melhor). |
| phones[].number | string | Número de telefone (mascarado em modo demo). |
| phones[].contact_potential | string | Potencial de contato: LOW, MEDIUM, HIGH. |
| phones[].whatsapp_available | boolean | Se o número está disponível no WhatsApp. |
| phones[].best_contact_window | string | Janela de horário recomendada para contato (ex.: "18:00-21:00"). |
| email.address | string | E-mail (mascarado em modo demo). |
| email.cpf_link | string | Tipo de vínculo com CPF: CONFIRMED, WEAK, NONE. |
| email.link_strength | string | Força do vínculo: LOW, MEDIUM, HIGH, VERY_HIGH. |
| email.deliverability_status | string | Status de entregabilidade: VALID, RISKY, INVALID. |
| email.channel_quality | string | Qualidade do canal: LOW, MEDIUM, HIGH. |
| recommended_contact | object | null | Contato preferencial; null quando não há canal claramente superior. |
| recommended_contact.value | string | Valor do contato recomendado (telefone ou e-mail). |
| recommended_contact.best_contact_window | string | Janela de horário recomendada. |
payment_propensity
| Campo | Tipo | Descrição |
|---|---|---|
| classification | string | Propensão de pagamento: LOW, MODERATE, HIGH, VERY_HIGH. |
| score | integer | Score de propensão, de 0 a 1000. |
collection_profile
| Campo | Tipo | Descrição |
|---|---|---|
| digital_affinity.level | string | Afinidade digital: UNKNOWN, LOW, MODERATE, HIGH. |
| digital_affinity.label | string | Rótulo em PT-BR para exibição. |
| negotiation_capacity.level | string | Capacidade de negociação: UNKNOWN, LOW, MODERATE, HIGH. |
| negotiation_capacity.label | string | Rótulo em PT-BR para exibição. |
| collection_insight | string | Texto explicativo sobre a afinidade digital. |
| negotiation_insight | string | Texto explicativo sobre a capacidade de negociação. |
recovery_cluster & collection_strategy
| Campo | Tipo | Descrição |
|---|---|---|
| recovery_cluster.code | string | Cluster: LOW_RECOVERY_POTENTIAL, MEDIUM_RECOVERY_POTENTIAL, HIGH_RECOVERY_POTENTIAL. |
| recovery_cluster.label | string | Rótulo amigável do cluster. |
| recovery_cluster.description | string | Descrição operacional do cluster. |
| collection_strategy.suggested_approach | string | Abordagem sugerida: REVIEW_BEFORE_CONTACT, WHATSAPP_THEN_PHONE, DIRECT_CONTACT. |
| collection_strategy.recommended_priority | string | Fila recomendada: LOW_PRIORITY_QUEUE, HIGH_PRIORITY_QUEUE. |
| collection_strategy.action_recommendation | string | Próxima ação recomendada em texto. |
reasons & executive_summary
| Campo | Tipo | Descrição |
|---|---|---|
| reasons | array<string> | Lista de motivos/justificativas que sustentam a avaliação. |
| executive_summary.headline | string | Título do resumo executivo. |
| executive_summary.summary | string | Resumo executivo da análise, pronto para exibição em dashboards. |
6 Erros
| Status | Quando ocorre |
|---|---|
| 400 | Payload inválido — ex.: CPF sem 11 dígitos. |
| 401 | Token ausente, inválido ou expirado. |
| 403 | Produto não habilitado para essa API key. |
| 413 | Corpo da requisição maior que 64KB. |
| 429 | Limite de requisições ou quota de demo excedidos. |
| 502 | Serviço de collections indisponível temporariamente. |
{
"detail": "invalid or expired demo key"
}
7 Rate limit & quotas
POST /v1/analyze— 30 requisições/minuto por IP.POST /v1/demo-keys— 5 requisições/minuto por IP.- Chaves de demonstração têm quota própria (consulte
/v1/demo-keys); ao esgotar, a API retorna429.
8 Exemplos de código
cURL
TOKEN=$(curl -s -X POST https://collections.autentify.com.br/v1/auth/token \
-H "X-Api-Key: ak_live_xxx" | jq -r .access_token)
curl -X POST https://collections.autentify.com.br/v1/analyze \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"payload": {"email": "cliente@empresa.com", "cpf": "12345678901"}}'
Python
import httpx
API_KEY = "ak_live_xxx"
BASE_URL = "https://collections.autentify.com.br"
with httpx.Client(timeout=30) as client:
token_resp = client.post(f"{BASE_URL}/v1/auth/token", headers={"X-Api-Key": API_KEY})
access_token = token_resp.json()["access_token"]
analyze_resp = client.post(
f"{BASE_URL}/v1/analyze",
headers={"Authorization": f"Bearer {access_token}"},
json={"payload": {"email": "cliente@empresa.com", "cpf": "12345678901"}},
)
data = analyze_resp.json()
print(data["recovery_index"]["score"], data["collection_strategy"]["suggested_approach"])
Node.js
const BASE_URL = "https://collections.autentify.com.br";
const API_KEY = "ak_live_xxx";
const tokenRes = await fetch(`${BASE_URL}/v1/auth/token`, {
method: "POST",
headers: { "X-Api-Key": API_KEY },
});
const { access_token } = await tokenRes.json();
const analyzeRes = await fetch(`${BASE_URL}/v1/analyze`, {
method: "POST",
headers: {
Authorization: `Bearer ${access_token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ payload: { email: "cliente@empresa.com", cpf: "12345678901" } }),
});
const data = await analyzeRes.json();
console.log(data.recovery_index.score, data.collection_strategy.suggested_approach);