01 · VALIDADORES

Validadores core para dados operacionais LATAM

Cada validador faz uma coisa. Escolha um endpoint pontual ou use a Records API para validar a entidade completa.

Comparativo dos endpoints core

ValidadorEndpointO que validaQuando usar
Tax IDsPOST /v1/validate/tax-idsDNI, CUIT, CUIL, CPF, CNPJ, RFC, CURP, RUT, NIT, RUC, Cédula e maisQuando você valida documentos fiscais em lote, sabendo o país
ContasPOST /v1/validate/accountsCBU, CVU, CLABE, CCI, IBAN — checksum + nome do bancoAntes de um payout ou transferência, em lote
EmailsPOST /v1/validate/emailsSintaxe RFC + normalização + detecção de typos de domínioQuando você valida e-mails em lote antes de guardá-los
TelefonesPOST /v1/validate/phonesNormalização para E.164 + tipo de linha (móvel/fixo)Quando você valida telefones em lote, sabendo o país
RecordsPOST /v1/validate/recordsEntidade completa: documento + conta + nome + e-mail + telefone + endereço, com consistência e readinessQuando você valida registros completos (fornecedores, clientes) antes de operar
PessoasPOST /v1/validate/recordsNomes com sobrenome paterno e materno, gênero, nacionalidadeQuando um record inclui o nome de uma pessoa
EndereçosPOST /v1/validate/recordsEndereços LATAM com parsing de componentes e estado ISO 3166-2Quando um record inclui um endereço em texto livre
DomíniosPOST /v1/validate/emailsSintaxe do domínio + detecção de typos contra provedores comunsQuando você valida a parte de domínio de um email antes de salvar

Detalhe por validador

Tax IDs

POST /v1/validate/tax-ids

O QUE FAZ

Implementa o checksum certo por país: Mod-11 com pesos custom (CUIT), duas rodadas de Mod-11 (CPF, CNPJ), homoclave do SAT (RFC), Mod-11 com K verificador (RUT-CL). Cobre identificações pessoais (DNI, CURP, Cédula) e fiscais. Você manda um lote de até 1.000 itens e recebe um resultado por item.

O QUE NÃO FAZ

Não consulta AFIP, Receita Federal nem SAT. Um resultado válido significa que o formato e o dígito verificador estão corretos — não que o contribuinte esteja ativo ou registrado.

Contas

POST /v1/validate/accounts

O QUE FAZ

Valida formatos bancários: CBU (Mod-10 por bloco), CVU (mesmo checksum, prefixo diferente), CLABE (dígito ponderado do Banxico), CCI (Peru), IBAN (Mod-97-10). Resolve bank_code → bank_name a partir de registros oficiais. Até 1.000 contas por request.

O QUE NÃO FAZ

Não verifica se a conta está aberta nem quem é o titular. Não executa uma transferência de teste — só valida que o número está bem formado e pertence a um banco real.

Emails

POST /v1/validate/emails

O QUE FAZ

Valida sintaxe de e-mail segundo o RFC, normaliza (lowercase, trim) e detecta typos de domínio contra provedores comuns (gmial → gmail). Você manda um lote de até 1.000 e-mails e recebe validade e forma normalizada por item.

O QUE NÃO FAZ

Não verifica se a inbox existe nem faz lookup SMTP. Valida que o e-mail está bem armado, não que recebe correio.

Telefones

POST /v1/validate/phones

O QUE FAZ

Faz parse de telefones em qualquer formato e devolve E.164, validade e tipo de linha (mobile, landline, mobile_or_landline, other). O país é a região de parsing. Até 1.000 telefones por request.

O QUE NÃO FAZ

Não liga para a operadora nem envia SMS de teste. Valida que o número está bem formado para o país, não que está ativo.

Records

POST /v1/validate/records

O QUE FAZ

Valida uma entidade completa em uma request: cada campo presente é validado com seu normalizador, checa consistência entre campos (país↔documento, país↔conta) e calcula readiness por processo: payment (pronto para pagar) e billing (pronto para faturar). Até 500 records por request.

O QUE NÃO FAZ

Não é KYC nem verificação de identidade. Não consulta registros governamentais. Confirma que o registro está bem armado e é internamente consistente, não que a entidade existe.

Pessoas

POST /v1/validate/records

O QUE FAZ

Faz o split de nomes hispânicos e brasileiros em first / paterno / materno. Corrige maiúsculas e acentos quando é determinístico. Resolve gentílicos e nacionalidades contra uma tabela LATAM. Viaja como campo name dentro de /v1/validate/records.

O QUE NÃO FAZ

Não verifica se a pessoa existe no RENIEC, AFIP ou Receita. Não faz verificação de identidade — isso é KYC, uma camada diferente que roda depois da validação de formato.

Endereços

POST /v1/validate/records

O QUE FAZ

Extrai componentes (rua, número, andar, apto, localidade, estado, país) de um string. Normaliza o estado para ISO 3166-2. Mapeia variantes ("Bs As", "BUENOS AIRES") para o nome canônico. Viaja como campo address dentro de /v1/validate/records.

O QUE NÃO FAZ

Não geocodifica — não devolve lat/lng nem chama o Google Maps. Não verifica que o endereço existe fisicamente. O parsing é sintático, não semântico.

Domínios

POST /v1/validate/emails

O QUE FAZ

A validação de domínio vive dentro de /v1/validate/emails: checa que a parte depois do @ tenha sintaxe válida e detecta typos contra provedores comuns (gmial.com → gmail.com). Não é um endpoint à parte — é parte do check de email.

O QUE NÃO FAZ

Não resolve registros DNS nem MX, nem verifica que o domínio recebe email. Valida que o domínio esteja bem escrito, não que exista ou esteja ativo.

Como escolher o validador correto?

Cinco perguntas para rotear seu caso ao endpoint certo sem testar todos.

  • Precisa validar um documento fiscal?Use Tax IDs com country e value por item. Mesmo endpoint para 1 ou N — até 1.000 por request.
  • Vai mandar dinheiro pra essa conta?Valide com Contas antes da tentativa de pagamento. Pega erros de digitação em CBU, CVU, CLABE, CCI ou IBAN antes da transferência voltar.
  • Está guardando e-mails ou telefones?Use Emails ou Telefones em lote. Normaliza, detecta typos de domínio e devolve E.164 com tipo de linha.
  • Precisa de um veredito de entidade completa?Use Records. Valida cada campo, checa consistência entre os dados e resume readiness para payment e billing.
  • O input é um endereço ou um nome livre?Mande o campo name ou address dentro de um record. Faz o split de sobrenomes LATAM e normaliza o estado para ISO 3166-2, sem geocodificação.

Perguntas frequentes

Preciso de uma API key por endpoint?

Não. Uma única key (header X-API-Key) habilita os cinco endpoints da API. Os rate limits se aplicam ao total de requests, não por endpoint.

Existe um endpoint batch?

Sim. Todos os endpoints aceitam um array items e devolvem um array results — o mesmo endpoint valida 1 ou N. O limite é 1.000 itens por request (500 em /records).

Como correlaciono cada resultado com o meu input?

Você fornece um id por item (ou reference_id em /records) e ele volta verbatim em cada result. A ordem do array também é preservada.

Peça acesso antecipado

Grátis durante o beta. Respondemos por email em 24 horas ou antes.