Προγραμματιστές

API τελωνειακού ελέγχου

Ο ίδιος έλεγχος όπως σε αυτόν τον ιστότοπο, καλούμενος από το δικό σας λογισμικό. Στέλνετε έναν φάκελο σε JSON και λαμβάνετε βαθμολογία στα 100, τα ανασταλτικά σημεία, τις προειδοποιήσεις και τις συνιστώμενες ενέργειες — με σταθερούς κωδικούς αποκλίσεων και μηνύματα στις 24 επίσημες γλώσσες της Ευρωπαϊκής Ένωσης.

Δημιουργία κλειδιού Προδιαγραφή OpenAPI

Πρόκειται για API διακομιστή προς διακομιστή. Ένα κλειδί API είναι μυστικό. Οι κλήσεις από πρόγραμμα περιήγησης δεν υποστηρίζονται και δεν αποστέλλεται καμία κεφαλίδα CORS στις διαδρομές με ταυτοποίηση: ένα κλειδί που φτάνει σε πρόγραμμα περιήγησης είναι κλειδί που έχει διαρρεύσει.

Επισκόπηση

Το API εκθέτει τη μηχανή ελέγχου του επικυρωτή: δεκατέσσερις οριζόντιους κανόνες, πέντε κανόνες TARIC, τέσσερις κανόνες πληρότητας εγγράφων και τους επικυρωτές κάθε συστήματος διασάφησης. Δεν διαβιβάζει τίποτα: ελέγχει τη μορφή και τη συνοχή του φακέλου σας, την ύπαρξη των κωδικών στην ονοματολογία και, για εισαγωγή στην ΕΕ, τα μέτρα TARIC που ισχύουν για την καταγωγή (αντιντάμπινγκ, έλεγχοι, προτιμήσεις, δασμολογικός συντελεστής), πριν προετοιμάσετε τη διασάφηση.

Κάθε διαδρομή φέρει το πρόθεμα της έκδοσής της. Οι διαδρομές ανακάλυψης και η προδιαγραφή είναι δημόσιες: ένας ενσωματωτής, ή ένας πράκτορας, μπορεί να διαβάσει το σχήμα πριν καν αποκτήσει κλειδί.

Διαδρομή	Ρόλος	Ταυτοποίηση
POST/v1/checks	Ελέγχει έναν φάκελο και επιστρέφει την πλήρη αναφορά	Απαιτείται κλειδί
POST/v1/checks/batch	Ελέγχει έως 25 φακέλους σε μία κλήση	Απαιτείται κλειδί
GET/v1/me	Επιστρέφει το τρέχον κλειδί και το όριό του, χωρίς να το καταναλώνει	Απαιτείται κλειδί
GET/v1/declaration-types	Απαριθμεί τους αναγνωρισμένους τύπους διασάφησης	Δημόσια
GET/v1/declaration-types/{type}	Περιγράφει τα πεδία που αναμένονται για έναν τύπο	Δημόσια
GET/v1/openapi.json	Η προδιαγραφή OpenAPI 3.1 αυτού του API	Δημόσια

Ταυτοποίηση

Το API ταυτοποιείται με διακριτικό τύπου bearer. Το διακριτικό εμφανίζεται μία μόνο φορά, κατά τη δημιουργία: διατηρείται μόνο το αποτύπωμά του, οπότε ένα χαμένο κλειδί αντικαθίσταται, ποτέ δεν ανακτάται.

Μπορείτε να διατηρείτε τρία ενεργά κλειδιά ταυτόχρονα, κάτι που επιτρέπει την εναλλαγή κλειδιού χωρίς διακοπή της ενσωμάτωσης: δημιουργήστε το νέο, αναπτύξτε το και μετά ανακαλέστε το παλιό.

01Δημιουργήστε ένα κλειδί από τον λογαριασμό σας, στα «Κλειδιά API».
02Στείλτε το στην κεφαλίδα Authorization κάθε αιτήματος.
03Ανακαλέστε το σε περίπτωση διαρροής: η διακοπή είναι άμεση και το περιεχόμενο των φακέλων που υποβλήθηκαν με αυτό το κλειδί διαγράφεται αμέσως.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Πρώτος έλεγχος

Ένας φάκελος αποτελείται από έναν τύπο, μια κεφαλίδα και γραμμές εμπορευμάτων. Όλες οι τιμές είναι συμβολοσειρές: η μηχανή αναλαμβάνει την ερμηνεία τους. Τα ονόματα των πεδίων ανακαλύπτονται κατά την εκτέλεση, τύπο προς τύπο.

Η απόκριση έρχεται αμέσως· δεν υπάρχει τίποτα να ερωτηθεί στη συνέχεια.

