Τεκμηρίωση REST API

Τεκμηρίωση VIES API REST

Εισαγωγή

Το API που παρέχεται από εμάς χρησιμοποιεί το τυπικό πρωτόκολλο HTTP. Όλες οι συναρτήσεις API χρησιμοποιούν τη μέθοδο HTTP GET. Κάθε κλήση συνάρτησης απαιτεί εξουσιοδότηση ερωτήματος. Τα δεδομένα για εξουσιοδότηση ερωτήματος αποστέλλονται στην κεφαλίδα HTTP.

Υπηρεσία παραγωγής

Απαιτείται η εγγραφή μιας οντότητας που θέλει να χρησιμοποιήσει τη λειτουργικότητα του συστήματος viesapi.eu. Για να το κάνετε αυτό, μεταβείτε στο Εγγραφή σελίδα και συμπληρώστε την κατάλληλη φόρμα. Απαραίτητη προϋπόθεση για τη χρήση του συστήματος viesapi.eu είναι η αποδοχή του Όροι χρήσης. Συμπληρώνοντας σωστά τη φόρμα και κάνοντας κλικ στο Κανω ΕΓΓΡΑΦΗ κουμπί θα δημιουργήσει λογαριασμό στο σύστημα viesapi.eu και την αυτόματη ενεργοποίησή του.

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

Διεύθυνση υπηρεσίας παραγωγής: https://viesapi.eu/api

Υπηρεσία δοκιμής

Η πλήρης λειτουργικότητα όλων των κοινόχρηστων βιβλιοθηκών μπορεί να ελεγχθεί χρησιμοποιώντας το κοινόχρηστο Test VIES API. Χρησιμοποιώντας το δοκιμαστικό API, μπορείτε να ελέγξετε όλες τις λειτουργίες που προσφέρονται σε προγράμματα επί πληρωμή χωρίς την ανάγκη δημιουργίας λογαριασμού.

Διεύθυνση υπηρεσίας δοκιμής: https://viesapi.eu/api-test

Ορισμός διεπαφής API

Ένας λεπτομερής ορισμός του API είναι διαθέσιμος σε μορφή συμβατή με OpenAPI και μπορεί να ληφθεί ως αρχείο YAML εδώ.

Το API είναι επίσης διαθέσιμο ως διεπαφή πελάτη Swagger UI.

Εκτέλεση του ερωτήματος

Ένα παράδειγμα υποβολής ερωτήματος στον ιστότοπο δοκιμής:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Host: viesapi.eu:443
Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version
Accept: mime_type

Οπου:

  • api_key_id – Αναγνωριστικό κλειδιού API (στο περιβάλλον παραγωγής, η τιμή του αναγνωριστικού που δημιουργήθηκε κατά την εγγραφή, στο περιβάλλον δοκιμής, η τιμή του test_id),
  • unix_timestamp – η τρέχουσα ώρα με τη μορφή αριθμού δευτερολέπτων από το λεγόμενο unix εποχ,
  • random_str – τυχαία συμβολοσειρά, διαφορετική για κάθε ερώτημα (ελάχ. 8 χαρακτήρες, μέγ. 16 χαρακτήρες),
  • b64_calculated_mac_value – υπολογισμένο HMAC (χρησιμοποιώντας ένα API key, αξία test_key στο περιβάλλον δοκιμής),
  • client_version – έκδοση πελάτη (στις βιβλιοθήκες μας είναι η έκδοση της βιβλιοθήκης API μας, π.χ. 1.2.3),
  • platform_name – το όνομα της πλατφόρμας πελάτη API (στις βιβλιοθήκες μας είναι το όνομα της γλώσσας της βιβλιοθήκης, π.χ. JAVA, PHP, .NET, Python),
  • platform_version – Έκδοση πλατφόρμας πελάτη API (στις βιβλιοθήκες μας είναι η έκδοση περιβάλλοντος βιβλιοθήκης, π.χ. 17 για JAVA ή 7.4 για PHP),
  • mime_type – Όνομα τύπου MIME στο οποίο πρέπει να επιστραφεί η απάντηση, υποστηρίζονται δύο τύποι: text/xml και application/json, εάν το αίτημα δεν περιέχει κεφαλίδα Αποδοχή, η XML επιστρέφεται από προεπιλογή.

Αίτημα ελέγχου ταυτότητας

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

Κάθε ερώτημα στον ιστότοπό μας πρέπει να επαληθεύεται χρησιμοποιώντας μία από τις δύο διαθέσιμες μεθόδους.

Μέθοδος 1 – HMAC (συνιστάται)

Προδιαγραφή της χρησιμοποιούμενης μεθόδου εξουσιοδότησης: Έλεγχος ταυτότητας HTTP: Έλεγχος ταυτότητας πρόσβασης MAC. Η εξουσιοδότηση συνίσταται στον υπολογισμό του HMAC SHA256 από μια σωστά προετοιμασμένη συμβολοσειρά και στην αποστολή του αποτελέσματος στην κεφαλίδα HTTP.

