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

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

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

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

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

Επισκόπηση

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

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

Διαδρομή	Ρόλος	Ταυτοποίηση
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. Το διακριτικό εμφανίζεται μία μόνο φορά, κατά τη δημιουργία: διατηρείται μόνο το αποτύπωμά του, οπότε ένα χαμένο κλειδί αντικαθίσταται, ποτέ δεν ανακτάται.

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

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

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

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

Οι τύποι διασάφησης και τα πεδία τους είναι δημόσια, δεν χρειάζεται κλειδί. Αυτή είναι η διαδρομή για να χτίσετε μια φόρμα, να τροφοδοτήσετε μια αντιστοίχιση από το 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": [] } ] }'

Όριο

Κάθε κλειδί διαθέτει 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

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

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