DOCS · EXEMPLOS

Exemplos de código em 4 linguagens

cURL, TypeScript, Python e Go pros 6 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

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

Endpoint	cURL	TypeScript	Python	Go
/v1/verify	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/verify/person	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/verify/tax-id	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/verify/contact	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/verify/bank	cURL ↓	TS ↓	Py ↓	Go ↓
/v1/verify/address	cURL ↓	TS ↓	Py ↓	Go ↓

POST /v1/verify

Smart Parse — detecção universal de tipo

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/verify \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"20-12345678-3","country_hint":"AR"}'

TypeScript

type SmartParseResponse = {
  contains_pii: boolean;
  processed_at: string;
  source: string;
  detected_type: string;
  confidence: number;
  result: { valid: boolean; normalized: string };
};

const res = await fetch("https://api.normadata.io/v1/verify", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "20-12345678-3",
    country_hint: "AR",
  }),
});

const data = (await res.json()) as SmartParseResponse;
console.log(data.detected_type, data.result.normalized);

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/verify",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "input": "20-12345678-3",
        "country_hint": "AR",
    },
    timeout=10,
)
res.raise_for_status()
data = res.json()
print(data["detected_type"], data["result"]["normalized"])

package main

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

type SmartParseResult struct {
	Valid      bool   `json:"valid"`
	Normalized string `json:"normalized"`
}

type SmartParseResponse struct {
	DetectedType string           `json:"detected_type"`
	Confidence   float64          `json:"confidence"`
	Result       SmartParseResult `json:"result"`
}

func main() {
	body, _ := json.Marshal(map[string]string{
		"input":        "20-12345678-3",
		"country_hint": "AR",
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/verify", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out SmartParseResponse
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.DetectedType, out.Result.Normalized)
}

POST /v1/verify/person

Person — normalização de pessoas

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/verify/person \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "X-Country-Hint: VE" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"juan carlos PEREZ lopez","birth_date":"15/03/1990","gender":"masculino"}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/verify/person", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "X-Country-Hint": "VE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    full_name: "juan carlos PEREZ lopez",
    birth_date: "15/03/1990",
    gender: "masculino",
  }),
});

const data = await res.json();
console.log(data.name.full);  // "Juan Carlos Pérez López"

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/verify/person",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "X-Country-Hint": "VE",
        "Content-Type": "application/json",
    },
    json={
        "full_name": "juan carlos PEREZ lopez",
        "birth_date": "15/03/1990",
        "gender": "masculino",
    },
    timeout=10,
)
data = res.json()
print(data["name"]["full"])

package main

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

type PersonName struct {
	Full     string `json:"full"`
	First    string `json:"first"`
	Paternal string `json:"paternal"`
	Maternal string `json:"maternal"`
}

type PersonResponse struct {
	Name PersonName `json:"name"`
}

func main() {
	body, _ := json.Marshal(map[string]string{
		"full_name":  "juan carlos PEREZ lopez",
		"birth_date": "15/03/1990",
		"gender":     "masculino",
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/verify/person", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("X-Country-Hint", "VE")
	req.Header.Set("Content-Type", "application/json")

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

	var out PersonResponse
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.Name.Full)
}

POST /v1/verify/tax-id

Tax ID — validação de tax IDs

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/verify/tax-id \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"20-12345678-3","country":"AR","type":"cuit"}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/verify/tax-id", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    value: "20-12345678-3",
    country: "AR",
    type: "cuit",
  }),
});

const data = await res.json();
if (!data.value?.valid) throw new Error("invalid cuit");
console.log(data.value.normalized);  // "20123456783"

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/verify/tax-id",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "value": "20-12345678-3",
        "country": "AR",
        "type": "cuit",
    },
    timeout=10,
)
data = res.json()
assert data["value"]["valid"], "invalid cuit"
print(data["value"]["normalized"])

package main

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

type TaxIdValue struct {
	Source     string `json:"source"`
	Normalized string `json:"normalized"`
	Country    string `json:"country"`
	Type       string `json:"type"`
	Valid      bool   `json:"valid"`
}

type TaxIdResponse struct {
	Value TaxIdValue `json:"value"`
}

func main() {
	body, _ := json.Marshal(map[string]string{
		"value":   "20-12345678-3",
		"country": "AR",
		"type":    "cuit",
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/verify/tax-id", 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 TaxIdResponse
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.Value.Valid, out.Value.Normalized)
}

POST /v1/verify/contact

Contact — normalização de contato

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/verify/contact \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "X-Country-Hint: AR" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+54 9 11 3456-7890","email":"juan@gmial.com"}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/verify/contact", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "X-Country-Hint": "AR",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "+54 9 11 3456-7890",
    email: "juan@gmial.com",
  }),
});

const data = await res.json();
console.log(data.phone.e164);            // "+5491134567890"
console.log(data.email.normalized);      // "juan@gmail.com"

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/verify/contact",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "X-Country-Hint": "AR",
        "Content-Type": "application/json",
    },
    json={
        "phone": "+54 9 11 3456-7890",
        "email": "juan@gmial.com",
    },
    timeout=10,
)
data = res.json()
print(data["phone"]["e164"], data["email"]["normalized"])