Παράδειγμα

Η συμβολοσειρά εισόδου στη συνάρτηση HMAC είναι:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Οπου:

  • ts – η τρέχουσα ώρα με τη μορφή αριθμού δευτερολέπτων από το λεγόμενο unix εποχ, θα πρέπει πάντα να παρέχετε τον τρέχοντα χρόνο εκτέλεσης του ερωτήματος (ανοχή διακομιστή +/- 10 λεπτά σε σχέση με την τρέχουσα ώρα),
  • nonce – τυχαία συμβολοσειρά, διαφορετική για κάθε ερώτημα (ελάχ. 8 χαρακτήρες, μέγ. 16 χαρακτήρες),
  • method – Όνομα μεθόδου HTTP (πάντα GET),
  • path – Διαδρομή URL του ερωτήματος που θα εκτελεστεί,
  • host – Όνομα διακομιστή VIES API (πάντα viesapi.eu),
  • port – Αριθμός θύρας διακομιστή VIES API (πάντα 443),
  • ’\n’ – χαρακτήρας νέας γραμμής (κωδικός ASCII 10, 0x0A).

Για το ερώτημα για τον ΑΦΜ PL7171642051 που στάλθηκε στην υπηρεσία δοκιμών στις 25-11-2019 00:00:00 UTC, η συμβολοσειρά εισόδου στη συνάρτηση HMAC θα μοιάζει με αυτό:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Μπορείτε να λάβετε το αρχείο συμβολοσειράς εισόδου για αυτό το παράδειγμα εδώ.

Από την προετοιμασμένη συμβολοσειρά, υπολογίζουμε το HMAC SHA256, ως κωδικό πρόσβασης HMAC που δίνουμε API key, δηλαδή στην περίπτωση του δοκιμαστικού API, η τιμή του test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Η συνάρτηση HMAC SHA256 επιστρέφει 32 δυαδικά byte (εμφανίζονται παραπάνω ως α hex συμβολοσειρά για αναγνωσιμότητα). Λήψη αρχείου με δυαδική τιμή εδώ.

Η δυαδική τιμή του υπολογισμένου HMAC θα πρέπει να κωδικοποιηθεί με τον αλγόριθμο Base64, παίρνουμε:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Αυτή η τιμή πρέπει να αποσταλεί ως τιμή MAC στην κεφαλίδα με δεδομένα για εξουσιοδότηση. Τελικά:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="

Σε μηχάνημα Linux, η απαιτούμενη τιμή MAC μπορεί να υπολογιστεί σε ένα βήμα χρησιμοποιώντας αυτήν την εντολή:

$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64

Μέθοδος 2 – Βασικός έλεγχος ταυτότητας

Προδιαγραφή αυτής της μεθόδου εξουσιοδότησης που χρησιμοποιείται: Έλεγχος ταυτότητας HTTP: Βασικός έλεγχος ταυτότητας.

Παράδειγμα 1

Η συμβολοσειρά εισόδου στη συνάρτηση Base64 είναι:

str = key_id + ':' + key

Οπου:

  • key_id – Αναγνωριστικό κλειδιού API (στην περίπτωση περιβάλλοντος δοκιμής, test_id σειρά),
  • key – Κλειδί API (στην περίπτωση περιβάλλοντος δοκιμής, συμβολοσειρά test_key).

Για το περιβάλλον δοκιμής, η συμβολοσειρά εισόδου για τη συνάρτηση Base64 θα είναι:

str = "test_id:test_key"

Μετά την εφαρμογή της συνάρτησης Base64, έχουμε:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Αυτή η τιμή πρέπει να αποσταλεί ως Βασική τιμή στην κεφαλίδα με δεδομένα για εξουσιοδότηση. Τελικά:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Παράδειγμα 2

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

https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051

Οπου:

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

Το αναγνωριστικό κλειδιού και το κλειδί δημιουργούνται από τον χρήστη αφού συνδεθεί στο λογαριασμό του στο viesapi.eu πύλη (API keys αυτί). μικρόεε το τεκμηρίωση σελίδα για περισσότερες πληροφορίες σχετικά με το αναγνωριστικό και τη δημιουργία κλειδιών.

Απάντηση

Εάν το αίτημα χειριστεί σωστά, δημιουργείται η ακόλουθη απάντηση:

