Οδηγίες για SMS HTTP API

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

Μέσω HTTP API.

Ο χρήστης λοιπόν, μπορεί μέσω HTTP requests να αποστέλει τα SMS του (μέσω φυσικά του account που έχει ήδη δημιουργήσει στο smsing.gr) από άλλες εφαρμογές (c#, java, php, jscript, visual basic κοκ) και να μπορεί επιπλέον να έχει και αναφορά για το κάθε SMS, βάσει του μοναδικού ID που επιστρέφεται από το web service κατά την αποστολή του SMS.

Η κλήση του web service γίνεται μέσω του παρακάτω url:

http://www.smsing.gr/webservice/sms/sendSMSHTTP.php

 Σε αυτό, με GET request προσθέτουμε και τις απαραίτητες μεταβλητές που είναι οι εξής:

1. username [alphanumeric] - όνομα χρήστη που έχετε στο smsing.gr
2. password [alphanumeric] - κωδικός χρήστη για το smsing.gr
3. destination [alphanumeric] - Νούμερο κινητού, πχ. για Ελλάδα 306912345678, δηλαδή χωρίς μηδενικά ή το σύμβολο + μπροστά.
4. sender [alphanumeric] - Όνομα αποστολέα. Μέγιστο πλάτος 11 χαρακτήρες. Δεν επιτρέπεται να είναι τηλ νούμερο.
   
5. message [alphanumeric] - Το κείμενο του μηνύματος SMS που θέλετε να στείλετε. Υπόψιν, πως το κείμενο πρέπει να είναι url encoded. Μπορείτε να γράψετε λατινικούς και ελληνικούς χαρακτήρες (πάντα με url encode).

Ένα παράδειγμα των παραπάνω είναι:

http://www.smsing.gr/webservice/sms/sendSMSHTTP.php?username=myusername&....

Το παραπάνω request, σε περίπτωση επιτυχίας, θα μας επιστρέψει:

OK ID:<SMS HTTP request ID>

όπου <SMS HTTP request ID> [integer], είναι το μοναδικό ID που αντιστοιχεί σε αυτό το SMS.

ένα παράδειγμα:

OK ID:1234

Σε περίπτωση αποτυχίας λαμβάνουμε κάποιο από τα εξής παρακάτω μηνύματα:

• Internal Error.
• Invalid destination or Destination not covered.
• System error. Please retry.

Για τον έλεγχο του status του απεσταλμένου SMS, πρέπει να κάνουμε επίσης ένα GET request στο:

http://www.smsing.gr/webservice/sms/getSMSStatus.php

Οι μεταβλητές που εισάγουμε σε αυτό το url είναι:

1. SMSId [integer] - Το ID που μας επέστρεψε το web service κατά την αποστολή του SMS με HTTP API.
2. username [alphanumeric] - Το username που έχετε στο smsing.gr
3. password [alphanumeric] -Το password για το παραπάνω username

Έτσι, ένα παράδειγμα αποστολής φαίνεται αμέσως παρακάτω:

http://www.smsing.gr/webservice/sms/getSMSStatus.php?SMSId=1111&username...

Το αποτέλεσμα αυτής της κλήσης είναι είτε κάποιο μήνυμα λάθους όπως:

• Error: 1012 - User authendication failure. Username and/or password mismatch.
• Error: 1027 - No SMS ID given.
• Error: 1028 - No valid parameters given.

ή ένας πίνακας από τιμές χωρισμένες με τον χαρακτήρα [:], που περιέχει όλα τα στοιχεία της κατάστασης του SMS. Συγκεκριμένα:

<SMSId>:<Submtited On>:<Destination number>:<Delivered On>:<Status number>:<Quantity of SMS>:<Charge amount>

 πχ. 2345:20101212152514:306912345678:20101212152519:2048:1:0.057

1. SMSId [Integer] - Το ID του SMS που αναζητούμε.
2. Submited On [String] - Ημερομηνία και ώρα αποστολής του SMS. Είναι της μορφής YYYYMMDDHHmmSS [YYYY:year, MM:month 00~12, DD:day of month 00~31, HH:hour 00~24, mm:minutes 00~59, SS:seconds 00~59].
3. Destination number [String] - Νούμερο αποστολής.
4. Delivered On [String] - Ημερομηνία και ώρα παράδοσης του SMS. Είναι της μορφής YYYYMMDDHHmmSS [YYYY:year, MM:month 00~12, DD:day of month 00~31, HH:hour 00~24, mm:minutes 00~59, SS:seconds 00~59].
5. Status number [Integer] - Αριθμός που υποδηλώνει το status του SMS. Πιθανές τιμές:
   • 1: Queued
   • 2: Queued on SMSC
   • 4: Waiting Validation
   • 8: Unknown subscriber
   • 16: Temporary unavailable
   • 32: Pending
   • 64: Undelivered
   • 128: Expired
   • 256: Non-Delivered to SMSC
   • 512: Error
   • 1024: Unknown error
   • 2048: Delivered
   • 16384: HLR Sent
   • 32768: HLR Completed
6. Quantity of SMS [Integer] - Αριθμός SMS που χρεώθηκαν
7. Charge amount [float] - Ποσό που χρεώθηκε στο SMS.

Για τον έλεγχο του account balance (διαθέσιμο υπόλοιπο χρημάτων και αριθμός sms) πρέπει να κάνουμε ένα GET request στο:

http://smsing.gr/webservice/sms/getAccountBalance.php

Οι απαιτούμενες μεταβλητές για την κλήση αυτού του webservice είναι:

• username [alphanumeric] - Το username σας για το smsing.gr
• password [alphanumeric] - Το password
• countryprefix [alphanumeric] - (προεραιτικό) Το πρόθεμα της χώρας για την οποία θέλετε να ελέγξετε το υπόλοιπο της ποσότητας των sms που μένουν ακόμη στο λογαριασμό σας. πχ. Αν δώσε σαν countryprefix το 30 (πρόθεμα Ελλάδας) και έχετε υπόλοιπο 112.90€ και η τιμή του SMS για Ελλάδα είναι 0.024, τότε το webservice θα σας επιστρέψει 4704 διαθέσιμα SMS.

 Οι πιθανές απαντήσεις του webservice είναι:

Status: 1000 - Balance:BalanceInEuro|SmsRemainCount:RemainingSMSCount

• BalanceInEuro, είναι το ποσό που υπάρχει στο λογαριασμό σας

• RemainingSMSCount, τα SMS που απομένουν για τη χώρα που ρωτάτε - Να σημειωθεί πως αν δεν έχετε βάλει κάποιο πρόθεμα ή το πρόθεμα της χώρας είναι λάθος, τότε το σύστημα σας επιστρέφει την τιμή -9999.

 ενώ σε περίπτωση αποτυχίας οι πιθανές απαντήσεις μπορεί να είναι:

Error: 1001 - No username given.

Error: 1002 - No password given.

Ένα παράδειγμα φαίνεται αμέσως πιο κάτω:

http://smsing.gr/webservice/sms/getAccountBalance.php?username=myusername&password=pass%40%24&countryprefix=30