Οδηγός υλοποίησης LINK Mobility REST API SMS
Το LINK Mobility παρέχει μια υπηρεσία για παράδοση μηνυμάτων, μικροπληρωμές και υπηρεσίες που βασίζονται στην τοποθεσία. Η πλατφόρμα λειτουργεί ως διαφανής, λευκής ετικέτας λήψης περιεχομένου και δρομολογητής συναλλαγών μεταξύ των παρόχων υπηρεσιών και των χειριστών.
Το LINK Mobility παρέχει ένα RESTful API που μπορεί να χρησιμοποιηθεί για πρόσβαση σε υπηρεσίες LINK Mobility, όπως η αποστολή SMS. Αυτό το API έχει σχεδιαστεί για να είναι εύκολο στη χρήση και συμβατό με όλες τις σύγχρονες γλώσσες και πλαίσια. Χρησιμοποιώντας τη γλώσσα της επιλογής σας, η εφαρμογή σας μπορεί να χρησιμοποιήσει το Link Mobility REST API για να εφαρμόσει ισχυρές δυνατότητες ανταλλαγής μηνυμάτων και πληρωμής
© LINK Mobility, 10 Μαρτίου 2021
Νομικές Πληροφορίες
Οι πληροφορίες που παρέχονται σε αυτό το έγγραφο αποτελούν αποκλειστική ιδιοκτησία και πνευματικά δικαιώματα της Netsize. Είναι εμπιστευτικό και προορίζεται για αυστηρά ενημερωτική χρήση. Δεν είναι δεσμευτικό και ενδέχεται να υπόκειται σε αλλαγές χωρίς προειδοποίηση. Οποιαδήποτε μη εξουσιοδοτημένη αποκάλυψη ή χρήση θα θεωρείται παράνομη.
Το Netsize™ και το linkmobility™ προστατεύονται από τη γαλλική, την ΕΟΚ και τη διεθνή νομοθεσία περί πνευματικής ιδιοκτησίας.
Όλα τα άλλα εμπορικά σήματα που αναφέρονται αποτελούν αποκλειστική ιδιοκτησία των αντίστοιχων κατόχων τους.
Τίποτα που περιέχεται στο παρόν δεν θα ερμηνεύεται ότι παρέχει άδεια ή δικαίωμα βάσει ευρεσιτεχνίας, πνευματικών δικαιωμάτων ή εμπορικού σήματος Netsize.
NETSIZE
Ανώνυμη Εταιρεία 5 478 070 ευρώ
Siège social :62, λεωφόρος Emile Zola92100 Boulogne – Γαλλία
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Πεδίο εφαρμογής του εγγράφου
Αυτό το έγγραφο περιγράφει πώς ο πάροχος υπηρεσιών χρησιμοποιεί το LINK Mobility REST API για SMS. Προορίζεται για τεχνικούς αρχιτέκτονες και σχεδιαστές που υλοποιούν τις υπηρεσίες του Παρόχου Υπηρεσιών.
1. Βασική χρήση
Είναι πολύ εύκολο να στείλετε ένα SMS. Στέλνετε ένα αίτημα HTTP στο LINK Mobility το οποίο μπορεί να επιτευχθεί χρησιμοποιώντας απλώς ένα web πρόγραμμα περιήγησης.
2. Λειτουργικό Overview
Το σύστημα LINK Mobility παρέχει τις ακόλουθες βασικές λειτουργίες για μηνύματα SMS:
Αποστολή μηνυμάτων SMS με τερματισμό κινητής τηλεφωνίας (MT), όπως μηνύματα κειμένου ή δυαδικά (π.χ. WAP Push) premium και τυπικής χρέωσης.
Λήψη αναφορών παράδοσης για υποβληθέντα μηνύματα ΜΤ.
Λήψη μηνυμάτων SMS προέλευσης (MO), premium και τυπικής χρέωσης.
Το SMS REST API είναι αφιερωμένο στην αποστολή μηνυμάτων SMS τυπικής χρέωσης MT.
Το API στέλνει όλα τα μηνύματα SMS ασύγχρονα, επιτρέποντας λειτουργίες όπως:
«Fire-and-Forget» – ο Πάροχος Υπηρεσιών θέλει να έχει πιο προβλέψιμους χρόνους απόκρισης και δεν θέλει να περιμένει το αποτέλεσμα από τον Διαχειριστή.
Επανάληψη της λειτουργίας – Το LINK Mobility θα στείλει ξανά το μήνυμα εάν ο χειριστής έχει προσωρινά προβλήματα.
2.1 Αποστολή μηνύματος SMS
Πάροχος υπηρεσιών Netsize Consumer
- Αποστολή μηνύματος ΜΤ
- Αναγνωριστικό μηνύματος επιστροφής
- Υποβολή μηνύματος SMS
- Παράδοση αναφοράς παράδοσης
- Αποστολή αναφοράς παράδοσης
Η βασική ροή για την αποστολή μηνυμάτων SMS περιγράφεται ως εξής:
Ο πάροχος υπηρεσιών υποβάλλει αίτημα αποστολής μηνύματος SMS σε έναν παραλήπτη μέσω του συστήματος LINK Mobility.
Ένα αναγνωριστικό μηνύματος επιστρέφεται στον πάροχο υπηρεσιών. Αυτό το αναγνωριστικό μπορεί να χρησιμοποιηθεί για π.χ. να συσχετίσει το μήνυμα με τη σωστή αναφορά παράδοσης.
Το LINK Mobility χειρίζεται τη δρομολόγηση και παραδίδει το μήνυμα SMS στον καταναλωτή που απευθύνεται.
Μια αναφορά παράδοσης ενεργοποιείται, π.χ. όταν το μήνυμα SMS παραδίδεται στη συσκευή του Καταναλωτή.
Η αναφορά παράδοσης αποστέλλεται στον πάροχο υπηρεσιών. Η αναφορά περιέχει το ίδιο αναγνωριστικό μηνύματος που επιστράφηκε στο βήμα 2.
Εναλλακτική ροή: Μη έγκυρο αίτημα
Εάν οι παρεχόμενες παράμετροι ή τα διαπιστευτήρια χρήστη στο αίτημα δεν είναι έγκυρα, επιστρέφεται σφάλμα στον πάροχο υπηρεσιών. Το σφάλμα υποδεικνύει τον λόγο της απόρριψης και η ροή τελειώνει. Δεν επιστρέφονται αναγνωριστικά μηνυμάτων.
3. Τελικό σημείο
Η πρόσβαση στον πόρο SMS γίνεται χρησιμοποιώντας τη διαδρομή:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Για ασφάλεια σύνδεσης, το LINK Mobility REST API είναι προσβάσιμο μόνο μέσω HTTPS.
Το πιστοποιητικό διακομιστή Link Mobility υπογράφεται από την Thawte Server CA.
4. Λειτουργίες
Η υπηρεσία SMS παρέχει τις ακόλουθες λειτουργίες:
| Ονομα | Μονοπάτι |
| Στέλνω | /restapi/v1/sms/send |
4.1 Αποστολή
Η λειτουργία αποστολής χρησιμοποιείται για την αποστολή SMS σε έναν μόνο παραλήπτη.
Αυτή η λειτουργία προορίζεται τόσο για βασικούς όσο και για προχωρημένους χρήστες. Στην απλούστερη περίπτωση, απαιτείται μόνο η διεύθυνση προορισμού και το κείμενο του μηνύματος για την παράδοση ενός SMS. Το LINK Mobility θα εντοπίσει το Σχήμα Κωδικοποίησης Δεδομένων και θα πραγματοποιήσει αυτόματη συνένωση ενός μηνύματος σε πολλαπλά τμήματα μηνύματος, εάν είναι απαραίτητο.
Για προχωρημένη χρήση, ο πάροχος υπηρεσιών μπορεί να χρησιμοποιήσει προαιρετικές παραμέτρους για τον απόλυτο έλεγχο της μορφοποίησης του μηνύματος, συμπεριλαμβανομένης της κεφαλίδας δεδομένων χρήστη.
Ο Πάροχος Υπηρεσιών μπορεί να στείλει αλληλοσυνδεόμενα μηνύματα, αλλά η προετοιμασία των δεδομένων χρήστη και της κεφαλίδας δεδομένων χρήστη πρέπει να γίνει από τον πάροχο υπηρεσιών και το μήνυμα πρέπει να αποσταλεί μέσω πολλαπλών αιτημάτων αποστολής προς το LINK Mobility.
5. Έλεγχος ταυτότητας
Το όνομα χρήστη και ο κωδικός πρόσβασης υποβάλλονται σε κάθε αίτημα χρησιμοποιώντας το βασικό σύστημα ελέγχου ταυτότητας HTTP.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Τα διαπιστευτήρια αποστέλλονται σε μια κεφαλίδα εξουσιοδότησης στο αίτημα HTTP. Ο πελάτης κατασκευάζει το πεδίο κεφαλίδας όπως περιγράφεται εδώ:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Για π.χample, εάν το όνομα χρήστη είναι john και το changeme είναι ο κωδικός πρόσβασης, τότε η κεφαλίδα εξουσιοδότησης που προκύπτει είναι:
Εξουσιοδότηση: Βασική am9objpjaGFuZ2VtZSA=
Ως εναλλακτικό, το όνομα χρήστη και ο κωδικός πρόσβασης μπορούν να υποβληθούν ως παράμετροι αιτήματος. Αυτό συνιστάται μόνο για πελάτες που δεν υποστηρίζουν Βασικό έλεγχο ταυτότητας.
6. Υποβολή αιτήματος
6.1 Συμβολοσειρά ερωτήματος
Οι παράμετροι αιτήματος υποβάλλονται ως συμβολοσειρά ερωτήματος που περιέχει ζεύγη ονόματος/τιμής. Η συμβολοσειρά ερωτήματος κωδικοποιείται με χρήση κωδικοποίησης ποσοστού (URL κωδικοποίηση).
http://www.w3schools.com/tags/ref_urlencode.asp
Για π.χample, Γεια σου Κόσμο! κωδικοποιείται ως Hello+World%21.
6.2 Υποχρεωτικές παράμετροι αιτήματος
| Ονομα | Μέγιστο μήκος | Περιγραφή |
| Διεύθυνση προορισμού | 40 | Το MSISDN στο οποίο θα πρέπει να σταλεί το μήνυμα SMS, ξεκινώντας με τον κωδικό χώρας. Πρώηνample: 46123456789. Για ορισμένες αγορές (όπου το Consumer MSISDN πρέπει να είναι ασαφές) αυτή η τιμή μπορεί επίσης να είναι ένα αλφαριθμητικό ψευδώνυμο, με πρόθεμα "#". |
| Κείμενο μηνύματος | 1600 | Το περιεχόμενο του μηνύματος SMS. |
6.3 Προαιρετικές παράμετροι αιτήματος (για προχωρημένη χρήση)
| Ονομα | Μέγιστο μήκος | Περιγραφή |
| προέλευσης Διεύθυνση | 16 | Η διεύθυνση προέλευσης για το εξερχόμενο μήνυμα SMS. Ο τύπος της αρχικής διεύθυνσης ορίζεται από την παράμετρο originatorTON. Το μέγιστο μήκος του μικρού αριθμού είναι 16. Ο αλφαριθμητικός αποστολέας περιορίζεται στο προεπιλεγμένο αλφάβητο GSM με μέγιστο μήκος 11 χαρακτήρες. Το μέγιστο μήκος του αποστολέα MSISDN είναι 15 (χρησιμοποιώντας την ίδια μορφή με το στοιχείο DestinationAddress). Μπορεί να παραλειφθεί όταν επιλέγονται από το σύστημα originatingAddress και originatingTON. Αυτή η λειτουργία εξαρτάται από την αγορά και τη διαμόρφωση. Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| δημιουργόςTON | 1 | Ο τύπος του αριθμού διεύθυνσης προέλευσης (TON): 0 – Σύντομος αριθμός 1 – Αλφαριθμητικό (μέγιστο μήκος 11) 2 – MSISDN Μπορεί να παραλειφθεί όταν το originatingAddress και το originatingTON επιλέγονται από το σύστημα. Αυτή η λειτουργία εξαρτάται από την αγορά και τη διαμόρφωση. Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| userDataHeader | 280 | Η κεφαλίδα δεδομένων χρήστη μαζί με τα δεδομένα χρήστη μπορεί να περιέχει έως και 140, δηλαδή 280, όταν είναι κωδικοποιημένη με εξαγωνικό, οκτάδες. Αυτή η παράμετρος είναι πάντα με εξαγωνική κωδικοποίηση. |
| DCS | 3 | Σχέδιο κωδικοποίησης δεδομένων. Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| PID | 3 | Αναγνωριστικό πρωτοκόλλου. Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| relativeValidityTime | 6 | Σχετικός χρόνος εγκυρότητας σε δευτερόλεπτα (σε σχέση με τον χρόνο υποβολής στο LINK Mobility). Η μέγιστη τιμή είναι 604800 (7 ημέρες) και η προεπιλογή είναι 48 ώρες. Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| Χρόνος παράδοσης | 20 | Έγκαιροςamp πότε πρέπει να παραδοθεί το μήνυμα SMS (καθυστερημένος χρόνος παράδοσης). Δείτε την ενότητα για τη μορφή ώρας ημερομηνίας. |
| statusReportFlags | 1 | Παράδοση αιτήματος αναφοράς: 0 – Καμία αναφορά παράδοσης (προεπιλογή) 1 – Ζητήθηκε αναφορά παράδοσης 9 – Ζητείται αναφορά παράδοσης διακομιστή (η LINK Mobility δεν προωθεί την αναφορά στον πάροχο υπηρεσιών, αλλά την καθιστά διαθέσιμη σε αναφορές κ.λπ.) |
| campaignName | 50 | Οι συναλλαγές LINK Mobility είναι tagged με αυτό το όνομα. Χρησιμοποιείται για την ομαδοποίηση συναλλαγών σε αναφορές κινητικότητας συνδέσμων. |
| maxConcatenatedMessages | 1 | Μια τιμή μεταξύ 1 και 10 που καθορίζει πόσα αλληλοσυνδεόμενα μηνύματα επιτρέπονται. Η προεπιλογή είναι 3. |
| συσχέτισηId | 100 | Αναγνωριστικό που παρέχεται από τον Πάροχο Υπηρεσιών που θα επαναλαμβάνεται στην Αναφορά παράδοσης. |
| όνομα χρήστη | 100 | Παρέχεται ως εναλλακτική λύση στον Βασικό έλεγχο ταυτότητας HTTP. |
| σύνθημα | 100 | Παρέχεται ως εναλλακτική λύση στον Βασικό έλεγχο ταυτότητας HTTP. |
6.4 Μέθοδοι αιτήματος HTTP
Για μέγιστη διαλειτουργικότητα, το API υποστηρίζει μεθόδους αιτήματος HTTP GET και POST. Δεν επιτρέπονται άλλες μέθοδοι HTTP.
6.4.1 GET
Η κωδικοποιημένη συμβολοσειρά ερωτήματος προσαρτάται στο URL.
ΠΑΙΡΝΩ
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
Εξουσιοδότηση: Βασική am9objpjaGFuZ2VtZSA=
6.4.2 ΑΝΑΡΤΗΣΗ
Η κωδικοποιημένη συμβολοσειρά ερωτήματος υποβάλλεται στο σώμα του μηνύματος αιτήματος HTTP. Το περιεχόμενο-Τύπος είναι εφαρμογή/x-www-form-urlκωδικοποιημένα.
ΘΕΣΗ https://europe.ipx.com/restapi/v1/sms/send
Διοργανωτής: europe.ipx.com
Τύπος περιεχομένου: εφαρμογή/x-www-form-urlκωδικοποιημένα
Εξουσιοδότηση: Βασική am9objpjaGFuZ2VtZSA=
Περιεχόμενο-Μήκος: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Ημερομηνία και ώρα
Οι παράμετροι στο REST API που αντιπροσωπεύουν την ημερομηνία και την ώρα βρίσκονται πάντα στη ζώνη ώρας UTC (Συντονισμένη παγκόσμια ώρα). TimestampΤα s αντιπροσωπεύονται ως συμβολοσειρά με αυτήν ακριβώς τη μορφή:
2017-04-25T23:20:50Z
Αυτό αντιπροσωπεύει 20 λεπτά και 50 δευτερόλεπτα μετά την 23η ώρα της 25ης Απριλίου 2017 σε UTC.
7. Μήνυμα απάντησης
Μετά τη λήψη και την ερμηνεία ενός μηνύματος αιτήματος, το API απαντά με ένα μήνυμα απόκρισης HTTP.
7.1 Κωδικός κατάστασης HTTP
Το REST API επιστρέφει πάντα τον κωδικό κατάστασης HTTP 200 OK για επεξεργασμένα αιτήματα. Το σώμα του μηνύματος περιέχει έναν κωδικό απάντησης παραμέτρου που χρησιμοποιείται για τον προσδιορισμό του ακριβούς αποτελέσματος.
7.2 Σώμα μηνύματος
Το σώμα του μηνύματος αποτελείται από JSON που περιγράφει το αποτέλεσμα του αιτήματος.
http://json.org/
Το Link Mobility JSON συμμορφώνεται με τον Οδηγό στυλ JSON της Google.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Παράμετροι απόκρισης
| Ονομα | Μέγιστο μήκος | Περιγραφή |
| Κωδικός απάντησης | 3 | Το 0 υποδηλώνει επιτυχημένη συναλλαγή. |
| Απάντηση Μήνυμα | 255 | Περιγραφή κειμένου απάντησης, π.χ. κείμενο σφάλματος. |
| χρόνοamp | 20 | Ημερομηνία και ώρα που η LINK Mobility επεξεργάστηκε το αίτημα. (Ανατρέξτε στην ενότητα μορφή ημερομηνίας/ώρας). |
| traceId | 36 | Εσωτερικό αναγνωριστικό Link Mobility. Χρησιμοποιείται για υποστήριξη και αντιμετώπιση προβλημάτων. |
| αναγνωριστικά μηνυμάτων | 10 x 36 | Πίνακας μοναδικών αναγνωριστικών μηνυμάτων LINK Mobility για κάθε επιτυχημένο μήνυμα (επιστρέφονται πολλαπλά αναγνωριστικά μηνυμάτων εάν το μήνυμα είναι συνενωμένο). Παραλείπεται σε περίπτωση αποτυχίας. |
7.4 Πρampοι απαντήσεις
Επιτυχία
HTTP/1.1 200 OK
Τύπος περιεχομένου: εφαρμογή/json
Περιεχόμενο-Μήκος: 144
Ημερομηνία: Πέμ. 15 Σεπ 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Εδώ είναι το ίδιο JSON με μορφοποίηση για αναγνωσιμότητα:
{
“Κωδικός απάντησης“:0,
“Απάντηση Μήνυμα":"Επιτυχία",
“χρόνοamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“αναγνωριστικά μηνυμάτων":["1-4850879008"] }
Αποτυχία
HTTP/1.1 200 OK
Τύπος περιεχομένου: εφαρμογή/json
Περιεχόμενο-Μήκος: 148
Ημερομηνία: Πέμ. 15 Σεπ 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Μη έγκυρη σύνδεση ή μη εξουσιοδοτημένη χρήση API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Επιτυχία
HTTP/1.1 200 OK
Τύπος περιεχομένου: εφαρμογή/json
Περιεχόμενο-Μήκος: 144
Ημερομηνία: Πέμ. 15 Σεπ 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Εδώ είναι το ίδιο JSON με μορφοποίηση για αναγνωσιμότητα:
{
“Κωδικός απάντησης“:0,
“Απάντηση Μήνυμα":"Επιτυχία",
“χρόνοamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“αναγνωριστικά μηνυμάτων":["1-4850879008"] }
Αποτυχία
HTTP/1.1 200 OK
Τύπος περιεχομένου: εφαρμογή/json
Περιεχόμενο-Μήκος: 148
Ημερομηνία: Πέμ. 15 Σεπ 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Μη έγκυρη σύνδεση ή μη εξουσιοδοτημένη χρήση API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Κωδικοί απόκρισης
Οι ακόλουθοι κωδικοί απόκρισης μπορούν να επιστραφούν στην απάντηση αποστολής:
| Κώδικας | Κείμενο | Περιγραφή |
| 0 | Επιτυχία | Εκτελέστηκε με επιτυχία. |
| 1 | Μη έγκυρη σύνδεση ή μη εξουσιοδοτημένη χρήση API | Το λανθασμένο όνομα χρήστη ή κωδικός πρόσβασης ή ο παροχέας υπηρεσιών εμποδίζεται από το LINK Mobility. |
| 2 | Ο καταναλωτής αποκλείεται από το Link Mobility | Ο Καταναλωτής αποκλείεται από το LINK Mobility. |
| 3 | Η λειτουργία δεν παρέχεται από το LINK Mobility | Η λειτουργία έχει αποκλειστεί για τον πάροχο υπηρεσιών. |
| 4 | Ο καταναλωτής είναι άγνωστος στο LINK Mobility | Ο καταναλωτής είναι άγνωστος στο LINK Mobility. Ή αν χρησιμοποιήθηκε ψευδώνυμο στο αίτημα. ψευδώνυμο δεν βρέθηκε. |
| 5 | Ο καταναλωτής έχει αποκλείσει αυτήν την υπηρεσία στο LINK Mobility | Ο καταναλωτής έχει αποκλείσει αυτήν την υπηρεσία στο LINK Mobility. |
| 6 | Η αρχική διεύθυνση δεν υποστηρίζεται | Η αρχική διεύθυνση δεν υποστηρίζεται. |
| 7 | Η διεύθυνση προέλευσης Alpha δεν υποστηρίζεται από τον λογαριασμό | Η διεύθυνση προέλευσης alpha δεν υποστηρίζεται από τον λογαριασμό. |
| 8 | Η διεύθυνση προέλευσης MSISDN δεν υποστηρίζεται | Η διεύθυνση προέλευσης MSISDN δεν υποστηρίζεται. |
| 9 | Το GSM επεκτάθηκε δεν υποστηρίζεται | Το GSM επεκτάθηκε δεν υποστηρίζεται. |
| 10 | Το Unicode δεν υποστηρίζεται | Το Unicode δεν υποστηρίζεται. |
| 11 | Η αναφορά κατάστασης δεν υποστηρίζεται | Η αναφορά κατάστασης δεν υποστηρίζεται. |
| 12 | Η απαιτούμενη ικανότητα δεν υποστηρίζεται | Η απαιτούμενη δυνατότητα (εκτός των παραπάνω) για την αποστολή του μηνύματος δεν υποστηρίζεται. |
| 13 | Υπέρβαση του μέγιστου ποσοστού στραγγαλισμού του παρόχου περιεχομένου | Ο πάροχος υπηρεσιών στέλνει τα μηνύματα SMS στο LINK Mobility πολύ γρήγορα. |
| 14 | Το αναγνωριστικό πρωτοκόλλου δεν υποστηρίζεται από τον λογαριασμό | Το αναγνωριστικό πρωτοκόλλου δεν υποστηρίζεται. |
| 15 | Υπέρβαση του ορίου συνένωσης μηνυμάτων | Ο αριθμός των συνδεδεμένων μηνυμάτων υπερβαίνει τον μέγιστο αριθμό που ζητήθηκε. |
| 16 | Δεν είναι δυνατή η δρομολόγηση του μηνύματος. | Το LINK Mobility δεν μπόρεσε να δρομολογήσει το μήνυμα. |
| 17 | Απαγορευμένη χρονική περίοδος | Δεν επιτρέπεται η αποστολή μηνύματος κατά τη διάρκεια της χρονικής περιόδου |
| 18 | Πολύ χαμηλό υπόλοιπο στον λογαριασμό παρόχου υπηρεσιών | Ο πάροχος υπηρεσιών είναι αποκλεισμένος λόγω πολύ χαμηλού υπολοίπου |
| 50 | Μερική επιτυχία | Μερική επιτυχία κατά την αποστολή μηνύματος SMS σε πολλούς παραλήπτες. |
| 99 | Σφάλμα εσωτερικού διακομιστή | Άλλο σφάλμα κινητικότητας συνδέσμου, επικοινωνήστε με την υποστήριξη του LINK Mobility για περισσότερες πληροφορίες. |
| 100 | Μη έγκυρη διεύθυνση προορισμού | Η διεύθυνση προορισμού (MSISDN ή ψευδώνυμο) δεν είναι έγκυρη. |
| 102 | Μη έγκυρο αναγνωριστικό αναφοράς (συνδεδεμένο). | Το αναγνωριστικό αναφοράς δεν είναι έγκυρο, ίσως το αναγνωριστικό αναφοράς χρησιμοποιείται ήδη, πολύ παλιό ή άγνωστο. |
| 103 | Μη έγκυρο όνομα λογαριασμού | Το όνομα λογαριασμού δεν είναι έγκυρο. |
| 105 | Μη έγκυρα μεταδεδομένα υπηρεσίας | Τα μεταδεδομένα της υπηρεσίας δεν είναι έγκυρα. |
| 106 | Μη έγκυρη διεύθυνση προέλευσης | Η αρχική διεύθυνση δεν είναι έγκυρη. |
| 107 | Μη έγκυρη αλφαριθμητική διεύθυνση προέλευσης | Η αλφαριθμητική διεύθυνση προέλευσης δεν είναι έγκυρη. |
| 108 | Μη έγκυρος χρόνος ισχύος | Ο χρόνος ισχύος δεν είναι έγκυρος. |
| 109 | Μη έγκυρος χρόνος παράδοσης | Ο χρόνος παράδοσης δεν είναι έγκυρος. |
| 110 | Μη έγκυρο περιεχόμενο μηνύματος/δεδομένα χρήστη | Τα δεδομένα χρήστη, δηλαδή το μήνυμα SMS, δεν είναι έγκυρα. |
| 111 | Μη έγκυρο μήκος μηνύματος | Το μήκος του μηνύματος SMS δεν είναι έγκυρο. |
| 112 | Μη έγκυρη κεφαλίδα δεδομένων χρήστη | Η κεφαλίδα δεδομένων χρήστη δεν είναι έγκυρη. |
| 113 | Μη έγκυρο σχήμα κωδικοποίησης δεδομένων | Το DCS δεν είναι έγκυρο. |
| 114 | Μη έγκυρο αναγνωριστικό πρωτοκόλλου | Το PID δεν είναι έγκυρο. |
| 115 | Μη έγκυρες σημαίες αναφοράς κατάστασης | Οι σημαίες αναφοράς κατάστασης δεν είναι έγκυρες. |
| 116 | Μη έγκυρο TON | Το αρχικό TON δεν είναι έγκυρο. |
| 117 | Μη έγκυρο γampόνομα aign | Το γampΤο όνομα aign δεν είναι έγκυρο. |
| 120 | Μη έγκυρο όριο για μέγιστο αριθμό αλληλοσυνδεόμενων μηνυμάτων | Ο μέγιστος αριθμός αλληλοσυνδεόμενων μηνυμάτων δεν είναι έγκυρος. |
| 121 | Μη έγκυρη διεύθυνση προέλευσης msisdn | Η διεύθυνση προέλευσης MSISDN δεν είναι έγκυρη. |
| 122 | Μη έγκυρο αναγνωριστικό συσχέτισης | Το αναγνωριστικό συσχέτισης δεν είναι έγκυρο. |
8. Προαιρετικά χαρακτηριστικά
8.1 Διόρθωση MSISDN
Η διόρθωση MSISDN είναι μια προαιρετική δυνατότητα που μπορεί να ενεργοποιηθεί από την υποστήριξη LINK Mobility εάν ζητηθεί.
Αυτή η δυνατότητα θα διορθώσει τις διευθύνσεις προορισμού και θα τις ευθυγραμμίσει με την απαιτούμενη μορφή E.164. Εκτός από τη διόρθωση μορφής, το σύστημα μπορεί επίσης να εκτελέσει συγκεκριμένες λειτουργίες της αγοράς, όπως τη μετάφραση διεθνών γαλλικών αριθμών για τη διόρθωση αριθμών DOM-TOM (départements et territores d'outre-mer) όπου ισχύει.
Παρακάτω είναι ένας αριθμός πρώηνampΟι διορθώσεις:
| Υποβλήθηκε Διεύθυνση Προορισμού | Διορθωμένη διεύθυνση προορισμού |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Ο αριθμός στα γαλλικά μεταφράζεται σε αριθμό DOM-TOM) |
Επιπλέον, είναι δυνατό να επιτρέπονται εθνικοί αριθμοί τηλεφώνου για μια επιλεγμένη αγορά. Όταν αυτή η δυνατότητα είναι ενεργοποιημένη, όλοι οι διεθνείς αριθμοί για άλλες αγορές πρέπει να αποστέλλονται με ένα αρχικό σύμβολο «+» για να διακρίνονται από την επιλεγμένη αγορά.
Παρακάτω είναι αρκετές πρώηνampΟι διορθώσεις που έγιναν όταν χρησιμοποιείται η Σουηδία (κωδικός χώρας 46) ως προεπιλεγμένη αγορά για εθνικούς αριθμούς.
| Υποβλήθηκε Διεύθυνση Προορισμού | Διορθωμένη διεύθυνση προορισμού |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Μη έγκυρο επειδή λείπει το σύμβολο "+". |
Σημειώστε ότι το διορθωμένο MSISDN θα χρησιμοποιηθεί από το LINK Mobility και θα επιστραφεί στις αναφορές παράδοσης.
Επικοινωνήστε με την υποστήριξη LINK Mobility για περισσότερες πληροφορίες.
8.2 Αντικατάσταση χαρακτήρων
Η αντικατάσταση χαρακτήρων είναι μια προαιρετική δυνατότητα που μπορεί να ενεργοποιηθεί από την υποστήριξη LINK Mobility, εάν ζητηθεί.
Αυτή η δυνατότητα θα μεταφράσει χαρακτήρες αλφαβήτου εκτός GSM στα δεδομένα χρήστη (κείμενο SMS) σε ισοδύναμους χαρακτήρες αλφαβήτου GSM όταν το DCS έχει οριστεί σε "GSM" (17). Για π.χampΤο «Seqüência de teste em Português» θα μεταφραστεί σε «Seqüencia de teste em Portugues».
9. Εκθέσεις παράδοσης
Ο πάροχος υπηρεσιών μπορεί, εάν παρέχεται, να ζητήσει αναφορές παράδοσης μηνυμάτων SMS ή ειδοποιήσεις παράδοσης για τα μηνύματα ΜΤ που αποστέλλονται. Αυτές οι αναφορές ενεργοποιούνται στο Operator SMSC όταν το μήνυμα MT παραδίδεται στον στοχευμένο καταναλωτή ή διαγράφεται, π.χ. έχει λήξει ή, για κάποιο λόγο, δεν μπορεί να δρομολογηθεί.
Μόνο η τελική κατάσταση του μηνύματος SMS αναφέρεται στον πάροχο υπηρεσιών, δηλαδή παραδόθηκε ή διαγράφηκε. Δημιουργείται μόνο μία αναφορά ανά μήνυμα MT. Με τη διαγραμμένη κατάσταση, ενδέχεται να ισχύει ένας κωδικός αιτίας. Αυτός ο κωδικός αιτίας καθορίζει τον λόγο για τον οποίο δεν παραδόθηκε το μήνυμα SMS.
Οι αναφορές δρομολογούνται μέσω του LINK Mobility και αποστέλλονται στον πάροχο υπηρεσιών χρησιμοποιώντας το πρωτόκολλο HTTP.
Για να λαμβάνει αναφορές, ο Πάροχος Υπηρεσιών πρέπει να εφαρμόσει για π.χampγια μια σελίδα Java Servlet ή ASP.NET. Και οι δύο λαμβάνουν αιτήματα HTTP GET ή POST.
Παράμετροι
Το αίτημα περιλαμβάνει τις ακόλουθες παραμέτρους:
| Παράμετρος | Τύπος | M/O/I* | Προεπιλεγμένη τιμή | Μέγιστο μήκος | Περιγραφή |
| Αναγνωριστικό μηνύματος | σειρά | M | – | 22 | Το αναγνωριστικό μηνύματος του μηνύματος MT στο οποίο αντιστοιχεί αυτή η αναφορά. |
| Διεύθυνση Προορισμού | σειρά | M | – | 40 | Το MSISDN του Καταναλωτή, δηλαδή η διεύθυνση προορισμού του αρχικού μηνύματος ΜΤ. |
| Κωδικός κατάστασης | ακέραιος αριθμός | M | 1 | Ο κωδικός κατάστασης υποδεικνύει την κατάσταση του μηνύματος MT. Οι ισχύοντες κωδικοί κατάστασης είναι: 0 – Παραδόθηκε 2 – Διαγράφηκε (ισχύει ο κωδικός αιτίας) |
|
| TimeStamp | σειρά | M | – | 20 | Η ώρα που υποδεικνύει πότε ελήφθη η αναφορά παράδοσης από το LINK Mobility. Η ζώνη ώρας της ώραςamp είναι CET ή CEST (με θερινή ώρα όπως ορίζεται για την ΕΕ). Μορφή: εεεεΜηη ΩΩ:λλ:δδ. |
| Χειριστής | σειρά | M | – | 100 | Το όνομα του χειριστή που χρησιμοποιείται κατά την αποστολή του μηνύματος SMS ή το όνομα λογαριασμού που χρησιμοποιείται κατά την αποστολή του μηνύματος SMS. Μια λίστα με τους διαθέσιμους χειριστές παρέχεται από την υποστήριξη LINK Mobility. |
| ReasonCode | ακέραιος αριθμός | O | – | 3 | Ο κωδικός αιτίας υποδεικνύει γιατί το μήνυμα κατέληξε στην κατάσταση διαγραμμένο. Οι ισχύοντες κωδικοί λόγων είναι: 100 – Λήγει 101 – Απορρίφθηκε 102 – Σφάλμα μορφοποίησης 103 – Άλλο σφάλμα 110 – Άγνωστος συνδρομητής 111 – Αποκλεισμός συνδρομητή 112 – Δεν παρέχεται συνδρομητής 113 – Ο συνδρομητής δεν είναι διαθέσιμος 120 – Αποτυχία SMSC 121 – Συμφόρηση SMSC 122 – Περιαγωγή SMSC 130 – Σφάλμα ακουστικού 131 – Υπέρβαση της μνήμης του ακουστικού Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| OperatorTimeStamp | σειρά | O | – | 20 | Χρόνος που υποδεικνύει πότε ενεργοποιήθηκε η αναφορά στο SMSC του Χειριστή (εάν παρέχεται από τον Διαχειριστή). Η ζώνη ώρας της ώραςamp είναι CET ή CEST (με θερινή ώρα όπως ορίζεται για την ΕΕ). Μορφή: εεεεΜηη ΩΩ:λλ:δδ. |
| StatusText | σειρά | O | – | 255 | Θέση κράτησης θέσης για πρόσθετες πληροφορίες από τον Χειριστή, π.χ. σαφής περιγραφή της κατάστασης/λόγου με κείμενο. Η συμπεριφορά μπορεί να διαφέρει ανάλογα με τις ενσωματώσεις χειριστή. |
| ΣυσχέτισηId | σειρά | O | – | 100 | Το αναγνωριστικό συσχέτισης που παρέχεται στο SendRequest ή στο SendTextRequest. |
| Κωδικός δικτύου χειριστή | ακέραιος αριθμός | O | – | 6 | Ο Κωδικός δικτύου κινητής τηλεφωνίας (MCC + MNC) του Διαχειριστή. |
* M = Υποχρεωτικό, O = Προαιρετικό, I = Αγνοήθηκε.
Ο πάροχος υπηρεσιών πρέπει να παρέχει το LINK Mobility με τον στόχο URL για αναφορές παράδοσης (προαιρετικά συμπεριλαμβανομένων των διαπιστευτηρίων για τον βασικό έλεγχο ταυτότητας HTTP). Ο πάροχος υπηρεσιών μπορεί να επιλέξει ποια προτιμώμενη μέθοδο HTTP θα χρησιμοποιήσει:
HTTP POST (συνιστάται)
HTTP GET.
ExampΧρησιμοποιώντας το HTTP GET (παραδόθηκε με επιτυχία):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
ExampΧρησιμοποιώντας HTTP GET (δεν παραδίδεται, ο χειριστής έχει παράσχει χρόνοamp για την εκδήλωση):
Οι παράμετροι είναι URL κωδικοποιούνται.
Κωδικοποίηση χαρακτήρων:
Ο πάροχος υπηρεσιών μπορεί να επιλέξει ποια προτιμώμενη κωδικοποίηση χαρακτήρων θα χρησιμοποιήσει:
UTF-8 (συνιστάται)
ISO-8859-1.
9.1 Αναγνώριση παρόχου υπηρεσιών
Ο πάροχος υπηρεσιών θα πρέπει να αναγνωρίζει κάθε αναφορά παράδοσης. Η επιβεβαίωση μπορεί να είναι θετική, δηλαδή αναφορά παράδοσης με επιτυχία, ή αρνητική, δηλαδή αποτυχία.
Σημείωση: Το LINK Mobility έχει χρονικό όριο ανάγνωσης για επιβεβαιώσεις 30 δευτερολέπτων για αναφορές παράδοσης. Ένα χρονικό όριο λήξης θα ενεργοποιήσει μια επανάληψη προσπάθειας παράδοσης (αν είναι ενεργοποιημένη η επανάληψη) ή μια ακύρωση της παράδοσης (εάν η επανάληψη είναι απενεργοποιημένη). Αυτό σημαίνει ότι η εφαρμογή Service Provider πρέπει να διασφαλίζει γρήγορους χρόνους απόκρισης, ειδικά κατά τη διάρκεια υψηλού φορτίου.
Συνιστάται ιδιαίτερα να αναγνωρίσετε την αναφορά παράδοσης προς το LINK Mobility πριν την επεξεργαστείτε.
Ο κανόνας για θετική και αρνητική αναγνώριση περιγράφεται ως εξής:
Θετική επιβεβαίωση, ACK, αναφορά παράδοσης:
Κώδικας απόκρισης εύρους HTTP 200 σε συνδυασμό με το ακόλουθο περιεχόμενο σε μορφή XML:
Αρνητική επιβεβαίωση, NAK, αναφορά παράδοσης δεν παραδόθηκε:
Οποιαδήποτε απάντηση εκτός από θετική επιβεβαίωση, π.χampΓια παράδειγμα, μια αρνητική επιβεβαίωση ενεργοποιείται από οποιονδήποτε κωδικό σφάλματος HTTP ή το ακόλουθο περιεχόμενο XML:
Το περιεχόμενο XML μπορεί να χρησιμοποιηθεί για τον έλεγχο του μηχανισμού επανάληψης LINK Mobility. Ένα NAK θα προκαλέσει προσπάθεια επανάληψης, εάν είναι ενεργοποιημένο. Για παρόχους υπηρεσιών που δεν έχουν ρυθμιστεί για τον μηχανισμό επανάληψης δοκιμής, το περιεχόμενο XML είναι προαιρετικό.
Ακολουθεί ένα αίτημα και απάντηση HTTP POST π.χampμια αναφορά παράδοσης που παραδόθηκε σε έναν πάροχο υπηρεσιών:
Αίτημα HTTP:
POST /context/app HTTP/1.1
Τύπος περιεχομένου: εφαρμογή/x-www-form-urlencoded;charset=utf-8
Κεντρικός υπολογιστής: διακομιστής: θύρα
Περιεχόμενο-Μήκος: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
Απόκριση HTTP:
HTTP/1.1 200 OK
Περιεχόμενο-Τύπος: κείμενο/απλό
9.2 Επανάληψη
Το σύστημα LINK Mobility μπορεί να εκτελέσει προσπάθειες επανάληψης για αποτυχημένες, δηλ. μη επιβεβαιωμένες παραδόσεις αναφοράς παράδοσης. Ο πάροχος υπηρεσιών μπορεί να επιλέξει την προτιμώμενη συμπεριφορά επανάληψης:
Χωρίς επανάληψη (προεπιλογή) – το μήνυμα θα απορριφθεί εάν η προσπάθεια σύνδεσης αποτύχει, το χρονικό όριο ανάγνωσης ή τυχόν κωδικός σφάλματος HTTP.
Δοκιμάζω πάλι – το μήνυμα θα σταλεί εκ νέου για κάθε τύπο προβλήματος σύνδεσης, χρονικού ορίου ανάγνωσης ή αρνητική επιβεβαίωση.
Όταν είναι ενεργοποιημένη η επανάληψη δοκιμής για το NAK, είναι σημαντικό να κατανοήσετε ποια σενάρια θα δημιουργήσουν μια προσπάθεια επανάληψης από το LINK Mobility και πώς λειτουργεί η επανάληψη. Κάθε πάροχος υπηρεσιών έχει τη δική του ουρά επανάληψης, όπου τα μηνύματα ταξινομούνται σύμφωνα με το χρονικό διάστημα μηνύματοςamp. Το Link Mobility προσπαθεί πάντα να παραδίδει πρώτα παλαιότερα μηνύματα, παρόλο που η μεμονωμένη σειρά των μηνυμάτων που παραδίδονται στον πάροχο υπηρεσιών δεν είναι εγγυημένη. Ο κύριος λόγος για την απόρριψη μηνυμάτων από την ουρά επανάληψης είναι ένας από τους δύο λόγους: είτε το μήνυμα TTL λήγει είτε (θεωρητικά) η ουρά επανάληψης γεμίζει. Το TTL εξαρτάται από τον χειριστή και τον λογαριασμό, δηλαδή, μπορεί να διαφέρει ανάλογα με τον χειριστή και τον τύπο μηνύματος, π.χ., SMS premium ή μήνυμα SMS τυπικής χρέωσης.
Οι πάροχοι υπηρεσιών με ενεργοποιημένη την επανάληψη πρέπει να ελέγξουν το μοναδικό αναγνωριστικό του μηνύματος MT για να διασφαλίσουν ότι το μήνυμα δεν έχει ήδη ληφθεί.
Είναι σημαντικό για τον Πάροχο Υπηρεσιών να συμμορφώνεται με αυτούς τους απλούς κανόνες όταν παρουσιάζεται σφάλμα κατά την επεξεργασία μιας αναφοράς παράδοσης, εάν ο λόγος του σφάλματος είναι: Προσωρινή, π.χ. μη διαθέσιμη βάση δεδομένων, πρέπει να επιστραφεί ένα NAK. Το LINK Mobility θα στείλει ξανά το μήνυμα.
Η μόνιμη και μια προσπάθεια επανάληψης είναι πιθανό να προκαλέσει το ίδιο πρόβλημα, ένα ACK θα πρέπει να επιστραφεί. Για π.χample, όταν το μήνυμα δεν μπορούσε να αναλυθεί σωστά ή προκάλεσε απροσδόκητο σφάλμα χρόνου εκτέλεσης.
Η ανάλογη ενέργεια θα διασφαλίσει ότι δεν προκαλείται αποκλεισμός ή υποβάθμιση της απόδοσης λόγω επανειλημμένης αποστολής αναφοράς παράδοσης.
10. Συμβουλές υλοποίησης
1. Είναι δυνατό να χρησιμοποιήσετε το δικό σας web πρόγραμμα περιήγησης για την υποβολή αιτημάτων στο API. Αυτό καθιστά πολύ εύκολη την εξερεύνηση και την αξιολόγηση των υπηρεσιών χωρίς εργαλεία ανάπτυξης.
2. Το Chrome ή ο Firefox συνιστώνται μαζί με μια επέκταση όπως το JSONView για εμφάνιση JSON με όμορφη μορφή.
3. Χρησιμοποιήσαμε το SoapUI για δοκιμή POST, Βασικό έλεγχο ταυτότητας και για επιθεώρηση των μη επεξεργασμένων μηνυμάτων αιτήματος και απάντησης HTTP.
4. Το γURL Το εργαλείο είναι χρήσιμο για την υποβολή αιτημάτων POST με Βασικό έλεγχο ταυτότητας. Βλέπε π.χample παρακάτω.
curl ΑΝΑΡΤΗΣΗ \
-H “Content-Type: application/x-www-form-urlκωδικοποιημένο» \
-H “Authorization: Basic am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
_______________
Μετασχηματίζοντας τις Εξατομικευμένες Επικοινωνίες
Έγγραφα / Πόροι
 |
Οδηγός υλοποίησης LINK Mobility REST API SMS [pdf] Οδηγός χρήστη Mobility Implementation Guide REST API SMS, Mobility, Implementation Guide REST API SMS, REST API SMS, API SMS, SMS |
