DOCS · EXEMPLOS

Exemplos de código em 4 linguagens

cURL, TypeScript, Python e Go pros 5 endpoints. Sem SDK fictício — apenas stdlib + fetch / requests / net/http. Copia, cola, troca a API key e roda.

Como autenticar Pedir uma API key

ÍNDICE

Endpoints e linguagens

5 endpoints × 4 linguagens = 20 snippets. Clica em qualquer célula pra pular direto pro code block correspondente.

Endpoint	cURL	TypeScript	Python	Go
/v1/validate/tax-ids	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/validate/accounts	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/validate/emails	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/validate/phones	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/validate/records	cURL ↓	TS ↓	Py ↓	Go ↓

POST /v1/validate/tax-ids

Tax IDs — validação de tax IDs em lote

Referência completa →

cURL

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

TypeScript

const res = await fetch("https://api.normadata.io/v1/validate/tax-ids", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_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();
for (const r of results) console.log(r.id, r.valid, r.normalized);

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/validate/tax-ids",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_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"},
        ],
    },
    timeout=10,
)
for r in res.json()["results"]:
    print(r["id"], r["valid"], r.get("normalized"))

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type TaxIDItem struct {
	ID      string `json:"id"`
	Value   string `json:"value"`
	Country string `json:"country"`
	Type    string `json:"type,omitempty"`
}

type TaxIDResult struct {
	ID         string `json:"id"`
	Valid      bool   `json:"valid"`
	Normalized string `json:"normalized"`
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"items": []TaxIDItem{
			{ID: "a", Value: "20-12345678-6", Country: "AR", Type: "cuit"},
			{ID: "b", Value: "123.456.789-09", Country: "BR"},
		},
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/validate/tax-ids", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	var out struct {
		Results []TaxIDResult `json:"results"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ID, r.Valid, r.Normalized)
	}
}

POST /v1/validate/accounts

Contas — validação bancária em lote

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/validate/accounts \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"id":"1","value":"0170010600000123456780","country":"AR","type":"cbu"},
    {"id":"2","value":"DE89370400440532013000","country":"DE","type":"iban"}
  ]}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/validate/accounts", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { id: "1", value: "0170010600000123456780", country: "AR", type: "cbu" },
      { id: "2", value: "DE89370400440532013000", country: "DE", type: "iban" },
    ],
  }),
});

const { results } = await res.json();
for (const r of results) console.log(r.id, r.checksum_valid, r.bank_name);

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/validate/accounts",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "items": [
            {"id": "1", "value": "0170010600000123456780", "country": "AR", "type": "cbu"},
            {"id": "2", "value": "DE89370400440532013000", "country": "DE", "type": "iban"},
        ],
    },
    timeout=10,
)
for r in res.json()["results"]:
    print(r["id"], r["checksum_valid"], r.get("bank_name"))

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type AccountItem struct {
	ID      string `json:"id"`
	Value   string `json:"value"`
	Country string `json:"country"`
	Type    string `json:"type,omitempty"`
}

type AccountResult struct {
	ID            string `json:"id"`
	Valid         bool   `json:"valid"`
	ChecksumValid bool   `json:"checksum_valid"`
	BankName      string `json:"bank_name"`
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"items": []AccountItem{
			{ID: "1", Value: "0170010600000123456780", Country: "AR", Type: "cbu"},
			{ID: "2", Value: "DE89370400440532013000", Country: "DE", Type: "iban"},
		},
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/validate/accounts", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	var out struct {
		Results []AccountResult `json:"results"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ID, r.ChecksumValid, r.BankName)
	}
}

POST /v1/validate/emails

E-mails — sintaxe e typos em lote

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/validate/emails \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"id":"1","value":"  ROGER@Normadata.IO "},
    {"id":"2","value":"juan@gmial.com"}
  ]}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/validate/emails", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { id: "1", value: "  ROGER@Normadata.IO " },
      { id: "2", value: "juan@gmial.com" },
    ],
  }),
});

const { results } = await res.json();
for (const r of results) console.log(r.id, r.valid, r.normalized ?? r.error);

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/validate/emails",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "items": [
            {"id": "1", "value": "  ROGER@Normadata.IO "},
            {"id": "2", "value": "juan@gmial.com"},
        ],
    },
    timeout=10,
)
for r in res.json()["results"]:
    print(r["id"], r["valid"], r.get("normalized") or r.get("error"))

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type EmailItem struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

