autentify
Referência da API · v1

Documentação Collections API

Envie e-mail + CPF e receba um Recovery Index (0–1000), a elegibilidade de contato, propensão de pagamento e uma estratégia de cobrança recomendada — pronta para priorizar sua régua.

POST /v1/auth/token POST /v1/collections/analyze

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).

request.sh
curl -X POST https://collections.autentify.com.br/v1/auth/token \
  -H "X-Api-Key: ak_live_xxx"

Resposta:

response.json
{
  "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

endpoint
POST /v1/analyze
Authorization: Bearer <access_token>
Content-Type: application/json
payload.json
{
  "payload": {
    "email": "cliente@empresa.com",
    "cpf": "12345678901"
  }
}

Notas de contrato

  • request_id é opcional; se ausente, a API gera automaticamente.
  • schema_version é opcional (default v1).
  • channel é opcional para chamadas externas e assume api.
  • cpf aceita com ou sem máscara; é normalizado para 11 dígitos.

4 Resposta completa

Exemplo real de retorno do endpoint /v1/analyze:

response.json
{
  "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

CampoTipoDescrição
request_idstringIdentificador único da requisição.

recovery_assessment & recovery_index

CampoTipoDescrição
recovery_assessment.classificationstringClassificação: LOW_RECOVERY_PRIORITY, MEDIUM_RECOVERY_PRIORITY, HIGH_RECOVERY_PRIORITY.
recovery_assessment.scoreintegerScore de recuperação, de 0 a 1000.
recovery_assessment.recommended_actionstringAção recomendada: LOW_PRIORITY_QUEUE, PRIORITIZE_COLLECTION, IMMEDIATE_CONTACT.
recovery_index.namestringNome do índice ("Autentify Recovery Index").
recovery_index.scoreintegerMesmo score de recovery_assessment.score.
recovery_index.classstringMesma classificação de recovery_assessment.classification.
recovery_index.labelstringRótulo amigável em PT-BR para exibição.

contact_eligibility

CampoTipoDescrição
statusstringELIGIBLE ou NOT_ELIGIBLE — se o devedor pode ser acionado.
restrictionsarrayLista de restrições aplicáveis (vazia quando não há).

recommended_contacts

CampoTipoDescrição
primary_channelstringCanal recomendado: EMAIL, PHONE, WHATSAPP.
phones[]arrayTelefones qualificados, ordenados por rank (vazio quando nenhum é encontrado).
phones[].rankintegerPosição de prioridade do telefone (1 = melhor).
phones[].numberstringNúmero de telefone (mascarado em modo demo).
phones[].contact_potentialstringPotencial de contato: LOW, MEDIUM, HIGH.
phones[].whatsapp_availablebooleanSe o número está disponível no WhatsApp.
phones[].best_contact_windowstringJanela de horário recomendada para contato (ex.: "18:00-21:00").
email.addressstringE-mail (mascarado em modo demo).
email.cpf_linkstringTipo de vínculo com CPF: CONFIRMED, WEAK, NONE.
email.link_strengthstringForça do vínculo: LOW, MEDIUM, HIGH, VERY_HIGH.
email.deliverability_statusstringStatus de entregabilidade: VALID, RISKY, INVALID.
email.channel_qualitystringQualidade do canal: LOW, MEDIUM, HIGH.
recommended_contactobject | nullContato preferencial; null quando não há canal claramente superior.
recommended_contact.valuestringValor do contato recomendado (telefone ou e-mail).
recommended_contact.best_contact_windowstringJanela de horário recomendada.

payment_propensity

CampoTipoDescrição
classificationstringPropensão de pagamento: LOW, MODERATE, HIGH, VERY_HIGH.
scoreintegerScore de propensão, de 0 a 1000.

collection_profile

CampoTipoDescrição
digital_affinity.levelstringAfinidade digital: UNKNOWN, LOW, MODERATE, HIGH.
digital_affinity.labelstringRótulo em PT-BR para exibição.
negotiation_capacity.levelstringCapacidade de negociação: UNKNOWN, LOW, MODERATE, HIGH.
negotiation_capacity.labelstringRótulo em PT-BR para exibição.
collection_insightstringTexto explicativo sobre a afinidade digital.
negotiation_insightstringTexto explicativo sobre a capacidade de negociação.

recovery_cluster & collection_strategy

CampoTipoDescrição
recovery_cluster.codestringCluster: LOW_RECOVERY_POTENTIAL, MEDIUM_RECOVERY_POTENTIAL, HIGH_RECOVERY_POTENTIAL.
recovery_cluster.labelstringRótulo amigável do cluster.
recovery_cluster.descriptionstringDescrição operacional do cluster.
collection_strategy.suggested_approachstringAbordagem sugerida: REVIEW_BEFORE_CONTACT, WHATSAPP_THEN_PHONE, DIRECT_CONTACT.
collection_strategy.recommended_prioritystringFila recomendada: LOW_PRIORITY_QUEUE, HIGH_PRIORITY_QUEUE.
collection_strategy.action_recommendationstringPróxima ação recomendada em texto.

reasons & executive_summary

CampoTipoDescrição
reasonsarray<string>Lista de motivos/justificativas que sustentam a avaliação.
executive_summary.headlinestringTítulo do resumo executivo.
executive_summary.summarystringResumo executivo da análise, pronto para exibição em dashboards.

6 Erros

StatusQuando ocorre
400Payload inválido — ex.: CPF sem 11 dígitos.
401Token ausente, inválido ou expirado.
403Produto não habilitado para essa API key.
413Corpo da requisição maior que 64KB.
429Limite de requisições ou quota de demo excedidos.
502Serviço de collections indisponível temporariamente.
error-response.json
{
  "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 retorna 429.

8 Exemplos de código

cURL

example.sh
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

example.py
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

example.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);