Sviluppatori

API di controllo doganale

Lo stesso controllo di questo sito, richiamato dal suo software. Lei invia una pratica in JSON e riceve un punteggio su 100, i punti bloccanti, gli avvisi e le azioni consigliate — con codici di anomalia stabili e messaggi tradotti nelle 24 lingue ufficiali dell'Unione europea.

Crea una chiave Specifica OpenAPI

È un'API da server a server. Una chiave API è un segreto. Le chiamate da un browser non sono supportate e nessuna intestazione CORS viene inviata sulle rotte autenticate: una chiave che arriva in un browser è una chiave divulgata.

Panoramica

L'API espone il motore di controllo del validatore: quattordici regole trasversali, cinque regole TARIC, quattro regole di completezza documentale e i validatori propri di ciascun sistema dichiarativo. Non trasmette nulla: verifica il formato e la coerenza della pratica, l'esistenza dei codici nella nomenclatura e, per un'importazione nell'UE, le misure TARIC applicabili all'origine (antidumping, controlli, preferenze, aliquota del dazio), prima che lei prepari la dichiarazione.

Tutte le rotte sono precedute dalla loro versione. Le rotte di scoperta e la specifica sono pubbliche: un integratore, o un agente, può leggere lo schema prima ancora di avere una chiave.

Rotta	Ruolo	Autenticazione
POST/v1/checks	Controlla una pratica e restituisce il rapporto completo	Chiave richiesta
POST/v1/checks/batch	Controlla fino a 25 pratiche in una chiamata	Chiave richiesta
GET/v1/me	Restituisce la chiave corrente e la sua quota, senza consumarla	Chiave richiesta
GET/v1/declaration-types	Elenca i tipi di dichiarazione riconosciuti	Pubblica
GET/v1/declaration-types/{type}	Descrive i campi attesi per un tipo	Pubblica
GET/v1/openapi.json	La specifica OpenAPI 3.1 di questa API	Pubblica

Autenticazione

L'API si autentica con un token bearer. Il token viene mostrato una sola volta, alla creazione: se ne conserva solo l'impronta, quindi una chiave persa si sostituisce, non si recupera.

Può detenere tre chiavi attive alla volta, il che consente di ruotare una chiave senza interrompere l'integrazione: crei la nuova, la distribuisca, poi revochi la vecchia.

01Crei una chiave dal suo account, alla voce «Chiavi API».
02La invii nell'intestazione Authorization di ogni richiesta.
03La revochi in caso di fuga: l'interruzione è immediata e il contenuto delle pratiche inviate con quella chiave viene subito eliminato.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Primo controllo

Una pratica si compone di un tipo, di una testata e di righe merce. Tutti i valori sono stringhe: il motore si occupa di interpretarle. I nomi dei campi si scoprono a runtime, tipo per tipo.

La risposta arriva subito; non c'è nulla da interrogare in seguito.

Richiesta

curl https://www.customs-check.com/api/v1/checks \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "import-export",
    "reference": "PO-2026-114",
    "header": {
      "flow": "IM",
      "shipmentCountry": "CN",
      "destinationCountry": "FR",
      "incoterm": "FOB",
      "companyName": "Acme SAS",
      "companyCountry": "FR",
      "eori": "FR12345678900012",
      "transportMode": "sea",
      "currency": "USD",
      "invoiceTotal": "12500"
    },
    "items": [
      {
        "description": "Leather sport shoes",
        "hsCode": "6403990000",
        "quantity": "500",
        "value": "12500",
        "origin": "VN",
        "grossMass": "850",
        "netMass": "800"
      }
    ],
    "documents": { "commercialInvoice": "available", "packingList": "missing" }
  }'

Leggere la risposta

Ogni anomalia porta sia un'identità macchina sia una frase leggibile. Costruisca la sua logica sull'identità macchina: non cambia senza un cambio di versione.

severity · code · path · rule: Contratto stabileStabili. Possono comparire nuovi codici; quelli esistenti non vengono rinominati senza un cambio di versione.
field · message · text: Solo visualizzazioneTradotti per la visualizzazione. Possono essere riformulati in qualsiasi momento: non li confronti mai nel suo codice.
engine.version: Cambia non appena un'evoluzione delle regole modifica il punteggio di una pratica invariata. La archivi insieme ai suoi rapporti.

Il campo «path» rispecchia la forma della sua richiesta, così può collegare un'anomalia direttamente al campo corrispondente nella sua interfaccia.

header.<campo> · items.<n>.<campo> · documents.<category> · global

Risposta

