documentação

Referência da API

planejada A API pública ainda não está no ar — esta página documenta o contrato que o motor de validação já usa internamente no site, para quem quiser se preparar para a integração.

Autenticação

Token de API no cabeçalho Authorization. Um token por conta, com escopo de leitura e uso de créditos.

header
Authorization: Bearer SEU_TOKEN

Contrato de resposta

Toda validação — e-mail, telefone, CPF ou CNPJ — devolve o mesmo formato.

{
  "campo": "email | telefone | cpf | cnpj",
  "original": "string | null",
  "sugerido": "string | null",
  "status": "valido | corrigido | arriscado | invalido | desconhecido | vazio",
  "motivos": ["string", "..."],
  "detalhes": { }
}

sugerido é a correção — nunca sobrescreve original. Quando status é invalido ou vazio, sugerido vem null.

POST/v1/validar/email

Sintaxe, typo de domínio, descartáveis, MX e e-mail de função.

request
{ "valor": "[email protected]" }
response
{
  "campo": "email",
  "original": "[email protected]",
  "sugerido": "[email protected]",
  "status": "corrigido",
  "motivos": ["typo_dominio"],
  "detalhes": {}
}
POST/v1/validar/telefone

DDD, nono dígito, formato fixo/móvel, DDI estrangeiro, números suspeitos. Saída em E.164.

request
{ "valor": "14 67778888" }
response
{
  "campo": "telefone",
  "original": "14 67778888",
  "sugerido": "+5514967778888",
  "status": "corrigido",
  "motivos": ["nono_digito_adicionado"],
  "detalhes": { "tipo": "movel", "ddd": "14", "formatado": "(14) 96777-8888" }
}
POST/v1/validar/cpf

Zeros à esquerda, tamanho, dígitos repetidos e dígito verificador (módulo 11).

request
{ "valor": "12345678909" }
response
{
  "campo": "cpf",
  "original": "12345678909",
  "sugerido": null,
  "status": "invalido",
  "motivos": ["dv_invalido"],
  "detalhes": {}
}
POST/v1/validar/cnpj

Aceita formato numérico (legado) e alfanumérico (Receita Federal, a partir de 07/2026).

request
{ "valor": "12.ABC.345/01DE-35" }
response
{
  "campo": "cnpj",
  "original": "12.ABC.345/01DE-35",
  "sugerido": "12ABC34501DE35",
  "status": "valido",
  "motivos": [],
  "detalhes": { "formatado": "12.ABC.345/01DE-35", "alfanumerico": true }
}

Erros

Entrada inválida nunca derruba a chamada — ela vira status: "invalido" ou "desconhecido" na resposta. Códigos HTTP de erro (401, 429) ficam só para autenticação e limite de uso.