Αίτημα

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

Ανάγνωση της απόκρισης

Κάθε απόκλιση φέρει ταυτόχρονα μηχανική ταυτότητα και μια αναγνώσιμη πρόταση. Χτίστε τη λογική σας στη μηχανική ταυτότητα: δεν αλλάζει χωρίς αλλαγή έκδοσης.

severity · code · path · rule: Σταθερό συμβόλαιοΣταθεροί. Μπορεί να εμφανιστούν νέοι κωδικοί· οι υπάρχοντες δεν μετονομάζονται χωρίς αλλαγή έκδοσης.
field · message · text: Μόνο εμφάνισηΜεταφρασμένα για εμφάνιση. Μπορούν να αναδιατυπωθούν ανά πάσα στιγμή — μην τα συγκρίνετε ποτέ στον κώδικά σας.
engine.version: Αλλάζει μόλις μια εξέλιξη των κανόνων μετακινήσει τη βαθμολογία ενός αμετάβλητου φακέλου. Αρχειοθετήστε την μαζί με τις αναφορές σας.

Το πεδίο «path» αντικατοπτρίζει τη μορφή του αιτήματός σας, ώστε να συνδέετε μια απόκλιση απευθείας με το αντίστοιχο πεδίο στη δική σας διεπαφή.

header.<πεδίο> · items.<n>.<πεδίο> · documents.<category> · global

Απόκριση

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

Ανακάλυψη των πεδίων

Οι τύποι διασάφησης και τα πεδία τους είναι δημόσια, δεν χρειάζεται κλειδί. Αυτή είναι η διαδρομή για να χτίσετε μια φόρμα, να τροφοδοτήσετε μια αντιστοίχιση από το ERP σας ή να δώσετε σε έναν πράκτορα το σχήμα που πρέπει να συμπληρώσει.

Τα ονόματα που επιστρέφονται εδώ είναι ακριβώς τα κλειδιά που χρησιμοποιούνται στην κεφαλίδα και σε κάθε γραμμή εμπορεύματος. Οι λίστες επιλογών επιστρέφονται επιλυμένες και μεταφρασμένες· προσθέστε την παράμετρο για να τις παραλείψετε αν η απόκριση σας φαίνεται βαριά.

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

Μαζική επεξεργασία

Έως 25 φάκελοι ανά κλήση. Η απόκριση είναι πάντα επιτυχία μόλις γίνει δεκτή η παρτίδα, και κάθε καταχώριση φέρει τη δική της κατάσταση: ένας κακοσχηματισμένος φάκελος δεν αποτυγχάνει ποτέ τους υπόλοιπους.

Αν το υπόλοιπο όριο δεν καλύπτει όλες τις έγκυρες καταχωρίσεις, απορρίπτεται ολόκληρη η παρτίδα αντί να επεξεργαστεί μερικώς — δεν χρειάζεται ποτέ να μαντέψετε πού σταμάτησε η επεξεργασία.

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

Πράκτορες και εργαλεία

Εκτός από τις διαδρομές REST, η ίδια μηχανή και τα ίδια δεδομένα είναι προσβάσιμα από βοηθό τεχνητής νοημοσύνης, μέσω διακομιστή Model Context Protocol (MCP), και από πελάτη API, μέσω έτοιμης συλλογής Postman. Και τα δύο χρησιμοποιούν το κλειδί API και την ημερήσια ποσόστωση που περιγράφονται παραπάνω.

Διακομιστής MCP

Ο διακομιστής MCP επιτρέπει σε έναν βοηθό να αναζητά κωδικούς τελωνειακής ονοματολογίας, να διαβάζει τον εισαγωγικό δασμό της ΕΕ για έναν κωδικό, να ελέγχει έναν αριθμό EORI, ΦΠΑ ή AEO στα επίσημα μητρώα και να ελέγχει ένα προσχέδιο διασάφησης, χωρίς να γράψετε ούτε μία γραμμή κώδικα σύνδεσης. Απαντά στο POST /api/mcp, με απαντήσεις JSON.

Δεν διατηρεί κατάσταση και μιλά και τις δύο γενιές του πρωτοκόλλου: την αναθεώρηση 2026-07-28, όπου κάθε αίτημα φέρει την έκδοσή του, και τις παλαιότερες αναθεωρήσεις, που ξεκινούν με κλήση initialize. Η σύνδεση, η ανακάλυψη και η παράθεση των εργαλείων δεν κοστίζουν τίποτα· κάθε κλήση εργαλείου καταναλώνει μία μονάδα της ημερήσιας ποσόστωσης του κλειδιού.