{
  "id": "4c749e25-3408-48f9-b3ca-b18a7ad84681",
  "createdAt": "2026-09-16T12:46:13.186Z",
  "type": "import-export",
  "locale": "en",
  "reference": "PO-2026-114",
  "score": 90,
  "level": "good",
  "counts": { "errors": 0, "warnings": 2, "infos": 1 },
  "documents": { "commercialInvoice": "available", "packingList": "missing" },
  "issues": [
    {
      "severity": "warning",
      "code": "docPackingListMissing",
      "path": "documents.packingList",
      "rule": "DOC-002",
      "params": null,
      "field": "Packing list",
      "message": "Packing list not provided",
      "text": "Packing list not provided"
    },
    {
      "severity": "warning",
      "code": "docTransportMissing",
      "path": "documents.transportDocument",
      "rule": "DOC-003",
      "params": null,
      "field": "Transport document (B/L, AWB, CMR)",
      "message": "Transport document not provided",
      "text": "Transport document not provided"
    }
  ],
  "actions": [
    { "severity": "warning", "code": "docPackingListMissing",
      "path": "documents.packingList", "text": "Add: Packing list" }
  ],
  "tips": [
    {
      "severity": "info",
      "code": "taricControlsPossible",
      "path": "items.0.hsCode",
      "rule": "RULE-017",
      "params": { "measures": "Import control - CITES ; Import control on seal products" },
      "field": "Product 1 — HS / commodity code (if known)",
      "message": "Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply.",
      "text": "Product 1 — HS / commodity code (if known): Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply."
    }
  ],
  "engine": { "version": "1.6.0", "rules": 25, "taric": "2026-10-01" }
}

Scoprire i campi

I tipi di dichiarazione e i loro campi sono pubblici, nessuna chiave necessaria. È la rotta da usare per costruire un modulo, alimentare una mappatura dal suo ERP o dare a un agente lo schema da compilare.

I nomi restituiti qui sono esattamente le chiavi da usare nella testata e in ogni riga merce. Gli elenchi di opzioni arrivano risolti e tradotti; aggiunga il parametro per ometterli se la risposta le sembra pesante.

# The 8 declaration types
curl "https://www.customs-check.com/api/v1/declaration-types?locale=en"

# The fields of one type
curl "https://www.customs-check.com/api/v1/declaration-types/h7?locale=en"

# Same, without the resolved option lists
curl "https://www.customs-check.com/api/v1/declaration-types/h7?options=false"

Elaborazione in lotto

Fino a 25 pratiche per chiamata. La risposta è sempre un successo una volta accettato il lotto, e ogni voce porta il proprio stato: una pratica malformata non fa mai fallire le altre.

Se la quota residua non copre tutte le voci valide, l'intero lotto viene rifiutato anziché elaborato parzialmente — non dovrà mai indovinare dove si è fermata l'elaborazione.

curl https://www.customs-check.com/api/v1/checks/batch \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "checks": [ { "type": "h7", "header": {}, "items": [] } ] }'

Agenti e strumenti

Oltre alle route REST, lo stesso motore e gli stessi dati sono raggiungibili da un assistente di IA, tramite un server Model Context Protocol (MCP), e da un client API, tramite una collezione Postman già pronta. Entrambi usano la chiave API e la quota giornaliera descritte sopra.

Server MCP

Il server MCP permette a un assistente di cercare codici doganali, leggere il dazio all'importazione UE di un codice, verificare un numero EORI, IVA o AEO nei registri ufficiali e controllare una bozza di dichiarazione, senza che tu scriva una riga di codice di collegamento. Risponde su POST /api/mcp, con risposte JSON.

È senza stato e parla entrambe le generazioni del protocollo: la revisione 2026-07-28, in cui ogni richiesta porta la propria versione, e le revisioni precedenti, che si aprono con una chiamata initialize. Connessione, scoperta ed elenco degli strumenti non costano nulla; ogni chiamata a uno strumento consuma un'unità della quota giornaliera della chiave.

L'autenticazione usa lo stesso token bearer dell'API REST. Un client che supporta solo l'accesso OAuth, come i connettori web di claude.ai, non può ancora connettersi: usa un client che consenta di impostare un'intestazione.

POST https://www.customs-check.com/api/mcp

claude mcp add --transport http customs-check https://www.customs-check.com/api/mcp \
  --header "Authorization: Bearer $CUSTOM_CHECK_KEY"