Λεπτομερής περιγραφή των επιστρεφόμενων χαρακτηριστικών:

  • uid – μοναδικό αναγνωριστικό ερωτήματος που δημιουργείται από το viesapi.eu,
  • countryCode – κωδικός χώρας στην οποία είναι εγγεγραμμένη η εταιρεία που σχετίζεται με τον ΑΦΜ της ΕΕ που παρέχεται στο αίτημα,
  • vatNumber – Αριθμός ΦΠΑ ΕΕ της επαληθευμένης εταιρείας που παρέχεται στο ερώτημα,
  • valid – απάντηση από την υπηρεσία VIES, που ενημερώνει για το τρέχον καθεστώς ΦΠΑ ΕΕ της ελεγχόμενης οντότητας:
    • true – ο ΑΦΜ ΕΕ που παρέχεται στο αίτημα είναι έγκυρος,
    • false – ο αριθμός ΦΠΑ ΕΕ που παρέχεται στο αίτημα δεν είναι έγκυρος,
  • traderName – την εμπορική επωνυμία της εταιρείας,
  • traderCompanyType – επέστρεφε πάντα μια σειρά χαρακτήρων '-',
  • traderAddress – διεύθυνση της εταιρείας στην οποία είναι εγγεγραμμένη η εταιρεία,
  • id – μοναδικό αναγνωριστικό ερωτήματος που δημιουργείται από το σύστημα VIES
  • date – ημερομηνία εκτέλεσης ερωτήματος
  • source – πηγή δεδομένων, πάντα: http://ec.europa.eu

Απόκριση σφάλματος

Σε περίπτωση οποιουδήποτε σφάλματος που σχετίζεται με τον χειρισμό του αιτήματος, επιστρέφεται το ακόλουθο μήνυμα σφάλματος:

Λάθος

Λεπτομερής περιγραφή των επιστρεφόμενων χαρακτηριστικών:

  • code – μοναδικός κωδικός σφάλματος για αυτόματο χειρισμό σφαλμάτων,
  • description – περιγραφή σφαλμάτων που μπορεί να αναχαιτιστεί από τον άνθρωπο,
  • details - Μή λεπτομερής περιγραφή σφάλματος (προαιρετικό),

Κωδικοί σφαλμάτων

Ο παρακάτω πίνακας παραθέτει όλα τα πιθανά σφάλματα που επιστρέφονται από τα REST API και τις βιβλιοθήκες προγραμματισμού:

Κωδικός σφάλματος Μήνυμα σφάλματος
8 Μη έγκυρη μορφή αιτήματος
10 Μη έγκυρη διαδρομή API
11 Σφάλμα εσωτερικού σέρβις
22 Ο ΑΦΜ ΕΕ δεν είναι έγκυρος
23 Αποτυχία λήψης δεδομένων από το σύστημα VIES
26 Αυτή η λειτουργία δεν είναι διαθέσιμη στο τρέχον επιλεγμένο σχέδιο
27 Αυτή η λειτουργία δεν υποστηρίζει αυτήν τη λειτουργία αναζήτησης
33 Η αναζήτηση των δεδομένων δεδομένων δεν είναι δυνατή στη δοκιμαστική λειτουργία
35 Δεν απαιτείται εξουσιοδότηση ερωτήματος πρόσβασης
36 Η υπηρεσία δεν είναι διαθέσιμη προσωρινά λόγω προγραμματισμένων τεχνικών εργασιών
43 Δεν ήταν δυνατή η ανάκτηση του αριθμού των ερωτημάτων χρήστη για τον τρέχοντα μήνα
54 Εσφαλμένη ημερομηνία ή ώρα στον υπολογιστή ή το σύστημα του χρήστη
55 Μη έγκυρη τιμή συμβολοσειράς MAC στην κεφαλίδα με διαπιστευτήρια ερωτήματος
57 Μη έγκυρη τιμή κλειδιού στην κεφαλίδα με διαπιστευτήρια ερωτήματος
58 Έχει συμπληρωθεί ο μέγιστος αριθμός ταυτόχρονων ερωτημάτων για αυτό το κράτος μέλος
59 Η αίτηση στο κράτος μέλος δεν απαντά ή δεν είναι διαθέσιμη
101 Ο αριθμός IP σύνδεσης δεν ταιριάζει με τον αριθμό IP που έχει εκχωρηθεί στο κλειδί API
102 Το κλειδί API είναι αποκλεισμένο
103 Μη έγκυρο κλειδί API
104 Έχει συμπληρωθεί ο μέγιστος αριθμός διαθέσιμων ερωτημάτων για το επιλεγμένο σχέδιο
105 Ο λογαριασμός αποκλείστηκε ή διαγράφηκε
106 Μη έγκυρος τύπος λογαριασμού
107 Ο προπληρωμένος λογαριασμός δεν έχει πληρωθεί
108 Μη έγκυρο αναγνωριστικό κλειδιού API
201 Αποτυχία σύνδεσης με την υπηρεσία VIES API
202 Η απόκριση υπηρεσίας VIES API έχει μη έγκυρη μορφή
203 Μη έγκυρος τύπος αριθμού
204 Το NIP δεν είναι έγκυρο
205 Ο ΑΦΜ ΕΕ δεν είναι έγκυρος
206 Η συνάρτηση δημιούργησε μια εξαίρεση
207 Η ημερομηνία έχει μη έγκυρη μορφή
208 Μη έγκυρη παράμετρος εισαγωγής