type EmailResult struct {
	ID         string `json:"id"`
	Valid      bool   `json:"valid"`
	Normalized string `json:"normalized"`
	Error      string `json:"error"`
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"items": []EmailItem{
			{ID: "1", Value: "  ROGER@Normadata.IO "},
			{ID: "2", Value: "juan@gmial.com"},
		},
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/validate/emails", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	var out struct {
		Results []EmailResult `json:"results"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ID, r.Valid, r.Normalized)
	}
}

POST /v1/validate/phones

Telefones — E.164 e tipo de linha em lote

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/validate/phones \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"id":"1","value":"+54 (11) 4555-2233","country":"AR"},
    {"id":"2","value":"11987654321","country":"BR"}
  ]}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/validate/phones", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { id: "1", value: "+54 (11) 4555-2233", country: "AR" },
      { id: "2", value: "11987654321", country: "BR" },
    ],
  }),
});

const { results } = await res.json();
for (const r of results) console.log(r.id, r.normalized, r.type);

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/validate/phones",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "items": [
            {"id": "1", "value": "+54 (11) 4555-2233", "country": "AR"},
            {"id": "2", "value": "11987654321", "country": "BR"},
        ],
    },
    timeout=10,
)
for r in res.json()["results"]:
    print(r["id"], r.get("normalized"), r.get("type"))

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type PhoneItem struct {
	ID      string `json:"id"`
	Value   string `json:"value"`
	Country string `json:"country"`
}

type PhoneResult struct {
	ID         string `json:"id"`
	Valid      bool   `json:"valid"`
	Normalized string `json:"normalized"`
	Type       string `json:"type"`
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"items": []PhoneItem{
			{ID: "1", Value: "+54 (11) 4555-2233", Country: "AR"},
			{ID: "2", Value: "11987654321", Country: "BR"},
		},
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/validate/phones", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	var out struct {
		Results []PhoneResult `json:"results"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ID, r.Normalized, r.Type)
	}
}

POST /v1/validate/records

Records — consistência e readiness

Referência completa →

cURL

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

TypeScript

const res = await fetch("https://api.normadata.io/v1/validate/records", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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",
      },
    ],
  }),
});

const { results } = await res.json();
for (const r of results) console.log(r.reference_id, r.readiness.payment.status);

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/validate/records",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "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",
            }
        ],
    },
    timeout=10,
)
for r in res.json()["results"]:
    print(r["reference_id"], r["readiness"]["payment"]["status"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type RecordItem struct {
	ReferenceID string `json:"reference_id"`
	Country     string `json:"country"`
	TaxID       string `json:"tax_id,omitempty"`
	Account     string `json:"account,omitempty"`
	AccountType string `json:"account_type,omitempty"`
	Name        string `json:"name,omitempty"`
	Email       string `json:"email,omitempty"`
}

type ReadinessFlag struct {
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
}

type RecordResult struct {
	ReferenceID string `json:"reference_id"`
	Readiness   struct {
		Payment ReadinessFlag `json:"payment"`
		Billing ReadinessFlag `json:"billing"`
	} `json:"readiness"`
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"items": []RecordItem{{
			ReferenceID: "prov-001",
			Country:     "AR",
			TaxID:       "20-12345678-6",
			Account:     "0170010600000123456780",
			AccountType: "cbu",
			Name:        "Juan Pérez",
			Email:       "juan@empresa.com",
		}},
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/validate/records", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	var out struct {
		Results []RecordResult `json:"results"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ReferenceID, r.Readiness.Payment.Status)
	}
}

REFERÊNCIAS

Documentação detalhada por endpoint

Cada endpoint tem uma página dedicada com o schema completo do request, todos os campos de resposta, os erros comuns e notas de implementação.

/v1/validate/tax-ids — Tax IDs — validação de tax IDs em lote
/v1/validate/accounts — Contas — validação bancária em lote
/v1/validate/emails — E-mails — sintaxe e typos em lote
/v1/validate/phones — Telefones — E.164 e tipo de linha em lote
/v1/validate/records — Records — consistência e readiness