check_declaration	Controlla una bozza di dichiarazione: punteggio su 100, livello e ogni problema con il campo e l'azione. Non conserva il contenuto del file se non richiesto.
list_declaration_types	I sistemi di dichiarazione supportati, con autorità, regione e documenti attesi.
describe_declaration_type	I campi di intestazione e di voce di un tipo, per costruire l'input di check_declaration.
search_hs_codes	Codici candidati della Nomenclatura combinata a partire dalla descrizione di un prodotto, in una qualsiasi delle 24 lingue dell'UE.
describe_hs_code	Se un codice di 4-10 cifre esiste nella nomenclatura in vigore, con il suo percorso e il suo testo ufficiali.
lookup_import_duty	Dazio all'importazione UE di un codice dai dati TARIC della Commissione: dazio dei paesi terzi, preferenze per un'origine, contingenti, antidumping e controlli.
search_chemical	Una sostanza chimica per numero CAS, numero CUS o nome nell'inventario ECICS della Commissione: il codice della nomenclatura combinata dato per ogni voce, da verificare.
get_quota_balance	Saldo residuo di un contingente tariffario dell'UE nella banca dati QUOTA della Commissione, dal suo numero d'ordine o da un codice e un'origine: saldo, stato (aperto, critico, bloccato, esaurito), periodo e ora della lettura.
validate_eori	Formato di un numero EORI e suo stato nel registro ufficiale (Commissione europea, HMRC).
validate_vat	Formato di un numero di partita IVA UE e sua validità in VIES, con la denominazione registrata se pubblicata.
check_rex	Formato di un numero REX di esportatore registrato e suo stato nella banca dati REX della Commissione (valido, revocato o sconosciuto), con le relative date.
screen_sanctions	Un'azienda, una persona o una nave rispetto agli elenchi delle sanzioni di UE, ONU, Regno Unito e Stati Uniti, aggiornati ogni giorno: ogni corrispondenza con il suo punteggio, forte o parziale.
search_aeo	Ricerca nella banca dati della Commissione degli operatori economici autorizzati per nome dell'impresa.

I codici doganali sono proposte tratte dal testo della nomenclatura. Solo il dichiarante, o un'informazione tariffaria vincolante della dogana, può confermare una classificazione.
I dazi sono indicativi: condizioni, esclusioni per paese e contingenti esauriti non sono valutati. Ogni risposta porta la data di riferimento dell'estratto TARIC, aggiornato ogni mese.
Un registro che non risponde è segnalato come non disponibile, mai come numero non valido. Non viene mai inviato nulla alla dogana.

Collezione Postman

La collezione è generata dalla specifica OpenAPI, quindi vi corrisponde sempre: una richiesta per route, raggruppate per tag, con uno scheletro di body per ogni POST. Importala in Postman, compila la variabile apiKey (conservata come segreto) e le richieste sono pronte da inviare.

Scarica la collezione

Quota

Ogni chiave dispone di 500 controlli per giorno solare UTC. Lo stato corrente viaggia con ogni risposta autenticata, quindi non serve mai una chiamata in più per conoscerlo.

Anche le chiamate rifiutate contano: un client che insiste con richieste non valide si limita da solo. La quota è fissata per chiave — ci scriva se le serve di più.

Risposta

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 437
X-RateLimit-Reset: 1789603200
X-RateLimit-Policy: 500;w=86400

Errori

I messaggi di errore sono solo in inglese: sono messaggi di protocollo, destinati agli sviluppatori. Solo il contenuto di merito è tradotto.

Ogni risposta porta un identificativo di richiesta, ripetuto nel corpo. Lo citi quando ci contatta: ci porta direttamente alla chiamata.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body failed validation.",
    "details": [
      { "path": "items.0.quantity", "message": "expected a string" }
    ],
    "requestId": "2bbb0946-6178-4b54-921c-b28f794c44bd"
  }
}

Stato	code	Significato
400	invalid_json	Il corpo non è JSON valido.
422	invalid_request	Il JSON è valido ma il suo contenuto no. Il dettaglio indica il campo errato.
401	missing_credentials	Intestazione Authorization assente o malformata.
401	invalid_key	Chiave sconosciuta.
401	key_revoked	Chiave revocata.
403	account_suspended	L'account proprietario della chiave è sospeso.
415	unsupported_media_type	Il tipo di contenuto non è JSON.
413	payload_too_large	Corpo della richiesta troppo grande.
429	rate_limit_exceeded	Quota giornaliera raggiunta. Veda l'intestazione Retry-After.
500	internal_error	Errore dalla nostra parte. Riprovi, poi ce lo segnali con l'identificativo di richiesta.

Dati e conservazione

Le pratiche inviate tramite l'API sono dati dei suoi clienti: conserviamo il meno possibile e lei dispone di un interruttore per non conservare nulla.

Invii «store» a false e nessun contenuto della pratica verrà scritto: restano solo il punteggio e i codici di anomalia.
Altrimenti il contenuto delle pratiche viene eliminato dopo 30 giorni.
Revocare una chiave elimina immediatamente il contenuto delle pratiche che ha inviato.
L'elaborazione avviene a Francoforte e la base dati è ospitata nell'Unione europea.
Nessun file viene caricato tramite l'API: lei dichiara soltanto quali documenti possiede.

200 items · 256 KB · 25 / batch · reference ≤ 64

Ciò che questa API non è

Il controllo è un aiuto alla preparazione. Non costituisce una convalida da parte dell'amministrazione doganale, non presenta nulla e non sostituisce gli obblighi normativi applicabili alla sua operazione.

I codici doganali sono verificati nel formato, nell'esistenza nella nomenclatura e, per le importazioni nell'UE, rispetto alle misure TARIC della loro origine, mai nella classificazione della merce: un codice esistente resta un codice da verificare. Le misure TARIC sono indicative (estrazione mensile della Commissione europea): esclusioni di paesi, contingenti esauriti e dazi condizionati non sono valutati.