package main

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

type Phone struct {
	E164  string `json:"e164"`
	Valid bool   `json:"valid"`
}

type Email struct {
	Normalized string `json:"normalized"`
	Valid      bool   `json:"valid"`
}

type ContactResponse struct {
	Phone Phone `json:"phone"`
	Email Email `json:"email"`
}

func main() {
	body, _ := json.Marshal(map[string]string{
		"phone": "+54 9 11 3456-7890",
		"email": "juan@gmial.com",
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/verify/contact", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("X-Country-Hint", "AR")
	req.Header.Set("Content-Type", "application/json")

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

	var out ContactResponse
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.Phone.E164, out.Email.Normalized)
}

POST /v1/verify/bank

Bank — normalização bancária

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/verify/bank \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "X-Country-Hint: AR" \
  -H "Content-Type: application/json" \
  -d '{"cbu":"0170010600000123456780","iban":"DE89370400440532013000"}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/verify/bank", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "X-Country-Hint": "AR",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cbu: "0170010600000123456780",
    iban: "DE89370400440532013000",
  }),
});

const data = await res.json();
console.log(data.cbu.bank_name);   // "Galicia"
console.log(data.iban.country);    // "DE"

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/verify/bank",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "X-Country-Hint": "AR",
        "Content-Type": "application/json",
    },
    json={
        "cbu":  "0170010600000123456780",
        "iban": "DE89370400440532013000",
    },
    timeout=10,
)
data = res.json()
print(data["cbu"]["bank_name"], data["iban"]["country"])

package main

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

type Cbu struct {
	Normalized string `json:"normalized"`
	BankName   string `json:"bank_name"`
	Valid      bool   `json:"valid"`
}

type Iban struct {
	Normalized string `json:"normalized"`
	Country    string `json:"country"`
	Valid      bool   `json:"valid"`
}

type BankResponse struct {
	Cbu  Cbu  `json:"cbu"`
	Iban Iban `json:"iban"`
}

func main() {
	body, _ := json.Marshal(map[string]string{
		"cbu":  "0170010600000123456780",
		"iban": "DE89370400440532013000",
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/verify/bank", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("X-Country-Hint", "AR")
	req.Header.Set("Content-Type", "application/json")

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

	var out BankResponse
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.Cbu.BankName, out.Iban.Country)
}

POST /v1/verify/address

Address — normalização de endereços

Referência completa →

cURL

curl -X POST https://api.normadata.io/v1/verify/address \
  -H "X-API-Key: $NORMADATA_API_KEY" \
  -H "X-Country-Hint: AR" \
  -H "Content-Type: application/json" \
  -d '{"full_address":"Av. Corrientes 1234, Piso 5, Buenos Aires, Argentina","state":"buenos aires"}'

TypeScript

const res = await fetch("https://api.normadata.io/v1/verify/address", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NORMADATA_API_KEY!,
    "X-Country-Hint": "AR",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    full_address: "Av. Corrientes 1234, Piso 5, Buenos Aires, Argentina",
    state: "buenos aires",
  }),
});

const data = await res.json();
console.log(data.full_address.normalized);   // "Av. Corrientes 1234, Piso 5"
console.log(data.state.iso_3166_2);          // "AR-B"

Python

import os
import requests

res = requests.post(
    "https://api.normadata.io/v1/verify/address",
    headers={
        "X-API-Key": os.environ["NORMADATA_API_KEY"],
        "X-Country-Hint": "AR",
        "Content-Type": "application/json",
    },
    json={
        "full_address": "Av. Corrientes 1234, Piso 5, Buenos Aires, Argentina",
        "state":        "buenos aires",
    },
    timeout=10,
)
data = res.json()
print(data["full_address"]["normalized"], data["state"]["iso_3166_2"])

package main

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

type FullAddress struct {
	Normalized string `json:"normalized"`
	Valid      bool   `json:"valid"`
}

type State struct {
	Normalized string `json:"normalized"`
	Iso3166_2  string `json:"iso_3166_2"`
	Valid      bool   `json:"valid"`
}

type AddressResponse struct {
	FullAddress FullAddress `json:"full_address"`
	State       State       `json:"state"`
}

func main() {
	body, _ := json.Marshal(map[string]string{
		"full_address": "Av. Corrientes 1234, Piso 5, Buenos Aires, Argentina",
		"state":        "buenos aires",
	})
	req, _ := http.NewRequest("POST", "https://api.normadata.io/v1/verify/address", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("NORMADATA_API_KEY"))
	req.Header.Set("X-Country-Hint", "AR")
	req.Header.Set("Content-Type", "application/json")

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

	var out AddressResponse
	json.NewDecoder(res.Body).Decode(&out)
	fmt.Println(out.FullAddress.Normalized, out.State.Iso3166_2)
}

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/verify — Smart Parse — detecção universal de tipo
/v1/verify/person — Person — normalização de pessoas
/v1/verify/tax-id — Tax ID — validação de tax IDs
/v1/verify/contact — Contact — normalização de contato
/v1/verify/bank — Bank — normalização bancária
/v1/verify/address — Address — normalização de endereços