Dezvoltatori

API de verificare vamală

Aceeași verificare ca pe acest site, apelată din propriul dumneavoastră software. Trimiteți un dosar în JSON și primiți un scor din 100, punctele blocante, alertele și acțiunile recomandate — cu coduri de anomalie stabile și mesaje traduse în cele 24 de limbi oficiale ale Uniunii Europene.

Creați o cheie Specificație OpenAPI

Acesta este un API server-la-server. O cheie API este un secret. Apelurile dintr-un browser nu sunt acceptate și niciun antet CORS nu este trimis pe rutele autentificate: o cheie care ajunge într-un browser este o cheie divulgată.

Prezentare generală

API-ul expune motorul de control al validatorului: paisprezece reguli transversale, cinci reguli TARIC, patru reguli de completitudine a documentelor și validatorii proprii fiecărui sistem declarativ. Nu transmite nimic: verifică formatul și coerența dosarului, existența codurilor în nomenclatură și, pentru un import în UE, măsurile TARIC aplicabile originii (antidumping, controale, preferințe, cota taxei), înainte să pregătiți declarația.

Toate rutele au prefixul versiunii lor. Rutele de descoperire și specificația sunt publice: un integrator sau un agent poate citi schema înainte de a avea o cheie.

Rută	Rol	Autentificare
POST/v1/checks	Verifică un dosar și returnează raportul complet	Cheie necesară
POST/v1/checks/batch	Verifică până la 25 de dosare într-un singur apel	Cheie necesară
GET/v1/me	Returnează cheia curentă și cota ei, fără să o consume	Cheie necesară
GET/v1/declaration-types	Listează tipurile de declarație recunoscute	Publică
GET/v1/declaration-types/{type}	Descrie câmpurile așteptate pentru un tip	Publică
GET/v1/openapi.json	Specificația OpenAPI 3.1 a acestui API	Publică

Autentificare

API-ul se autentifică printr-un token purtător. Tokenul este afișat o singură dată, la creare: se păstrează doar amprenta lui, așa că o cheie pierdută se înlocuiește, nu se recuperează.

Puteți deține trei chei active simultan, ceea ce permite rotirea unei chei fără a întrerupe integrarea: creați-o pe cea nouă, implementați-o, apoi revocați-o pe cea veche.

01Creați o cheie din contul dumneavoastră, la „Chei API”.
02Trimiteți-o în antetul Authorization al fiecărei cereri.
03Revocați-o dacă se scurge: întreruperea este imediată, iar conținutul dosarelor trimise cu acea cheie este șters imediat.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prima verificare

Un dosar se compune dintr-un tip, un antet și linii de marfă. Toate valorile sunt șiruri de caractere: motorul se ocupă de interpretarea lor. Numele câmpurilor se descoperă în execuție, tip cu tip.

Răspunsul sosește imediat; după aceea nu mai este nimic de interogat.

Cerere

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" }
  }'

Citirea răspunsului

Fiecare anomalie poartă atât o identitate de mașină, cât și o frază lizibilă. Construiți-vă logica pe identitatea de mașină: nu se schimbă fără o schimbare de versiune.

severity · code · path · rule: Contract stabilStabile. Pot apărea coduri noi; cele existente nu sunt redenumite fără o schimbare de versiune.
field · message · text: Doar afișareTraduse pentru afișare. Pot fi reformulate oricând — nu le comparați niciodată în cod.
engine.version: Se schimbă de îndată ce o evoluție a regulilor modifică scorul unui dosar neschimbat. Arhivați-o odată cu rapoartele.

Câmpul „path” reflectă forma cererii dumneavoastră, astfel încât puteți lega o anomalie direct de câmpul corespunzător din propria interfață.

header.<câmp> · items.<n>.<câmp> · documents.<category> · global

Răspuns

{
  "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" }
}

Descoperirea câmpurilor

