ΜΕΛΕΤΗ ΕΦΑΡΜΟΓΗΣ ΓΙΑ ΤΟ ΕΡΓΟ «ΑΝΑΠΤΥΞΗ ΠΛΑΤΦΟΡΜΑΣ ΠΑΡΟΧΗΣ ΥΠΗΡΕΣΙΩΝ ΑΠΟΣΤΟΛΗΣ ΚΑΙ ΛΗΨΗΣ ΣΥΝΤΟΜΩΝ ΜΗΝΥΜΑΤΩΝ» ΟΔΗΓΟΣ ΔΙΑΣΥΝΔΕΣΗΣ για το Έργο «Ανάπτυξη Πλατφόρμας Παροχής Υπηρεσιών Αποστολής και Λήψης Σύντομων Μηνυμάτων» ΙΟΥΝΙΟΣ 2015 ΠΕΡΙΕΧΟΜΕΝΑ 1.Εισαγωγή... 3 2.Αρχιτεκτονική...3
2.1Λογική Αρχιτεκτονική της πλατφόρμας...3 2.2Κλήσεις API...4 2.3Παραδείγματα κλήσεων...4 2.3.1Παράδειγμα send SMS... 4 2.3.2Παράδειγμα send SMS response...4 2.3.3Παράδειγμα DLR Request... 5 2.3.4Παράδειγμα SMS forward request...6 2.3.5Παράδειγμα SMS forward response...6 Σελ. 2 από 10
1. Εισαγωγή Ο σκοπός του εγγράφου είναι να περιγραφεί η Διασύνδεση Προγραμματισμού Εφαρμογών (API) της πλατφόρμας αποστολής σύντομων μηνυμάτων της GUNet προκειμένου να γίνει δυνατή η διασύνδεση των Πανεπιστημιακών Ιδρυμάτων με την πλατφόρμα. Η Διασύνδεση Προγραμματισμού Εφαρμογών της πλατφόρμας επιτρέπει στις εξωτερικές εφαρμογές των Πανεπιστημιακών Ιδρυμάτων να χρησιμοποιήσουν τις υπηρεσίες αποστολής SMS μέσω της τεχνολογίας JSON χωρίς την ανάγκη υλοποίησης πολύπλοκων πρωτοκόλλων όπως το SMPP. Η πλατφόρμα προσφέρει διαφορετικές υπηρεσίες SMS που ορίζονται από την GUNet. Κάθε υπηρεσία έχει έναν αριθμό από προκαθορισμένα μηνύματα και κάθε ένα από τα οποία μπορεί να σταλεί σε έναν παραλήπτη. Τα προκαθορισμένα μηνύματα μπορούν να υποστηρίξουν δυναμικά πεδία, τις τιμές των οποίων θα καθορίζει η πλευρά του καλούντος. Για παράδειγμα, μπορεί να υπάρξει ένα προκαθορισμένο μήνυμα "Η βαθμολογία σας για το μάθημα Πεδίο 1,1 είναι Πεδίο 2,2". Τα Πανεπιστημιακά Ιδρύματα μπορούν να καλέσουν την υπηρεσία δίνοντας τιμές στα δυναμικά πεδία "Πληροφορική Ι" και "7" και το τελικό μήνυμα προς το χρήστη να είναι "Η βαθμολογία σας για το μάθημα Πληροφορική Ι είναι 7". Η χρήση των υπηρεσιών την πλατφόρμας προϋποθέτει: Η IP διεύθυνση της πλευράς που καλεί το Web Service να είναι εισηγμένη σαν επιτρεπτή στην πλατφόρμα Σε κάθε κλήση του Web Service θα πρέπει να περιλαμβάνεται προκαθορισμένο κλειδί που θα έχει δοθεί στην πλευρά του καλούντος από τους διαχειριστές της πλατφόρμας, όπως επεξηγείται στη συνέχεια Σελ. 3 από 10
2. Αρχιτεκτονική 2.1 Λογική Αρχιτεκτονική της πλατφόρμας Όπως φαίνεται και στο διάγραμμα, οι εφαρμογές των Πανεπιστημιακών Ιδρυμάτων καλούν μέσω HTTP/HTTPS τα Web Services της πλατφόρμας, η οποία για την αποστολή/λήψη των μηνυμάτων επικοινωνεί μέσω του πρωτοκόλλου SMPP με τα SMSCs των τηλεπικοινωνιακών παρόχων. Σελ. 4 από 10
2.2 Κλήσεις API 1 Send SMS 3rd party προς πλατφόρμα GUNet Μέθοδος που χρησιμοποιείται για την αποστολή ενός SMS μέσω της πλατφόρμας της GUNet. Το όνομα της μεθόδου, το οποίο θα εμφανίζεται στο endpoint, είναι sendsms Πεδία: serviceid (string - υποχρεωτικό): το ID της υπηρεσίας που περιέχει το προκαθορισμένο μήνυμα προς αποστολή messageid (string - υποχρεωτικό): το ID του προκαθορισμένου μηνύματος που πρέπει να σταλεί στον παραλήπτη replacements (array of strings - προαιρετικό): Οι τιμές των δυναμικών πεδίων που θα αντικατασταθούν στο προκαθορισμένο μήνυμα recipient(string - υποχρεωτικό): Το username ή το MSISDN του χρήστη. Σε περίπτωση που χρησιμοποιηθεί username, η πλατφόρμα θα χρησιμοποιήσει το discovery service του Πανεπιστημιακού Ιδρύματος για να βρει το MSISDN. institution (string - υποχρεωτικό): Το keyword του Πανεπιστημιακού Ιδρύματος που καλεί το WS pre-shared key (string - υποχρεωτικό): Το προκαθορισμένο token που θα πιστοποιεί ότι η πλευρά που καλεί το Web Service είναι το συγκεκριμένο Πανεπιστημιακό Ίδρυμα dlr-url (string - προαιρετικό): το URL που θα λάβει την αναφορά παράδοσης από την Σελ. 5 από 10
πλατφόρμα όταν αυτή ενημερωθεί πως το SMS παραδόθηκε 2 Send SMS Response πλατφόρμα GUNet προς 3rd party H απάντηση του server στον client που επιβεβαιώνει την υποβολή αποστολής SMS. Ο client είναι υπεύθυνος για τον χειρισμό αυτής της απάντησης Πεδία: serviceid (number) - το ID της υπηρεσίας που κλήθηκε errorcode - Ο κωδικός σφάλματος. Η λίστα των κωδικών βρίσκεται στην ενότητα 2.3.2 error (string) - Πιθανό σφάλμα στην υποβολή: unknown service, unknown message, unknown recipient, unknown institution, invalid pre-shared key, unauthorized sender address, user not opted in, user deactivated service, user credits expired, service deactivated, general error etc. 3 DLR Request πλατφόρμα GUNet προς 3rd party H απάντηση του server όταν λαμβάνει ένα DLR για μια αποστολή που είχε υποβληθεί με το πεδίο dlr-url παρόν. Πεδία: serviceid (number) - το ID της υπηρεσίας που κλήθηκε recipient (number) - Το MSISDN του Σελ. 6 από 10
παραλήπτη status (string): 'DELIVRD', 'ERROR', 'EXPIRED', 'PENDING', 'SENT', 'SUBMITTED', 'UNDELIV' error (string): 0,999 4 SMS forward πλατφόρμα GUNet προς 3rd party Η κλήση αυτή γίνεται από την πλατφόρμα της GUNet προς ένα συγκεκριμένο Πανεπιστημιακό Ίδρυμα, όταν κάποιος χρήστης στείλει ένα SMS στην πλατφόρμα που περιλαμβάνει ένα συγκεκριμένο Keyword. Πεδία: MSISDN (number) - Το MSISDN του αποστολέα keyword - Το keyword με το οποίο ξεκινάει το μήνυμα body - Το περιεχόμενο του μηνύματος που ακολουθεί μετά το keyword pre-shared key : Το προκαθορισμένο token που θα πιστοποιεί ότι η πλευρά που καλεί το Web Service του Πανεπιστημιακού Ιδρύματος είναι η πλατφόρμα SMS της GUNet 2.3 Παραδείγματα κλήσεων 2.3.1 Παράδειγμα send SMS "serviceid": "gradeservice", "messageid": "newgrade", "replacements": [ "Προγραμματισμός Ι", Σελ. 7 από 10
], "7" "recipient": "6901234567", "institution": "ΑΠΘ", "pre-shared key": "F0fesFADSr223fA", "dlr-url": "url" 2.3.2 Παράδειγμα send SMS response Επιτυχές: "serviceid": "gradeservice", "errorcode": "" "error": "" Ανεπιτυχές: "serviceid": "gradeservice", "errorcode": "E-002" "error": "Unknown Service" Κωδικοί Σφάλματος: E-001 general error E-002 unknown service E-003 unknown message E-004 unknown recipient E-005 unknown institution E-010 invalid pre-shared key E-011 unauthorized sender address E-012 user not opted in E-013 user deactivated service E-014 user credits expired E-015 service deactivated 2.3.3 Παράδειγμα DLR Request Επιτυχές: Σελ. 8 από 10
"serviceid": "gradeservice", "recipient": "6901234657", "status": "DELIVRD" Ανεπιτυχές: "serviceid": "gradeservice",φ "recipient": "6901234657", "status": "ERROR", "error": "80" 2.3.4 Παράδειγμα SMS forward request "MSISDN": "6901234657", "keyword": "ΕΓΓΡΑΦΗ", "body": "ΜΑΘΗΜΑ ΕΠΙΛΟΓΗΣ", "pre-shared key": "F0fesFADSr223fA" 2.3.5 Παράδειγμα SMS forward response Εάν η πλατφόρμα διαχειρίστηκε το request όπως πρέπει, τότε η απάντηση θα πρέπει να γυρίζει result=0. Αν για οποιοδήποτε λόγο η διαχείρηση του request δεν ήταν επιτυχής, τότε η απάντηση θα πρέπει να περιέχει result=1. Τα πεδία error και errorcode δεν χρησιμεύουν σε κάτι για την ώρα αλλά υπάρχουν για πιθανή μελλοντική χρήση. Σε περίπτωση που γυρνάει ανεπιτυχής απάντηση, η πλατφόρμα κρατάει log του errorcode και error που επιστράφηκαν. Επιτυχές: "result": "0", "errorcode": "" "error": "" Ανεπιτυχές: Σελ. 9 από 10
"result": "1", "errorcode": "error-code-1" "error": "error-description" Σελ. 10 από 10