Έλεγχος ταυτότητας και αποκρίσεις API

Χρησιμοποιήστε διαπιστευτήρια API

Στείλτε αιτήματα v3 μέσω HTTPS προς https://api.multitel.net. Κάθε τελικό σημείο σε αυτόν τον οδηγό απαιτεί έλεγχο ταυτότητας. Διατηρήστε τα διαπιστευτήρια στον διακομιστή σας και μην τα τοποθετείτε ποτέ σε JavaScript προγράμματος περιήγησης, δημόσιες σελίδες, στιγμιότυπα οθόνης ή έλεγχο πηγαίου κώδικα.

Χρησιμοποιήστε μία από αυτές τις μορφές διαπιστευτηρίων:

HTTP Basic με το όνομα χρήστη και τον κωδικό πρόσβασης API που έχουν διαμορφωθεί για τον λογαριασμό σας MultiTEL.
Bearer διακριτικό σε μια κεφαλίδα Authorization: Bearer YOUR_API_TOKEN, για έναν ενεργοποιημένο λογαριασμό API που έχει διαμορφωθεί για έλεγχο ταυτότητας με διακριτικό. Τα αιτήματα με διακριτικό γίνονται δεκτά μόνο από διευθύνσεις που επιτρέπονται για αυτόν τον λογαριασμό API.

Εάν έχει διαμορφωθεί λίστα επιτρεπόμενων IP για τον λογαριασμό σας API, στείλτε όλα τα αιτήματα από επιτρεπόμενες διευθύνσεις.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

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

Χειριστείτε τα σφάλματα ελέγχου ταυτότητας

Τα σφάλματα ελέγχου ταυτότητας αποστέλλονται με κατάσταση HTTP 401. Το σώμα χρησιμοποιεί τον τυπικό φάκελο, με status.code ορισμένο σε 401 και μια κενή συμβολοσειρά ως response.

Χωρίς διαπιστευτήρια: status.msg είναι Username and password are required, και η απόκριση περιλαμβάνει μια πρόκληση ελέγχου ταυτότητας Basic.
Bearer διακριτικό απορρίφθηκε: εάν η κεφαλίδα Authorization χρησιμοποιεί το σχήμα Bearer και το διακριτικό είναι άγνωστο, απενεργοποιημένο ή δεν επιτρέπεται από τη διεύθυνσή σας, status.msg είναι Invalid bearer token. Δεν δοκιμάζονται άλλα διαπιστευτήρια όταν υπάρχει κεφαλίδα Bearer.
Μη έγκυρα διαπιστευτήρια Basic: status.msg ξεκινά με A valid username and password pair are required., και η απόκριση περιλαμβάνει μια πρόκληση ελέγχου ταυτότητας Basic. Το μήνυμα μπορεί να περιέχει περισσότερο διαγνωστικό κείμενο, οπότε μην το αναλύετε.

Μην επαναλαμβάνετε αυτόματα με τα ίδια διαπιστευτήρια. Πολλές αποτυχημένες προσπάθειες από μία διεύθυνση σε σύντομο χρονικό διάστημα μπορούν να προκαλέσουν τον αποκλεισμό περαιτέρω αιτημάτων από αυτή τη διεύθυνση.

Διαβάστε το σώμα της απόκρισης

Τα περισσότερα τελικά σημεία v3, συμπεριλαμβανομένων των getcountries, getstates, getareas και other, επιστρέφουν JSON σε αυτόν τον φάκελο:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

Αυτή είναι μια ενδεικτική απόκριση λίστας χωρών, όχι δήλωση του τρέχοντος αποθέματος ή των δυνατοτήτων.

Πεδίο	Σημασία
`status.code`	Ο κωδικός αποτελέσματος API, για παράδειγμα `200`, `401`, `404` ή `500`.
`status.msg`	Ένα μήνυμα αναγνώσιμο από άνθρωπο. Μπορεί να είναι κενό. Βασίστε τη λογική του προγράμματος σε `status.code`, όχι στο κείμενο του μηνύματος.
`status.results`	Ο αριθμός των καταχωρίσεων. Για τα τελικά σημεία ανακάλυψης που τεκμηριώνονται εδώ, υπάρχει όταν `response` είναι λίστα JSON, συμπεριλαμβανομένης μιας κενής λίστας (`0`). Απουσιάζει όταν `response` είναι κενή συμβολοσειρά ή `null`. Άλλα ωφέλιμα φορτία τελικών σημείων μπορούν να αναφέρουν τον αριθμό διαφορετικά· ακολουθήστε τη δική τους τεκμηρίωση απόκρισης.
`response`	Το ωφέλιμο φορτίο του τελικού σημείου. Ο τύπος του εξαρτάται από το τελικό σημείο και το αποτέλεσμα. Σε σφάλματα είναι κενή συμβολοσειρά.

