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

Εισαγωγή

Το 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
Διοργανωτής: viesapi.eu:443
Εξουσιοδότηση: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPICclient/client_version platform_name/platform_version

Οπου:

  • 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).

Όλες οι απαντήσεις που επιστρέφονται από τον ιστότοπο είναι σε μορφή XML.

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

Προδιαγραφή της χρησιμοποιούμενης μεθόδου εξουσιοδότησης: Έλεγχος ταυτότητας 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