Η ταυτοποίηση γίνεται με το ίδιο bearer token όπως στο REST API. Ένας πελάτης που υποστηρίζει μόνο σύνδεση OAuth, όπως οι web συνδέσεις του claude.ai, δεν μπορεί ακόμη να συνδεθεί: χρησιμοποιήστε έναν πελάτη που επιτρέπει τον ορισμό κεφαλίδας.

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	Έλεγχος ενός προσχεδίου διασάφησης: βαθμολογία στα 100, επίπεδο και κάθε πρόβλημα με το πεδίο και την ενέργεια. Δεν διατηρεί το περιεχόμενο του αρχείου εκτός αν ζητηθεί.
list_declaration_types	Τα υποστηριζόμενα συστήματα διασάφησης, με αρχή, περιοχή και αναμενόμενα έγγραφα.
describe_declaration_type	Τα πεδία κεφαλίδας και ειδών ενός τύπου, για τη δημιουργία της εισόδου του check_declaration.
search_hs_codes	Υποψήφιοι κωδικοί της Συνδυασμένης Ονοματολογίας από την περιγραφή ενός προϊόντος, σε οποιαδήποτε από τις 24 γλώσσες της ΕΕ.
describe_hs_code	Αν ένας κωδικός 4 έως 10 ψηφίων υπάρχει στην ισχύουσα ονοματολογία, με την επίσημη διαδρομή και διατύπωσή του.
lookup_import_duty	Εισαγωγικός δασμός της ΕΕ για έναν κωδικό από τα δεδομένα TARIC της Επιτροπής: δασμός τρίτων χωρών, προτιμήσεις για μια καταγωγή, ποσοστώσεις, αντιντάμπινγκ και έλεγχοι.
search_chemical	Μια χημική ουσία με αριθμό CAS, αριθμό CUS ή όνομα στον κατάλογο ECICS της Επιτροπής: ο κωδικός της Συνδυασμένης Ονοματολογίας που δίνεται για κάθε εγγραφή, προς επαλήθευση.
get_quota_balance	Υπόλοιπο δασμολογικής ποσόστωσης της ΕΕ στη βάση QUOTA της Επιτροπής, από τον αύξοντα αριθμό της ή από έναν κωδικό και μια καταγωγή: υπόλοιπο, κατάσταση (ανοιχτή, κρίσιμη, αποκλεισμένη, εξαντλημένη), περίοδος και ώρα ανάγνωσης.
validate_eori	Μορφή ενός αριθμού EORI και η κατάστασή του στο επίσημο μητρώο (Ευρωπαϊκή Επιτροπή, HMRC).
validate_vat	Μορφή ενός αριθμού ΦΠΑ της ΕΕ και η ισχύς του στο VIES, με την καταχωρισμένη επωνυμία όπου δημοσιεύεται.
check_rex	Μορφή αριθμού REX εγγεγραμμένου εξαγωγέα και κατάστασή του στη βάση REX της Επιτροπής (έγκυρος, ανακληθείς ή άγνωστος), με τις ημερομηνίες.
screen_sanctions	Μια επιχείρηση, ένα πρόσωπο ή ένα πλοίο έναντι των καταλόγων κυρώσεων της ΕΕ, του ΟΗΕ, του Ηνωμένου Βασιλείου και των ΗΠΑ, που ενημερώνονται καθημερινά: κάθε αντιστοιχία με τη βαθμολογία της, ισχυρή ή μερική.
search_aeo	Αναζήτηση στη βάση δεδομένων της Επιτροπής για τους Εγκεκριμένους Οικονομικούς Φορείς με βάση την επωνυμία της εταιρείας.

Οι κωδικοί ονοματολογίας είναι προτάσεις που προκύπτουν από το κείμενο της ονοματολογίας. Μόνο ο δηλούντας ή μια δεσμευτική πληροφορία για την ταξινόμηση από το τελωνείο μπορεί να επιβεβαιώσει μια ταξινόμηση.
Οι δασμοί είναι ενδεικτικοί: οι όροι, οι εξαιρέσεις χωρών και οι εξαντλημένες ποσοστώσεις δεν αξιολογούνται. Κάθε απάντηση φέρει την ημερομηνία αναφοράς του αποσπάσματος TARIC, που ανανεώνεται μηνιαία.
Ένα μητρώο που δεν απαντά αναφέρεται ως μη διαθέσιμο, ποτέ ως μη έγκυρος αριθμός. Τίποτα δεν στέλνεται ποτέ στο τελωνείο.

Συλλογή Postman

Η συλλογή δημιουργείται από την προδιαγραφή OpenAPI, άρα συμφωνεί πάντα με αυτήν: ένα αίτημα ανά διαδρομή, ομαδοποιημένα ανά ετικέτα, με σκελετό σώματος για κάθε POST. Εισαγάγετέ την στο Postman, συμπληρώστε τη μεταβλητή apiKey (φυλάσσεται ως μυστικό) και τα αιτήματα είναι έτοιμα προς αποστολή.