Tipurile de declarație și câmpurile lor sunt publice, nu este nevoie de cheie. Este ruta de folosit pentru a construi un formular, a alimenta o mapare din ERP-ul dumneavoastră sau a da unui agent schema pe care trebuie să o completeze.

Numele returnate aici sunt exact cheile de folosit în antet și în fiecare linie de marfă. Listele de opțiuni sosesc rezolvate și traduse; adăugați parametrul pentru a le omite dacă răspunsul vi se pare greu.

# 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"

Procesare în lot

Până la 25 de dosare pe apel. Răspunsul este întotdeauna un succes odată ce lotul este acceptat, iar fiecare intrare poartă propria stare: un dosar prost format nu face niciodată să eșueze celelalte.

Dacă cota rămasă nu acoperă toate intrările valide, întregul lot este refuzat în loc să fie procesat parțial — nu trebuie niciodată să ghiciți unde s-a oprit procesarea.

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

Agenți și instrumente

Pe lângă rutele REST, același motor și aceleași date pot fi accesate de la un asistent de IA, printr-un server Model Context Protocol (MCP), și de la un client API, printr-o colecție Postman gata făcută. Ambele folosesc cheia API și cota zilnică descrise mai sus.

Server MCP

Serverul MCP permite unui asistent să caute coduri vamale, să citească taxa vamală de import a UE pentru un cod, să verifice un număr EORI, de TVA sau AEO în registrele oficiale și să verifice un proiect de declarație, fără să scrieți nicio linie de cod de legătură. Răspunde la POST /api/mcp, cu răspunsuri JSON.

Este fără stare și vorbește ambele generații ale protocolului: revizia 2026-07-28, în care fiecare cerere poartă versiunea ei, și reviziile anterioare, care încep cu un apel initialize. Conectarea, descoperirea și listarea instrumentelor nu costă nimic; fiecare apel de instrument consumă o unitate din cota zilnică a cheii.

Autentificarea este același token bearer ca la API-ul REST. Un client care acceptă doar conectarea OAuth, precum conectorii web ai claude.ai, nu se poate conecta încă: folosiți un client care vă permite să setați un antet.

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	Verifică un proiect de declarație: scor din 100, nivel și fiecare problemă cu câmpul și acțiunea. Nu păstrează conținutul fișierului decât dacă se cere.
list_declaration_types	Sistemele de declarare acceptate, cu autoritate, regiune și documente așteptate.
describe_declaration_type	Câmpurile de antet și de articol ale unui tip, pentru a construi intrarea pentru check_declaration.
search_hs_codes	Coduri candidate din Nomenclatura combinată pe baza descrierii unui produs, în oricare dintre cele 24 de limbi ale UE.
describe_hs_code	Dacă un cod de 4 până la 10 cifre există în nomenclatura în vigoare, cu calea și textul său oficiale.
lookup_import_duty	Taxa vamală de import a UE pentru un cod, din datele TARIC ale Comisiei: taxa pentru țări terțe, preferințe pentru o origine, contingente, antidumping și controale.
search_chemical	O substanță chimică după număr CAS, număr CUS sau denumire în inventarul ECICS al Comisiei: codul din Nomenclatura Combinată dat pentru fiecare intrare, de verificat.
get_quota_balance	Soldul rămas al unui contingent tarifar al UE în baza de date QUOTA a Comisiei, după numărul de ordine sau după un cod și o origine: sold, stare (deschis, critic, blocat, epuizat), perioadă și ora citirii.
validate_eori	Formatul unui număr EORI și starea lui în registrul oficial (Comisia Europeană, HMRC).
validate_vat	Formatul unui număr de TVA din UE și valabilitatea lui în VIES, cu denumirea înregistrată acolo unde este publicată.
check_rex	Formatul unui număr REX de exportator înregistrat și starea sa în baza de date REX a Comisiei (valabil, revocat sau necunoscut), cu datele aferente.
screen_sanctions	O companie, o persoană sau o navă față de listele de sancțiuni ale UE, ONU, Regatului Unit și Statelor Unite, actualizate zilnic: fiecare corespondență cu scorul ei, puternică sau parțială.
search_aeo	Căutare în baza de date a Comisiei privind operatorii economici autorizați, după denumirea societății.

