De zero ao primeiro 200 OK em 60 segundos.

Seu primeiro request

Mande country e value para /v1/validate/tax-ids dentro de um array items. Receba um array results com um objeto por item: source, normalized, formatted, country, type e valid. Quando valid for false, leia a resposta — é sempre acionável.

$ curl -X POST https://api.normadata.io/v1/validate/tax-ids \
    -H "X-API-Key: nd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5" \
    -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" }
      ]
    }'

{
  "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"
    }
  ]
}

const res = await fetch("https://api.normadata.io/v1/validate/tax-ids", {
  method: "POST",
  headers: {
    "X-API-Key":    process.env.ND_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { id: "a", value: "20-12345678-6", country: "AR", type: "cuit" },
      { id: "b", value: "123.456.789-09", country: "BR" },
    ],
  }),
});

const { results } = await res.json();
// Same endpoint for 1 or N items — one result per item, by id.
for (const r of results) console.log(r.id, r.valid, r.normalized);

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/validate/tax-ids",
    headers={
        "X-API-Key":    os.environ["ND_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "items": [
            {"id": "a", "value": "20-12345678-6", "country": "AR", "type": "cuit"},
            {"id": "b", "value": "123.456.789-09", "country": "BR"},
        ],
    },
)
# Same endpoint for 1 or N items — one result per item, by id.
for r in res.json()["results"]:
    print(r["id"], r["valid"], r.get("normalized"))

Qualquer cliente HTTP serve

A gente ainda não shippa SDKs. A API é REST + JSON estrito, então cURL, fetch, requests ou net/http funcionam out of the box. Os exemplos abaixo cobrem os casos mais comuns.

API keys

Mande o header X-API-Key em cada request. As keys começam com nd_ seguido de 30 chars base62 (33 chars no total). Nunca exponha sua key em código do cliente — use só a partir de um servidor, função ou infra de confiança.

X-API-Key: nd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5

nd_   prefix          (3 chars)
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   base62 random  (30 chars)
──────────────────────────────
nd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5  (33 chars total)

Anatomia do payload

Cada endpoint de Validate aceita um shape plano. Campos extras são ignorados. Algo inválido vira 422 com os campos que falharam listados.

{
  "items": [                       // 1..1000 items (500 for /records)
    {
      "id":      "a",              // your correlation id, returned verbatim
      "value":   "20-12345678-6",  // raw input
      "country": "AR",             // ISO 3166-1 alpha-2 (required)
      "type":    "cuit"            // optional — deduced within the country
    }
  ]
}

Códigos possíveis

HTTP padrão mais códigos de warning do produto dentro da resposta. valid: false não é um erro HTTP — devolvemos 200 com valid: false e uma razão legível.

Toda resposta inclui um header X-Request-Id, também devolvido nos bodies de erro. Quando reportar um problema em hello@normadata.io, inclua-o — isso permite que a gente rastreie a request exata nos nossos logs.

Por key durante o acesso antecipado

Os rate limits são configurados por API key durante o acesso antecipado. Os números concretos vão na conta quando você for onboardado. A resposta inclui os headers padrão X-RateLimit-* pro seu cliente fazer back-off limpo.

X-RateLimit-Limit:      60000
X-RateLimit-Remaining:  55872
X-RateLimit-Reset:      2026-07-01T00:00:00Z
Retry-After:            1