Λήψη της συλλογής

Όριο

Κάθε κλειδί διαθέτει 500 ελέγχους ανά ημερολογιακή ημέρα UTC. Η τρέχουσα κατάσταση ταξιδεύει με κάθε ταυτοποιημένη απόκριση, οπότε δεν χρειάζεστε ποτέ επιπλέον κλήση για να τη μάθετε.

Οι απορριφθείσες κλήσεις μετρούν επίσης: ένας πελάτης που επαναλαμβάνει άκυρα αιτήματα περιορίζει τον εαυτό του. Το όριο ορίζεται ανά κλειδί — γράψτε μας αν χρειάζεστε περισσότερα.

Απόκριση

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

Σφάλματα

Τα μηνύματα σφάλματος είναι μόνο στα αγγλικά: πρόκειται για μηνύματα πρωτοκόλλου, που απευθύνονται σε προγραμματιστές. Μεταφράζεται μόνο το ουσιαστικό περιεχόμενο.

Κάθε απόκριση φέρει ένα αναγνωριστικό αιτήματος, που επαναλαμβάνεται στο σώμα. Αναφέρετέ το όταν επικοινωνείτε μαζί μας — μας οδηγεί κατευθείαν στην κλήση.

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

Κατάσταση	code	Σημασία
400	invalid_json	Το σώμα δεν είναι έγκυρο JSON.
422	invalid_request	Το JSON είναι έγκυρο αλλά το περιεχόμενό του όχι. Οι λεπτομέρειες υποδεικνύουν το εσφαλμένο πεδίο.
401	missing_credentials	Η κεφαλίδα Authorization λείπει ή είναι κακοσχηματισμένη.
401	invalid_key	Άγνωστο κλειδί.
401	key_revoked	Ανακληθέν κλειδί.
403	account_suspended	Ο λογαριασμός που κατέχει το κλειδί έχει ανασταλεί.
415	unsupported_media_type	Ο τύπος περιεχομένου δεν είναι JSON.
413	payload_too_large	Το σώμα του αιτήματος είναι πολύ μεγάλο.
429	rate_limit_exceeded	Το ημερήσιο όριο εξαντλήθηκε. Δείτε την κεφαλίδα Retry-After.
500	internal_error	Σφάλμα από τη δική μας πλευρά. Δοκιμάστε ξανά και αναφέρετέ το με το αναγνωριστικό αιτήματος.

Δεδομένα και διατήρηση

Οι φάκελοι που αποστέλλονται μέσω του API είναι δεδομένα των πελατών σας: κρατάμε όσο το δυνατόν λιγότερα, και έχετε έναν διακόπτη για να μην κρατηθεί τίποτα.

Στείλτε «store» ως false και δεν θα γραφτεί κανένα περιεχόμενο φακέλου: μένουν μόνο η βαθμολογία και οι κωδικοί αποκλίσεων.
Διαφορετικά, το περιεχόμενο των φακέλων διαγράφεται μετά από 30 ημέρες.
Η ανάκληση ενός κλειδιού διαγράφει αμέσως το περιεχόμενο των φακέλων που υποβλήθηκαν με αυτό.
Η επεξεργασία γίνεται στη Φρανκφούρτη και η βάση δεδομένων φιλοξενείται στην Ευρωπαϊκή Ένωση.
Κανένα αρχείο δεν μεταφορτώνεται μέσω του API: δηλώνετε μόνο ποια δικαιολογητικά κατέχετε.

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

Τι δεν είναι αυτό το API

Ο έλεγχος βοηθά στην προετοιμασία. Δεν συνιστά επικύρωση από την τελωνειακή διοίκηση, δεν υποβάλλει τίποτα και δεν υποκαθιστά τις κανονιστικές υποχρεώσεις που ισχύουν για την πράξη σας.

Οι τελωνειακοί κωδικοί ελέγχονται ως προς τη μορφή, την ύπαρξη στην ονοματολογία και, στις εισαγωγές στην ΕΕ, έναντι των μέτρων TARIC της καταγωγής τους, ποτέ ως προς την κατάταξη του εμπορεύματος: ένας υπαρκτός κωδικός παραμένει κωδικός προς επαλήθευση. Τα μέτρα TARIC είναι ενδεικτικά (μηνιαία εξαγωγή της Ευρωπαϊκής Επιτροπής): εξαιρέσεις χωρών, εξαντλημένες ποσοστώσεις και δασμοί υπό όρους δεν αξιολογούνται.