Codurile vamale sunt propuneri preluate din textul nomenclaturii. Doar declarantul sau o informație tarifară obligatorie a vămii poate confirma o clasificare.
Taxele sunt orientative: condițiile, excluderile pe țări și contingentele epuizate nu sunt evaluate. Fiecare răspuns poartă data de referință a extrasului TARIC, reîmprospătat lunar.
Un registru care nu răspunde este raportat ca indisponibil, niciodată ca număr invalid. Nu se trimite niciodată nimic vămii.

Colecție Postman

Colecția este generată din specificația OpenAPI, deci îi corespunde întotdeauna: o cerere pe rută, grupate pe etichetă, cu un schelet de corp pentru fiecare POST. Importați-o în Postman, completați variabila apiKey (păstrată ca secret) și cererile sunt gata de trimis.

Descărcați colecția

Cotă

Fiecare cheie dispune de 500 de verificări pe zi calendaristică UTC. Starea curentă călătorește cu fiecare răspuns autentificat, deci nu aveți niciodată nevoie de un apel suplimentar pentru a o afla.

Apelurile refuzate se numără și ele: un client care insistă cu cereri invalide se limitează singur. Cota este stabilită pe cheie — scrieți-ne dacă aveți nevoie de mai mult.

Răspuns

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

Erori

Mesajele de eroare sunt doar în engleză: sunt mesaje de protocol, destinate dezvoltatorilor. Doar conținutul de business este tradus.

Fiecare răspuns poartă un identificator de cerere, repetat în corp. Citați-l când ne contactați — ne duce direct la apel.

{
  "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"
  }
}

Stare	code	Semnificație
400	invalid_json	Corpul nu este JSON valid.
422	invalid_request	JSON-ul este valid, dar conținutul lui nu. Detaliul indică câmpul greșit.
401	missing_credentials	Antetul Authorization lipsește sau este greșit format.
401	invalid_key	Cheie necunoscută.
401	key_revoked	Cheie revocată.
403	account_suspended	Contul proprietar al cheii este suspendat.
415	unsupported_media_type	Tipul de conținut nu este JSON.
413	payload_too_large	Corpul cererii este prea mare.
429	rate_limit_exceeded	Cotă zilnică atinsă. Vedeți antetul Retry-After.
500	internal_error	Eroare de partea noastră. Reîncercați, apoi semnalați-ne-o cu identificatorul de cerere.

Date și păstrare

Dosarele trimise prin API sunt datele clienților dumneavoastră: păstrăm cât mai puțin posibil, iar dumneavoastră aveți un comutator pentru a nu păstra nimic.

Trimiteți „store” cu valoarea false și niciun conținut al dosarului nu va fi scris: rămân doar scorul și codurile de anomalie.
În caz contrar, conținutul dosarelor este șters după 30 de zile.
Revocarea unei chei șterge imediat conținutul dosarelor trimise cu ea.
Prelucrarea are loc la Frankfurt, iar baza de date este găzduită în Uniunea Europeană.
Niciun fișier nu este încărcat prin API: declarați doar ce documente dețineți.

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

Ce nu este acest API

Verificarea este un ajutor la pregătire. Nu constituie o validare din partea administrației vamale, nu depune nimic și nu înlocuiește obligațiile de reglementare aplicabile operațiunii dumneavoastră.

Codurile vamale sunt verificate ca format, ca existență în nomenclatură și, la importul în UE, față de măsurile TARIC ale originii lor, niciodată ca încadrare a mărfii: un cod existent rămâne un cod de verificat. Măsurile TARIC sunt orientative (extragere lunară a Comisiei Europene): excluderile de țări, contingentele epuizate și taxele condiționate nu sunt evaluate.