Μια απόκριση σφάλματος μοιάζει με αυτό:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Εάν μια απόκριση δεν μπορεί να κωδικοποιηθεί, το σώμα έχει status.code 500, status.msg Response encoding error, και ένα κενό αντικείμενο ως response.

Το τελικό σημείο παλαιού τύπου GET /v3/countries επιστρέφει {"code": 200, "data": [...]} αντ' αυτού. Ελέγξτε την τεκμηριωμένη απόκριση κάθε τελικού σημείου. Εάν ένα σώμα δεν είναι έγκυρο JSON, για παράδειγμα μετά από απροσδόκητη αποτυχία διακομιστή, αντιμετωπίστε το αίτημα ως αποτυχημένο και επαναλάβετε αργότερα.

Κωδικοί αποτελέσματος API και κατάσταση HTTP

status.code είναι ο κωδικός αποτελέσματος API. Δεν είναι η κατάσταση HTTP. Τα σφάλματα ελέγχου ταυτότητας αποστέλλονται με HTTP 401. Διαφορετικά, τα τελικά σημεία ανακάλυψης αναφέρουν αποτελέσματα όπως 404 και 500 μόνο σε status.code και δεν ορίζουν αντίστοιχη κατάσταση HTTP. Ένα αποτέλεσμα μη εύρεσης ή έλλειψης παραμέτρου μπορεί επομένως να φτάσει με επιτυχή κατάσταση HTTP. Ελέγχετε πάντα status.code πριν χρησιμοποιήσετε response.

Ο κωδικός αποτελέσματος 500 με το μήνυμα ISO Code parameter is required σημαίνει ότι λείπει μια απαιτούμενη παράμετρος. Διορθώστε το αίτημα αντί να το αντιμετωπίσετε ως διακοπή διακομιστή.

Ακολουθήστε το next_function

Τα αποτελέσματα ανακάλυψης περιλαμβάνουν next_function. Είναι μια σχετική διαδρομή χωρίς αρχική κάθετο, μερικές φορές με συμβολοσειρά ερωτήματος, όπως v3/getareas/US ή v3/getareas/US?state=NY. Προσθέστε ως πρόθεμα https://api.multitel.net/ για να δημιουργήσετε το επόμενο αίτημα και πραγματοποιήστε έλεγχο ταυτότητας για αυτό το αίτημα με τον ίδιο τρόπο. Τα προαιρετικά φίλτρα που στείλατε, όπως pid, δεν μεταφέρονται σε next_function. Προσθέστε τα ξανά εάν τα χρειάζεστε.

Προαιρετικός επιλογέας αποθέματος (pid)

getcountries, getstates και getareas δέχονται μια προαιρετική παράμετρο ερωτήματος pid που περιορίζει τα αποτελέσματα σε μία πηγή αποθέματος. Χρησιμοποιήστε την μόνο με τιμή που παρέχεται από MultiTEL, είτε στην αριθμητική της μορφή είτε στην 32-χαρακτήρων δεκαεξαδική της μορφή. Παραλείψτε την για κανονική χρήση. Στείλτε pid στη συμβολοσειρά ερωτήματος. Εάν το τελικό σημείο δεν αναγνωρίζει ή δεν αποδέχεται την τιμή, την αγνοεί χωρίς σφάλμα και το αίτημα συμπεριφέρεται σαν pid να είχε παραλειφθεί.

Διαχωρίστε την ανακάλυψη από τις παραγγελίες

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

Για αγορές, αναθέσεις, μηνύματα, αποστολές φαξ και άλλες ενέργειες, ακολουθήστε τους κανόνες επανάληψης του ίδιου του τελικού σημείου. Εάν μια ενέργεια λήξει χρονικά μετά την υποβολή, ελέγξτε την κατάστασή της ή τα αρχεία του λογαριασμού σας πριν την επαναλάβετε. Μια χαμένη απόκριση δεν αποδεικνύει ότι η ενέργεια απέτυχε.