Πριν από την αποστολή
Στείλτε ένα SMS ή υποστηριζόμενο MMS χρησιμοποιώντας έναν αριθμό αποστολής που έχει ρυθμιστεί για τον λογαριασμό σας. Πρόκειται για ενέργεια σε περιβάλλον παραγωγής που μπορεί να επικοινωνήσει με παραλήπτες και να επιφέρει χρεώσεις. Χρησιμοποιείτε μόνο παραλήπτες για τους οποίους έχετε εξουσιοδότηση και εγκεκριμένη κίνηση μηνυμάτων· οι αριθμοί και η αναφορά του παρακάτω παραδείγματος είναι φανταστικά.
Ο λογαριασμός σας χρειάζεται έγκριση για εξερχόμενα μηνύματα και τις ισχύουσες άδειες για τον αποστολέα, τη χώρα και την κίνηση μηνυμάτων. Τα απευθείας διαπιστευτήρια χρηστών προσωπικής ή καταναλωτικής χρήσης δεν είναι επιλέξιμα για αυτό το API. Τα εγκεκριμένα διαπιστευτήρια αποκλειστικής χρήσης API υπόκεινται σε ξεχωριστή διαδικασία επιλεξιμότητας· οι αποστολείς κινητής P2P ενδέχεται να χρειάζονται πρόσθετες άδειες P2P και άδειες για ΗΠΑ/Καναδά. Επιβεβαιώστε τη σωστή ρύθμιση του λογαριασμού με τη MultiTEL, αντί να θεωρείτε ότι ένα διαπιστευτήριο API παρέχει αυτόματα άδεια αποστολής οποιασδήποτε κίνησης μηνυμάτων.
Αίτημα αποστολής
Πραγματοποιήστε έλεγχο ταυτότητας μέσω HTTPS με έναν ενεργοποιημένο λογαριασμό API, από την επιτρεπόμενη διεύθυνση IP προέλευσής του. Διατηρείτε τα διαπιστευτήρια σε χώρο αποθήκευσης μυστικών στον διακομιστή. Χρησιμοποιήστε POST με πεδία κωδικοποιημένα ως φόρμα ή ένα αντικείμενο JSON όταν δεν παρέχονται πεδία φόρμας ή ερωτήματος. Μην τοποθετείτε διαπιστευτήρια ή κείμενο μηνύματος σε URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Πεδίο | Υποχρεωτικό | Σημασία |
|---|---|---|
| from | Ναι | Ο ρυθμισμένος αριθμός αποστολής σας, κατά προτίμηση με όλα τα ψηφία της διεθνούς μορφής. |
| to | Ναι | Ένας προορισμός, προορισμοί διαχωρισμένοι με κόμματα ή ένας πίνακας JSON. Προτιμήστε όλα τα ψηφία της διεθνούς μορφής. Ένα ομαδικό αίτημα μπορεί να απορριφθεί λόγω των ισχυόντων ορίων P2P ή χώρας· δεν πρόκειται για API μαζικής αποστολής χωρίς περιορισμούς. |
| text | Για SMS | Κείμενο μηνύματος σε UTF-8. Απαιτείται τουλάχιστον μη κενό κείμενο ή περιεχόμενο πολυμέσων. Στείλτε πραγματικούς χαρακτήρες και αλλαγές γραμμής αντί για HTML ή κείμενο με κωδικοποίηση διαφυγής με σύμβολα ποσοστού. Ορισμένες διαδρομές παρόχων κανονικοποιούν τις κυριολεκτικές συμβολοσειρές διαφυγής. |
| media | Για MMS μόνο με πολυμέσα | Περιεχόμενο πολυμέσων κωδικοποιημένο σε Base64, όχι URL ή διαδρομή αρχείου. Η διαθεσιμότητα, η μορφή και το μέγεθος των MMS εξαρτώνται από τη ρυθμισμένη διαδρομή. Επιβεβαιώστε με τη MultiTEL τα υποστηριζόμενα πολυμέσα· αυτός ο χειριστής δεν καθορίζει ενιαίο όριο μεγέθους πολυμέσων. |
| reference | Συνιστάται | Η ετικέτα συσχέτισής σας, η οποία διατηρείται στις εγγραφές και στις επανακλήσεις. Συμπεριλάβετε μια τέτοια ετικέτα για την αντιμετώπιση προβλημάτων. Δεν είναι κλειδί ιδιοδυναμίας. |
| notifyurl | Όχι | Ο δέκτης επανακλήσεων HTTPS σας. Ο χειριστής μπορεί να στείλει ένα αρχικό αποτέλεσμα μέσω POST μετά την επεξεργασία. Πρέπει να είναι δέκτης που ελέγχετε εσείς και δεν πρέπει να είναι URL εσωτερικής υπηρεσίας. |
Για πίνακα JSON, χρησιμοποιήστε πραγματικό πίνακα στο to· μην τοποθετείτε συμβολοσειρά πίνακα JSON μέσα σε πεδίο φόρμας. Χρησιμοποιήστε αποστολή σε έναν μόνο παραλήπτη ως αρχική δοκιμή διασύνδεσης. Η υποστήριξη ομαδικών αποστολών και MMS διαφέρει ανά διαδρομή, επομένως επιβεβαιώστε τον υποστηριζόμενο συνδυασμό πριν τα χρησιμοποιήσετε.
Διαβάστε το πλήρες αποτέλεσμα
Παρουσιάζονται μόνο επιλεγμένα πεδία για παράδειγμα· το εμφανιζόμενο κόστος δεν αποτελεί προσφορά τιμής.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Ελέγξτε συνδυαστικά την κατάσταση HTTP, το status.code του JSON και τα status/message της απόκρισης. Οι κωδικοί αποτελέσματος μπορεί να είναι συμβολοσειρές. Διατηρήστε το sms_log_id_ori και τις επιστρεφόμενες τιμές μηνύματος και αναφοράς για συσχέτιση από την υποστήριξη. Οι τιμές uniqueid και pid της παλαιότερης υλοποίησης διαφέρουν ανά διαδρομή· μην συνάγετε τη μορφή τους και μην υποθέτετε ότι αποτελούν διακριτικά ιδιοδυναμίας του πελάτη.
Η ένδειξη Success ή Message queued συνήθως περιγράφει αποδοχή από την επιλεγμένη διαδρομή, όχι παραλαβή στη συσκευή κάποιου ατόμου. Μια αρχική κατάσταση επανάκλησης όπως sent δεν αποδεικνύει από μόνη της την τελική παράδοση.
Τμήματα μηνύματος και χρεώσεις
Χρησιμοποιήστε την ανάλυση μήκους SMS στο πλήρες τελικό κείμενο πριν από την αποστολή. Οι τιμές SMS εξαρτώνται από τον προορισμό και την υπηρεσία του λογαριασμού· οι ισχύουσες χρεώσεις παρόχου προστίθενται ανά τμήμα μηνύματος. Η διαδρομή αποστολής συνδυάζει τις τιμές των παραληπτών και τις ισχύουσες χρεώσεις και, στη συνέχεια, πολλαπλασιάζει με τον υπολογισμένο αριθμό τμημάτων SMS. Για αυτόν τον υπολογισμό αντιμετωπίζει ένα αίτημα MMS ως ένα μήνυμα.
Τα cost και permsg είναι μορφοποιημένες συμβολοσειρές χρηματικών ποσών στην απόκριση της παλαιότερης υλοποίησης. Το carrier_fee_usd αναφέρει το μέρος του ποσού που αντιστοιχεί στη χρέωση παρόχου σε USD και περιλαμβάνεται ήδη στο υπολογισμένο συνολικό κόστος αποστολής· μην το προσθέσετε δεύτερη φορά. Πρέπει να ελέγξετε την πραγματική τιμολόγηση και τη διαθεσιμότητα διαδρομών για τον λογαριασμό σας. Το αίτημα δεν είναι ενέργεια αποκλειστικά για λήψη τιμής.
Ο κώδικας που ελέγχθηκε πραγματοποιεί χρέωση μετά την επιτυχή διαδρομή αποστολής μέσω παρόχου, αλλά η αποδοχή από τον πάροχο, η τοπική μόνιμη αποθήκευση και η χρέωση δεν αποτελούν μία ενιαία συναλλαγή. Μπορεί να προκύψει σφάλμα ή λήξη χρονικού ορίου αφού έχει γίνει αποδεκτό ένα αίτημα από το ανάντη σύστημα. Δεν παρέχεται κλειδί ιδιοδυναμίας του πελάτη: η επανάληψη της ίδιας αναφοράς μπορεί να προκαλέσει νέα αποστολή και νέα χρέωση.
Τοπική παράδοση και μικτά αποτελέσματα
Οι αριθμοί που φιλοξενούνται τοπικά μπορούν να γίνουν αποδεκτοί (accepted) στη ροή εισερχόμενων μηνυμάτων της MultiTEL χωρίς αποστολή μέσω εξωτερικού παρόχου. Για ένα αίτημα με αποκλειστικά τοπικούς παραλήπτες, η απόκριση μπορεί να περιλαμβάνει accepted, message_id, provider και delivery_status. Η τοπική αποδοχή δεν εγγυάται ότι λειτούργησε ο ρυθμισμένος προορισμός προώθησης του παραλήπτη.
Εξετάστε τα local_delivery_results και partial όταν υπάρχουν. Ένας παραλήπτης μπορεί να εμφανίζει accepted true, ενώ το αποτέλεσμα της προώθησής του είναι ανεπιτυχές. Ένα μικτό αίτημα μπορεί να έχει παραλήπτες αποδεκτούς από τον πάροχο (accepted) και αποτυχία στο τοπικό μέρος. Μην επαναλαμβάνετε αυτόματα ολόκληρη την παρτίδα: διασταυρώστε πρώτα το αποτέλεσμα για κάθε παραλήπτη.
Η αποδοχή αιτήματος με αποκλειστικά τοπικούς παραλήπτες αναφέρει μηδενικό κόστος εξερχόμενης αποστολής σε αυτή τη διαδρομή, ενώ οι παραλήπτες μπορεί να εξακολουθούν να επιβαρύνονται με τις κανονικές χρεώσεις εισερχόμενων μηνυμάτων. Μην ερμηνεύετε το μηδενικό κόστος εξερχόμενης αποστολής ως εγγύηση ότι δεν χρεώνεται κανένας λογαριασμός.
Επανακλήσεις και συσχέτιση
Όταν παρέχεται το notifyurl, η αρχική επανάκληση περιέχει ένα περίβλημα status και πεδία απόκρισης που περιλαμβάνουν τα message_id, reference, from, to, status, status_text, error_code, timestamp και accepted. Μπορεί επίσης να υπάρχουν τοπικά αποτελέσματα. Αποθηκεύετε τις πληροφορίες συσχέτισης χωρίς να καταγράφετε διαπιστευτήρια API ή περιεχόμενο μηνυμάτων που δεν είναι απαραίτητο.
Αυτός ο χειριστής δεν προσθέτει πεδίο υπογραφής σε εκείνη την αρχική επανάκληση. Μην χρησιμοποιείτε μια μη επαληθευμένη επανάκληση ως αυτοτελή εξουσιοδότηση για άλλη ενέργεια. Συμβουλευτείτε την υποστηριζόμενη ρύθμιση διασύνδεσης ή webhook για τον λογαριασμό σας και διασταυρώστε τα αβέβαια αποτελέσματα με τις εγγραφές της πύλης ή με την υποστήριξη. Μην υποθέτετε ότι οι επανακλήσεις φτάνουν μόνο μία φορά ή με τη σειρά της τελικής παράδοσης.
Αποτυχίες και ασφαλής ανάκαμψη
Οι αποτυχίες επικύρωσης μπορεί να χρησιμοποιούν τον κωδικό API 403. Οι απορρίψεις λόγω έγκρισης λογαριασμού ή πολιτικών P2P και χώρας μπορεί επίσης να ορίζουν HTTP 403 και να περιλαμβάνουν ένα response.code αναγνώσιμο από μηχανή. Τα όρια ρυθμού μπορεί να χρησιμοποιούν 429 με πληροφορίες επανάληψης. Μια μη διαθέσιμη πολιτική ή μια αποτυχία αποστολής ή τοπικής μόνιμης αποθήκευσης μπορεί να χρησιμοποιεί 503 ή 500· η ανεπαρκής πίστωση στην παλαιότερη υλοποίηση μπορεί επίσης να επιστρέφει 500.
Για το 429, τηρείτε το Retry-After και οποιαδήποτε τιμή response.retry_after. Σε περίπτωση απόρριψης λογαριασμού, αποστολέα, χώρας ή παραλήπτη, διορθώστε την αιτία πριν δοκιμάσετε ξανά. Σε περίπτωση λήξης χρονικού ορίου ή ασαφούς αποτελέσματος αποστολής, διατηρήστε την ώρα του αιτήματος, την αναφορά και τα αναγνωριστικά που επιστράφηκαν, ελέγξτε την πύλη και επικοινωνήστε με την υποστήριξη πριν από νέα αποστολή. Η απουσία εγγραφής καταγραφής από μόνη της δεν αποδεικνύει ότι κανένας πάροχος δεν αποδέχθηκε το αίτημα.