Επισκόπηση Api από την MerchantPro

Το MerchantPro API είναι ένα REST API. Για να χρησιμοποιήσετε τους πόρους API χρειάζεστε έναν λογαριασμό VIP, εγκατεστημένο πιστοποιητικό HTTPS και θα πρέπει να ενεργοποιήσετε το κλειδί API σας στη σελίδα Πρόσβαση API . Δείτε τις παρακάτω ενότητες για περισσότερες πληροφορίες σχετικά με τον τρόπο χρήσης του.

Σύμβαση
Εκδοχή
Σύνδεση
Αποστολή στοιχείων
Μορφή απόκρισης
Ατομικοί πόροι
Μορφή συλλογής(λίστα πόρων
Ρήματα HTTP
Παράμετροι φίλτρου
Μεταδεδομένα
Σελιδοποίηση
Κωδικοί κατάστασης HTTP
Απαντήσεις σφάλματος
Πλευρική φόρτωση
Όρια κλειδιού API

Σύμβαση

Τα τελικά σημεία API περιγράφονται με μέθοδο HTTP και διαδρομή. Παράδειγμα:

GET /api/v2/products HTTP/1.1

Προσθέστε τη διαδρομή προς τη διεύθυνση URL του τομέα σας (συμπεριλαμβανομένου του πρωτοκόλλου https) για να λάβετε το τελικό URL. Για παράδειγμα, εάν ο τομέας σας είναι example.com, τότε το τελικό URL του τελικού σημείου θα είναι:

https://www.example.com/api/v2/products

Τα άγκιστρα ,, {}στις διευθύνσεις URL υποδεικνύουν μια τιμή που πρέπει να αντικατασταθεί:

GET /api/v2/products/{id} HTTP/1.1

Όλες οι ιδιότητες JSON του API, οι διευθύνσεις URL καθώς και οι παράμετροι στη διεύθυνση URL είναι πεζοί.

εκδοχή

Το MerchantPro API χρησιμοποιεί ένα σύστημα εκδόσεων για να προσαρμόσει τις αναβαθμίσεις για να εξασφαλίσει συμβατότητα με τις τρέχουσες παραλλαγές

Η τρέχουσα, δημόσια διαθέσιμη έκδοση είναι v2, όπως υποδεικνύει το πρόθεμα διαδρομής /api/v2/.

Σύνδεση

Για να αποκτήσετε πρόσβαση στο MerchantPro API θα πρέπει να συνδεθείτε χρησιμοποιώντας βασικό έλεγχο ταυτότητας με βάση το API Key και το Api Secret. Ο έλεγχος ταυτότητας ενός αιτήματος API περιλαμβάνει την αποστολή μιας κεφαλίδας εξουσιοδότησης. Για να συνδεθείτε πρέπει να ακολουθήσετε τα παρακάτω βήματα:

Συνδυάστε το κλειδί API και το Api Secret στην ακόλουθη μορφή κλειδιού: κωδικός πρόσβασης
Εφαρμόστε base64_encode στην προκύπτουσα συμβολοσειρά, π.χ. a2V5OnNlY3JldA ==
Περιλαμβάνει τη βασική κεφαλίδα εξουσιοδότησης HTTP

Authorization: Basic {base64-encoded-string}

Authorization: Basic a2V5OnBhc3M=

Θα επιστρέψει μη έγκυρος έλεγχος ταυτότητας διαπιστευτηρίου και θα επιστρέψουν 401 Unauthorizedεπαναλαμβανόμενες προσπάθειες 403 Forbidden.

Αποστολή στοιχείων

Η πρόσβαση στο API γίνεται στον τομέα του καταστήματός σας, βάσει HTTPS. Όλα τα δεδομένα που αποστέλλονται είναι σε μορφή JSON.

Πρέπει να στείλετε την κεφαλίδα Accept: application/jsonγια να επιβεβαιώσετε ότι η εφαρμογή σας αναμένει απόκριση σε μορφή JSON από το API.

Είναι απαραίτητο να στείλετε αιτήματα POST ή PUT συνοδευόμενα από την κεφαλίδα Content-Type: application/jsonκαι το περιεχόμενο που στάλθηκε πρέπει να έχει έγκυρη μορφή JSON.

Μορφή απόκρισης

Το API αποκρίνεται με περιεχόμενο σε μορφή JSON, που αντιπροσωπεύεται από συμβολοσειρές, αριθμούς, αντικείμενα, πίνακες, τιμές Boolean ή null.

Το MerchantPro API θα επιστρέψει τους κωδικούς HTTP 200 και 300 για επιτυχημένες απαντήσεις και για σφάλματα θα επιστραφούν οι κωδικοί HTTP 400 και 500.

Γενικά, η απόκριση API μπορεί να περιέχει τα ακόλουθα:

Σφάλμα (συνοδεύεται από κωδικό και μήνυμα σφάλματος)
Δεδομένα σε μεμονωμένη μορφή πόρων
Δεδομένα σε μορφή συλλογής (λίστα πόρων)

Ατομικοί πόροι

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

Μορφή συλλογής (λίστα πόρων)

Όταν αποκτάτε πρόσβαση σε μια λίστα πόρων, θα επιστρέφεται ένα σύνολο περιλήψεων για κάθε μεμονωμένο πόρο. Στη συντριπτική πλειονότητα των περιπτώσεων, η λίστα περιέχει αρκετές πληροφορίες που επιτρέπουν τη χρήση σε άλλη εφαρμογή χωρίς την ανάγκη μεμονωμένης κλήσης σε κάθε πόρο.

Ρήματα HTTP

Ακολουθεί μια σύνοψη των ρήματος HTTP που μπορείτε να χρησιμοποιήσετε και ο σκοπός κάθε:

Ρήμα

Σκοπός

Παράδειγμα

GET

Χρησιμοποιείται για εξαγωγή δεδομένων

GET / προϊόντα sau GET / προϊόντα / 123

POST

Χρησιμοποιείται για τη δημιουργία νέων πόρων

POST / προϊόντα

PUT

Χρησιμοποιείται για την ενημέρωση υπαρχόντων πόρων με μερικά δεδομένα

PUT / προϊόντα / 123

DELETE

Χρησιμοποιείται για τη διαγραφή πόρων

ΔΙΑΓΡΑΦΗ / προϊόντα / 123

Παράμετροι φίλτρου

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

Μεταδεδομένα

Πληροφορίες για τον συνολικό αριθμό πόρων που πληρούν τα κριτήρια φιλτραρίσματος παρέχονται στα μεταδεδομένα, μαζί με τις απαραίτητες πληροφορίες σχετικά με την ύπαρξη πρόσθετων πόρων και τις διευθύνσεις URL πρόσβασης (όπου απαιτείται)

"meta": {
  "count": {
    "total": 8219,
    "current": 20,
    "start": 0,
    "limit": 20
  },
  "links": {
    "prev": null,
    "current": "/api/v2/products",
    "next": "/api/v2/products?start=20&limit=20"
  },
  "has_more": true
}

Σελιδοποίηση

Η σελιδοποίηση ορισμένων πόρων συλλογής πραγματοποιείται αυτόματα. Από προεπιλογή, τα περισσότερα τελικά σημεία επιστρέφουν 20 εγγραφές ανά σελίδα. Μπορείτε να αλλάξετε τον αριθμό των καταχωρήσεων ανά σελίδα χρησιμοποιώντας την παράμετρο ορίου (ex όριο = 50), αλλά δεν μπορείτε να υπερβείτε τις 100 καταχωρήσεις ανά σελίδα στις περισσότερες περιπτώσεις.

Όταν η απάντηση υπερβεί το όριο εγγραφής ανά σελίδα, μπορείτε να πλοηγηθείτε σε διαδοχικές σελίδες χρησιμοποιώντας την παράμετρο έναρξης (ex start = 20)

Η απόκριση περιλαμβάνει τα επόμενα και τα προηγούμενα χαρακτηριστικά για τη διευκόλυνση της πλοήγησης.

"meta": {
  ...
  "links": {
    "prev": "/api/v2/products",
    "current": "/api/v2/products?start=20&limit=20",
    "next": "/api/v2/products?start=40&limit=20"
  }
}

Διακόπτεται η περιήγηση σε διαδοχικές σελίδες όταν το επόμενο χαρακτηριστικό είναι μηδενικό.

Κωδικοί κατάστασης HTTP

Οι κωδικοί κατάστασης HTTP που επιστρέφει το API είναι σημαντικοί και σας επιτρέπουν να ερμηνεύσετε καλύτερα την απόκριση που λάβατε. Παρακάτω θα βρείτε μια περίληψη αυτών:

Κώδικας

Έννοια

200

Βρέθηκε και επέστρεψε

201

Δημιουργήθηκε πόρος

204

Ο πόρος διαγράφηκε

400

Κακό αίτημα

401

Ανεξουσιοδότητος

403

Απαγορευμένος

404

Ο πόρος δεν βρέθηκε

405

Μη επιτρεπτή μέθοδος

429

Πάρα πολλά αιτήματα

500

Εσωτερικό Σφάλμα Διακομιστή

Απαντήσεις σφάλματος

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

{
  "error": {
    "name": "unauthorized",
    "message": "Authentication required"
  }
}

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

Πλευρική φόρτωση

Στην περίπτωση συλλογών, μπορείτε να ανεβάσετε επιπλέον δεδομένα ως μέρος του ίδιου αιτήματος. Για παράδειγμα, συνήθως ένα αίτημα προς / προϊόντα θα επιστρέψει τα δεδομένα σε μια δομή παρόμοια με αυτήν παρακάτω:

{
  "data": [
    {
      "id": 7,
      "name": "Smartwatch GARMIN Vivoactive",
      ...
    },
    {
      "id": 7,
      "name": "Samsung Galaxy Smartwatch",
      ...
    }
  ]
}

Για να μπορέσετε να εξαγάγετε ορισμένες πρόσθετες πληροφορίες που κανονικά δεν θα μπορούσαν να βρεθούν σε αυτήν την απάντηση (όπως εικόνες ή παραλλαγές), θα ήταν απαραίτητο να υποβάλετε άλλο αίτημα στο / products / 7

Χρησιμοποιώντας την πλευρική φόρτωση, μπορείτε να επιβάλετε τη φόρτωση πρόσθετων δεδομένων στο ίδιο αίτημα. Για αυτό θα πρέπει να προσαρτήσετε την παράμετρο includeμε μια λίστα με πρόσθετες μεταβλητές (διαχωρισμένες με κόμματα) που θέλετε να προσθέσετε.

Παράδειγμα:

... / προϊόντα? include = παραλλαγές ... / παραγγελίες? include = προϊόντα

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

{
  "data": [
    {
      "id": 7,
      "name": "Smartwatch GARMIN Vivoactive",
      "variants": [
        ...
      ],
      ...
    },
    {
      "id": 7,
      "name": "Samsung Galaxy Smartwatch",
      "variants": [
        ...
      ],
      ...
    }
  ]
}

Όρια κλειδιού API

Για τη διατήρηση της βέλτιστης απόδοσης API, το MerchantPro επιβάλλει ορισμένα συνολικά όρια αιτήσεων ανά λεπτό ή / και ώρα. Όταν ξεπεραστούν αυτά τα όρια, τα αιτήματα θα αρχίσουν να αποτυγχάνουν με έναν κωδικό κατάστασης HTTP 429 You have exceeded your request quota for this API. Μπορείτε να αυξήσετε αυτό το όριο κατόπιν αιτήματος επικοινωνώντας μαζί μας στο support@merchantpro.gr .

Τελευταία τροποποίηση: 30 Jun 2021

Ήταν χρήσιμη αυτή η σελίδα;

Χρειάζεστε ακόμα βοήθεια; Επικοινωνήστε μαζί μας