Referência da API Validate
O módulo Validate valida tax IDs, documentos de identidade e identificadores financeiros na América do Sul mais padrões globais com um único endpoint.
O módulo Validate valida tax IDs, documentos de identidade e identificadores financeiros na América do Sul mais padrões globais com um único endpoint.
URL base para todas as requisições:
Todas as requisições exigem uma chave de API no header X-API-Key. Consulte a referência principal da API para detalhes de autenticação.
Autenticação
Cada requisição deve incluir sua chave de API no header X-API-Key. As chaves seguem o formato nd_ seguido de 30 caracteres (33 chars no total).
HeaderX-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4
As chaves são provisionadas manualmente durante o acesso antecipado. Entre na lista para solicitar acesso.
Validação de identificadores
Os endpoints core para validar e normalizar identificadores em vários domínios. Todos retornam um booleano valid mais a forma normalizada.
Todos os endpoints são batch: você envia um array items e recebe um results por item, correlacionado pelo id que você fornece. O mesmo endpoint serve para 1 ou N (até 1.000 itens; 500 em /records).
POST /v1/validate/tax-ids — Tax IDs
Valida e normaliza tax IDs (CUIT, CPF, RFC, RUT, NIT, RUC e mais). Devolve type (pessoa ou empresa) quando o ID o codifica. Até 1.000 por request.
cURLcurl -X POST https://api.normadata.io/v1/validate/tax-ids \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "id": "a", "value": "20-12345678-6", "country": "AR", "type": "cuit" },
{ "id": "b", "value": "123.456.789-09", "country": "BR" }
]
}'Exemplo de resposta 200
JSON{
"results": [
{
"id": "a",
"country": "AR",
"type": "cuit",
"valid": true,
"normalized": "20123456786",
"formatted": "20-12345678-6"
},
{
"id": "b",
"country": "BR",
"type": "cpf",
"valid": true,
"normalized": "12345678909",
"formatted": "123.456.789-09"
}
]
}POST /v1/validate/accounts — Contas (CBU, CVU, CLABE, CCI, IBAN)
Valida contas bancárias: CBU/CVU (Mod-10), CLABE (Banxico), CCI (Peru), IBAN (Mod-97). Devolve checksum_valid e bank_name quando resolve. Até 1.000 por request.
cURLcurl -X POST https://api.normadata.io/v1/validate/accounts \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "id": "1", "value": "0170010600000123456780", "country": "AR", "type": "cbu" },
{ "id": "2", "value": "DE89370400440532013000", "country": "DE", "type": "iban" }
]
}'Exemplo de resposta 200
JSON{
"results": [
{
"id": "1",
"country": "AR",
"type": "cbu",
"valid": true,
"checksum_valid": true,
"bank_name": "Galicia"
},
{
"id": "2",
"country": "DE",
"type": "iban",
"valid": true,
"checksum_valid": true
}
]
}POST /v1/validate/emails — Emails
Valida sintaxe RFC, normaliza (lowercase, trim) e detecta typos de domínio. Cada item do lote devolve valid e normalized. Até 1.000 e-mails por request.
cURLcurl -X POST https://api.normadata.io/v1/validate/emails \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "id": "1", "value": " ROGER@Normadata.IO " },
{ "id": "2", "value": "juan@gmial.com" }
]
}'Exemplo de resposta 200
JSON{
"results": [
{
"id": "1",
"value": " ROGER@Normadata.IO ",
"valid": true,
"normalized": "roger@normadata.io"
},
{
"id": "2",
"value": "juan@gmial.com",
"valid": false,
"error": "typo in domain: did you mean gmail.com?"
}
]
}POST /v1/validate/phones — Telefones
Normaliza telefones para E.164 e devolve o tipo de linha (mobile, landline, mobile_or_landline, other). O país é a região de parsing. Até 1.000 por request.
cURLcurl -X POST https://api.normadata.io/v1/validate/phones \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "id": "1", "value": "+54 (11) 4555-2233", "country": "AR" },
{ "id": "2", "value": "11987654321", "country": "BR" }
]
}'Exemplo de resposta 200
JSON{
"results": [
{
"id": "1",
"valid": true,
"normalized": "+541145552233",
"type": "landline"
},
{
"id": "2",
"valid": true,
"normalized": "+5511987654321",
"type": "mobile"
}
]
}POST /v1/validate/records — Records
Valida uma entidade completa (tax_id, account, email, phone, name, address), checa consistência entre campos e resume readiness (payment, billing). Até 500 records por request.
cURLcurl -X POST https://api.normadata.io/v1/validate/records \
-H "X-API-Key: nd_a8f3b2c1d4e5f6g7h8i9j0k1l2m3n4" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"reference_id": "prov-001",
"country": "AR",
"tax_id": "20-12345678-6",
"account": "0170010600000123456780",
"account_type": "cbu",
"name": "Juan Pérez",
"email": "juan@empresa.com"
}
]
}'Exemplo de resposta 200
JSON{
"results": [
{
"reference_id": "prov-001",
"country": "AR",
"fields": {
"tax_id": {
"valid": true,
"normalized": "20123456786"
},
"account": {
"valid": true,
"checksum_valid": true,
"bank_name": "Galicia",
"country": "AR"
},
"name": {
"full": "Juan Pérez",
"first": "Juan",
"paternal": "Pérez"
},
"email": {
"valid": true,
"normalized": "juan@empresa.com"
}
},
"consistency": [
{
"check": "country_matches_tax_id",
"ok": true
},
{
"check": "country_matches_account",
"ok": true
}
],
"readiness": {
"payment": {
"status": "ready"
},
"billing": {
"status": "ready"
}
}
}
]
}Códigos de erro
Todos os endpoints Validate compartilham o mesmo schema de erro. HTTP 200 só é retornado em normalização bem-sucedida.
| Código | Status | Descrição |
|---|---|---|
| empty_batch | 400 | O array items chegou vazio. Envie ao menos um item por request. |
| batch_too_large | 400 | O lote excede o máximo permitido (1.000 itens; 500 em /records). Pagine em lotes menores. |
| invalid_api_key | 401 | Chave de API ausente, inválida ou revogada |
| quota_exceeded | 429 | A cota da conta se esgotou. A contagem é por item ou registro processado. |
Limites de taxa
Durante o acesso antecipado, o uso é monitorado por conta. Não há números de limite de taxa públicos ainda.