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 verificare al validatorului: treisprezece reguli transversale, patru reguli de completitudine documentară și validatoarele proprii fiecărui sistem declarativ. Nu transmite nimic și nu interoghează nicio bază tarifară — verifică coerența internă și formatul dosarului dumneavoastră înainte de a pregăti 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.

1Creați o cheie din contul dumneavoastră, la „Chei API”.
2Trimiteți-o în antetul Authorization al fiecărei cereri.
3Revocaț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": 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 }
}

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

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 și coerență cu operațiunea, niciodată confruntate cu o bază tarifară: un cod bine format rămâne un cod de verificat.