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: tredici regole trasversali, quattro regole di completezza documentale e i validatori propri di ciascun sistema dichiarativo. Non trasmette nulla e non interroga alcuna banca dati tariffaria — verifica la coerenza interna e il formato della sua pratica 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.

1Crei una chiave dal suo account, alla voce «Chiavi API».
2La invii nell'intestazione Authorization di ogni richiesta.
3La 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": 0 },
  "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": [],
  "engine": { "version": "1.0.0", "rules": 13 }
}

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": [] } ] }'

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 e nella coerenza con l'operazione, mai confrontati con una banca dati tariffaria: un codice ben formato resta un codice da verificare.