Validación de registros completosBETAcore beta

Validá una entidad completa (tax_id, account, email, phone, name, address) por campo, chequeá consistencia y resumí readiness (payment, billing). Hasta 500 records por request.

Contrato estable; cambios breaking solo con deprecation previo.

POST/v1/validate/records

Resumen

Validate a batch of complete records (suppliers, customers). Each item declares its `country` (required) and any subset of fields: `tax_id`, `account` (+ optional `account_type`), `email`, `phone`, `name`, `address`. Every present field is validated with its own normalizer (reusing the per-field logic — no checksum reimplemented). The response adds `consistency[]` checks between fields and against the declared country (country↔tax_id, country↔account) and `readiness` per business process: `payment` (ready to pay) and `billing` (ready to invoice). Up to 500 records per request.

URL base: https://api.normadata.io

Header de autenticación: X-API-Key: nd-...

Cuerpo del request

Campo	Tipo	Obligatorio	Descripción
items	array	sí	Array of records to validate (1–500). Each item is the object described below.
items[].reference_id	string	no	Client-provided correlation id, echoed back verbatim in the matching result.
items[].country	string	sí	ISO 3166-1 alpha-2 country code. Used for per-field validation and consistency checks.
items[].tax_id	string	no	Tax / national ID. Type is resolved within the country.
items[].account	string	no	Bank account number (CBU, CVU, CLABE, CCI, IBAN).
items[].account_type	string	no	Account type ∈ {cbu, cvu, clabe, cci, iban}. If omitted, detected from country + format.
items[].email	string	no	Email address.
items[].phone	string	no	Phone number (parsed using country as region).
items[].name	string	no	Full person name (smart split into first / paternal surname).
items[].address	string	no	Free-form postal address.

Ejemplo de request

cURL

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

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"`
	Country     string `json:"country"`
	Readiness   struct {
		Payment ReadinessFlag `json:"payment"`
		Billing ReadinessFlag `json:"billing"`
	} `json:"readiness"`
}

type RecordResponse struct {
	Results []RecordResult `json:"results"`
}

func main() {
	body, _ := json.Marshal(map[string][]RecordItem{
		"items": {
			{
				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 RecordResponse
	json.NewDecoder(res.Body).Decode(&out)
	for _, r := range out.Results {
		fmt.Println(r.ReferenceID, r.Readiness.Payment.Status, r.Readiness.Billing.Status)
	}
}

Ejemplo de respuesta

Ejemplo de respuesta `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" }
      }
    }
  ]
}

Errores comunes

Códigos de error que podés encontrar al llamar este endpoint. El envelope completo está documentado en la referencia principal.

Código
empty_batch
batch_too_large
quota_exceeded

Ver todos los códigos de error →

Notas

Not KYC or identity verification, and no government lookups — it confirms the record is well-formed and internally consistent, not that the entity exists. `readiness` has only `payment` and `billing`. `payment.ready` ⟺ tax_id valid + account valid + checksum verified + country↔account consistent. `billing.ready` ⟺ tax_id valid + name present. The envelope is shared by every endpoint: POST `{items:[…]}` (1–500 for records) → `{results:[…]}` correlated by `reference_id`.

Endpoints relacionados

POST /v1/validate/tax-ids

Validación de Tax IDs en lote

POST /v1/validate/accounts

Validación de cuentas bancarias en lote

POST /v1/validate/emails

Validación de emails en lote

POST /v1/validate/phones

Validación de teléfonos en lote

Acceso