RESTful SMS API v.2 για επικοινωνία με το SMS Gateway

Στη σελίδα αυτή περιγράφονται οι διαθέσιμες λειτουργίες που παρέχονται για την επικοινωνία με το sms gateway.
To HTTP API σας επιτρέπει να προσθέσετε εύκολα στις εφαρμογές σας την δυνατότητα αποστολής SMS χρησιμοποιώντας το πρωτόκολλο HTTP.

Γενικά

Το πρόγραμμα κάνει μια HTTP GET κλήση στο easysms HTTP interface παρέχοντας την λίστα με τις απαραίτητες παραμέτρους. Το easysms απαντάει στην κλήση όπως περιγράφεται στη συνέχεια.

Σημειώστε οτι ο διαχωριστικός χαρακτήρας στα επιστρεφόμενα δεδομένα της κλήσης status είναι η κάθετος, '|', (ASCII 124).

Όλες οι παράμετροι θα πρέπει να είναι με κωδικοποίηση UTF-8 και URL-encoded, όπως περιγράφεται στα παραδείγματα κώδικα παρακάτω.

Απαντήσεις κλήσεων API

Το API απαντάει σε όλες τις κλήσεις ανάλογα με την τιμή της παραμέτρου type. Οι τιμές που δέχεται η παράμετρος type είναι: v2, json και xml.
Παραδείγματα απαντήσεων για την κλήση της εντολής key/get:

...&type=v2

Επιστρέφει:

6fe2dd9c06df83

...&type=json

Επιστρέφει:

{
   "status" : "1",
   "key" : "6fe2dd9c06df83",
   "remarks" : "Success"
}

...&type=xml

Επιστρέφει:

<response>
   <status>1</status>
   <key>6fe2dd9c06ff83</key>
   <remarks>Success</remarks>
</response>

Δοκίμασέ το   (key/get)

http://easysms.gr/api/key/get?username=&password=&type=
Δοκίμασέ το  

Ακολουθεί περιγραφή των διαθέσιμων εντολών.




API Key

Το API Key αντικαθιστά τα username και password για όλες τις κλήσεις του API. Αν θέλετε μπορείτε να χρησιμοποιείτε τις παραμέτρους username και password αλλά συνιστούμε να χρησιμοποιείτε το API Key για λόγους ασφάλειας.

Το API Key το παίρνετε μια φορά με την εντολή key/get και το χρησιμοποιείτε για όλες σας τις κλήσεις αντί να δίνετε τις παραμέτρους username και password. Αν χρειαστεί να αλλάξετε το API Key, μπορείτε να το κάνετε με την εντολή key/reset.
Οι εντολές key/get και key/reset είναι οι μόνες που απαιτούν την χρήση username και password.
Μόλις πάρετε το API Key μπορείτε να το χρησιμοποιείτε για όλες τις άλλες κλήσεις του API.

Δοκίμασέ το   (key/get)

http://easysms.gr/api/key/get?username=&password=&type=
Δοκίμασέ το  

Δοκίμασέ το   (key/reset)

http://easysms.gr/api/key/reset?username=&password=&type=
Δοκίμασέ το  

Επιστρέφουν

...&type=v2

Επιστρέφει:

6fe2dd9c06df83

...&type=json

Επιστρέφει:

{
   "status" : "1",
   "key" : "6fe2dd9c06df83",
   "remarks" : "Success"
}

...&type=xml

Επιστρέφει:

<response>
   <status>1</status>
   <key>6fe2dd9c06ff83</key>
   <remarks>Success</remarks>
</response>
 

Αποστολή SMS

RESTful SMS API v.2

URL: http://easysms.gr/api/sms/send?key=[API Key]

Παράμετροι

Παράμετρος Περιγραφή Παρουσία
text Κείμενο του μηνύματος. Πρέπει να είναι URL encoded Υποχρεωτικό
to Αριθμός κινητού τηλεφώνου του παραλήπτη του μηνύματος. Πχ: 306944777888 Υποχρεωτικό
from Αποστολέας του μηνύματος (για αλφαριθμητικούς μέχρι 11 χαρακτήρες, για αριθμητικούς μέχρι 16 ψηφία. Για αποστολή σε Ελληνικά δίκτυα επιτρέπονται μόνο οι αλφαριθμητικοί αποστολείς) Προαιρετικό
flash True για αποστολή Flash sms Προαιρετικό
ucs True για αποστολή του μηνύματος με κωδικοποίηση UCS Προαιρετικό
timestamp Η ώρα που θα γίνει η αποστολή σε μορφή Unix Epoch timestamp Προαιρετικό
type Τύπος της απάντησης του API, μπορεί να είναι v2, json ή xml Προαιρετικό

Επιστρέφει

...&type=v2

Επιστρέφει:

1234567890

...&type=json

Επιστρέφει:

{
   "status" : "1",
   "id" : "1234567890",
   "balance" : "1234",
   "remarks" : "Success"
}

...&type=xml

Επιστρέφει:

<response>
   <status>1</status>
   <id>1234567890</id>
   <balance>1234</balance>
   <remarks>Success</remarks>
</response>
Περιγραφή
status 1 για επιτυχημένη αποστολή, διαφορετικά η αποστολή απέτυχε
id Ο κωδικός του μηνύματος (ή 0 σε αποτυχία), οι αναφορές παράδοσης δίνονται με βάση αυτόν
balance Το υπόλοιπο του λογαριασμού
remarks Σχόλια για το αποτέλεσμα της κλήσης

Δοκίμασέ το   (sms/send)

http://easysms.gr/api/sms/send?key=&to=&from=&text=Hello&type=
Δοκίμασέ το  

Παραδείγματα κώδικα για την αποστολή SMS

<?php
	// Simple SMS send function
	function sendSMS($key, $to, $message, $originator) {
		$URL = "http://easysms.gr/api/sms/send?key=" . $key . "&to=" . $to;
		$URL .= "&text=" . urlencode( $message ) . '&from=' . urlencode( $originator );
		$fp = fopen( $URL, 'r' );
		return fread( $fp, 1024 );
	}
	// Example of use 
	$response = sendSMS( 'My API Key', '4917512345', 'My test message', 'MyMessage' );
	echo $response;
?>
<?php
    // Simple SMS send function
    function sendSMS($key, $to, $message, $originator) {
        $URL = "http://easysms.gr/api/sms/send?key=" . $key . "&to=" . $to;
        $URL .= "&text=".urlencode($message).'&from='.urlencode($originator);
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $URL);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $output = curl_exec($ch);
        $info = curl_getinfo($ch);
        curl_close($ch);
        return $output;
    }
    // Example of use
    $response = sendSMS('My API Key', '4917512345', 'My test message', 'MyMessage');
    echo $response ;
?>
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;
// Uses Apache Common URL utils, download from apache.org and put it in CLASSPATH
import org.apache.commons.codec.binary.Base64;

// Simple send SMS programm
public class SendSMS {
    public static String sendSMS( String key, String to, String message, String originator ) {
		
        String webPage;
        try {
            webPage = "http://easysms.gr/api/sms/send?key=" + key + 
                "&to=" + to + "&text=" + URLEncoder.encode( message, "UTF-8" ) +
                "&from=" + URLEncoder.encode( originator, "UTF-8" );
        } catch ( UnsupportedEncodingException e ) {
            return "UnsupportedEncodingException";
        }

		try{
			URL url = new URL(webPage);
			URLConnection urlConnection = url.openConnection();

			InputStream is = urlConnection.getInputStream();
			InputStreamReader isr = new InputStreamReader(is);

			int numCharsRead;
			char[] charArray = new char[1024];
			StringBuffer sb = new StringBuffer();

			while ((numCharsRead = isr.read(charArray)) > 0) {
				sb.append(charArray, 0, numCharsRead);
			}
			String result = sb.toString();
			return result;		

		} catch ( Exception e ){
			return "MalformedURLException";
		}
    }

    public static void main( String[] args ){
        // Example of use 
        String response = sendSMS( "My API Key", "4917512345", "My test message", "MyMessage" );
        System.out.println( response );
    }
}
<%
    mykey = "My API Key" 'put your API Key here
    mobile = "4917512345"

    message = Server.URLEncode("My test message")
    originator  = Server.URLEncode("TextMessage")

    url = "http://easysms.gr/api/sms/send?key=" + mykey + "&to=" + mobile + "&text=" + message + "&from=" + originator

    set objSrvHTTP = Server.CreateObject("Msxml2.ServerXMLHTTP")
    objSrvHTTP.open "GET", url, False
    objSrvHTTP.send()
    Resp = objSrvHTTP.responseText

    Response.Write( Resp )
%>
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Web;

namespace SendSMS {
    class Program {
        public static string SendSMS( string key, string to, string message, string originator ) {
            StringBuilder sb  = new StringBuilder();
            byte[] buf = new byte[ 1024 ];
            string url = "http://easysms.gr/api/sms/send?key=" + key +
                "&to=" + to + "&text=" + HttpUtility.UrlEncode( message ) +
                "&from=" + HttpUtility.UrlEncode( originator );
            HttpWebRequest request = ( HttpWebRequest ) WebRequest.Create( url );
            HttpWebResponse response = ( HttpWebResponse ) request.GetResponse();
            Stream resStream = response.GetResponseStream();
            string tempString = null;
            int count = 0;
            do {
                count = resStream.Read( buf, 0, buf.Length );
                if ( count != 0 ) {
                    tempString = Encoding.ASCII.GetString( buf, 0, count );
                    sb.Append( tempString );
                }
            }
            while ( count > 0 );
            return sb.ToString();
        }
        static void Main( string[] args ) {
            string respXML = SendSMS( "My API Key", "4917512345", "My test message", "MyMessage" );
            Console.WriteLine( respXML );
       }
    }
}
/* * Send SMS C/C++ example need curllib download from http://curl.haxx.se/ */

#include <stdio.h>
#include <tchar.h>
#include <string.h>
#include <curl/curl.h>
#define URLSIZE 512

struct MemoryStruct {
        char *memory;
        size_t size;
};

/* Converts a hex character to its integer value */

char from_hex(char ch) {
        return isdigit(ch) ? ch - '0' : tolower(ch) - 'a' + 10;
}

/* Converts an integer value to its hex character*/

char to_hex(char code) {
        static char hex[] = "0123456789abcdef";
        return hex[code & 15];
}

/* Returns a url-encoded version of str */

char *url_encode(char *str) {
        char *pstr = str, *buf = (char *)malloc(strlen(str) * 3 + 1), *pbuf = buf;
        while (*pstr) {
                if (isalnum(*pstr) || *pstr == '-' || *pstr == '_' || *pstr == '.' || *pstr == '~')
                        *pbuf++ = *pstr;
                else if (*pstr == ' ')
                        *pbuf++ = '+';
                else
                        *pbuf++ = '%', *pbuf++ = to_hex(*pstr >> 4), *pbuf++ = to_hex(*pstr & 15);
                pstr++;
        }
        *pbuf = '\0';
        return buf;
}

/* CURL Callback write function */

static size_t WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp) {
        size_t realsize = size * nmemb;
        struct MemoryStruct *mem = (struct MemoryStruct *)userp;
        mem->memory = (char *)realloc(mem->memory, mem->size + realsize + 1);
        if (mem->memory == NULL) {
                /* out of memory! */
                printf("not enough memory (realloc returned NULL)\n");
                exit(EXIT_FAILURE);
        }
        memcpy(&(mem->memory[mem->size]), contents, realsize);
        mem->size += realsize;
        mem->memory[mem->size] = 0;
        return realsize;
}

/* Send SMS */

char * sendSMS(const char *key, const char *to, char *message, char *originator) {
        static char url[URLSIZE] = "http://easysms.gr/api/sms/send?key=";
        char *encoded;
        CURL *curl;
        CURLcode res;
        struct MemoryStruct chunk;
        chunk.memory = (char *)malloc(1);  /* will be grown as needed by the realloc above */
        chunk.size = 0;    /* no data at this point */
        curl = curl_easy_init();
        if(curl) {
                strcat_s(url, URLSIZE, key);
                strcat_s(url, URLSIZE, "&to=");
                strcat_s(url, URLSIZE, to);
                strcat_s(url, URLSIZE, "&text=");
                encoded = url_encode(message);
                strcat_s(url, URLSIZE, encoded);
                free(encoded);
                encoded = url_encode(originator);
                strcat_s(url, URLSIZE, "&from=");
                strcat_s(url, URLSIZE, encoded);
                free(encoded);
                curl_easy_setopt(curl, CURLOPT_URL, url);
                /* send all data to this function  */
                curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);
                /* we pass our 'chunk' struct to the callback function */
                curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
                if((res = curl_easy_perform(curl)) != CURLE_OK) {
                        return NULL;
                }
                curl_easy_cleanup(curl);
        }
        return chunk.memory;
}

int main(void) {
        char *response;
        response = sendSMS("My API Key", "4917512345", "My test message", "MyMessage");
        if(response != NULL) {
                printf(response);
                free(response);
        }
        getchar();
        return 0;
}
#include <iostream>
#include <string>
#using <System.Dll>
#using <System.Web.Dll>

using namespace std;
using namespace System;
using namespace System::Web;
using namespace System::Net;
using namespace System::IO;
using namespace System::Runtime::InteropServices;

ref class SMSSender
{

private:
        static String^ Key = "My API Key";

public:
        SMSSender()
        {}
        String^ SendSMS(String^ To, String^ Message, String^ From)
        {
                Message = HttpUtility::UrlEncode(Message);
                From = HttpUtility::UrlEncode(From);
                String^ URL = "http://easysms.gr/api/sms/send?key=" + Key + "&text=" + Message + "&from=" + From + "&to=" + To;
                WebRequest^ Handle = WebRequest::Create(URL);
                WebResponse^ HTTPResponse = Handle->GetResponse();
                StreamReader^ Stream = gcnew StreamReader(HTTPResponse->GetResponseStream());
                String^ Response = Stream->ReadToEnd()->Trim();
                HTTPResponse->Close();
                return Response;
        }
};

int main() {
        SMSSender^ test = gcnew SMSSender();
        String^ resp = test->SendSMS("4917512345", "My test message", "MyMessage");
        Console::WriteLine(resp);
        return 0;
}
require 'net/http'
require 'uri'

def send_sms( key, to, message, originator )
  requested_url = 'http://easysms.gr/api/sms/send?key=' + key + 
                "&to=" + to + "&text=" + URI.escape( message ) +
                "&from=" + URI.escape( originator )
  url = URI.parse( requested_url )
  full_path = ( url.query.blank? ) ? url.path : "#{url.path}?#{url.query}"
  the_request = Net::HTTP::Get.new( full_path )
  the_response = Net::HTTP.start( url.host, url.port ) { |http|
    http.request( the_request )
  }
  raise "Response was not 200, response was #{the_response.code}" if the_response.code != "200"
  return the_response.bodyend
resp = send_sms( 'My API Key', '4917512345', 'My test message', 'MyMessage' )

puts(resp)
Imports System.Web

Module Module1

	Public Function SendSMS( ByVal key As String, ByVal toPhone As String, 
								ByVal message As String, ByVal originator As String )
		Dim request As HttpWebRequest  
		Dim response As HttpWebResponse = Nothing  
		Dim reader As StreamReader  
		Dim url As String = "http://easysms.gr/api/sms/send?key=" & key & 
		                "&to=" & toPhone & "&text=" & System.Web.HttpUtility.UrlEncode( message ) &
		                "&from=" & System.Web.HttpUtility.urlencode( originator )
		Try  
		    ' Create the web request  
		    request = DirectCast(WebRequest.Create(url), HttpWebRequest)  
		    ' Get response  
		    response = DirectCast(request.GetResponse(), HttpWebResponse)  
		    ' Get the response stream into a reader  
		    reader = New StreamReader(response.GetResponseStream())  
		    ' Return response
			SendSMS = reader.ReadToEnd()
		Finally  
		    If Not response Is Nothing Then 
				response.Close()  
				Console.WriteLine("Error connecting")
			End If
		End Try  
	End Function

    Sub Main()
        Dim result As String = SendSMS( "My API Key", "4917512345", "My test message", "MyMessage" )
        Console.WriteLine( result )
        Console.ReadKey()
    End Sub

End Module


Υπόλοιπο Λογαριασμού

URL:   http://easysms.gr/api/balance/get?key=[API Key]

Επιστρέφει

Τον αριθμό των μηνυμάτων που απομένουν στο λογαριασμό.

...&type=v2

Επιστρέφει:

1234

...&type=json

Επιστρέφει:

{
   "status" : "1",
   "balance" : "1234",
   "remarks" : "Success"
}

...&type=xml

Επιστρέφει:

<response>
   <status>1</status>
   <balance>1234</balance>
   <remarks>Success</remarks>
</response>

Δοκίμασέ το   (balance/get)

http://easysms.gr/api/balance/get?key=&type=
Δοκίμασέ το  

Αναφορές Παράδοσης

URL:   http://easysms.gr/api/status/get?key=[API Key]

Επιστρέφει

Επιστρέφει όλες τις αλλαγές στην κατάσταση των μηνυμάτων που στάλθηκαν, διαχωρισμένες με κάθετο | (όταν η type είναι v2).

Η κατάσταση μπορεί να είναι s (στάλθηκε), d (παραδόθηκε) ή f (απέτυχε).

...&type=v2

Επιστρέφει:

...&type=json

Επιστρέφει:

{
   "0" : {
           "id" : "1231223122",
           "status" : "d"
   },
   "1" : {
           "id" : "1234561232",
           "status" : "f"
   },
   "status" : "1",
   "total" : "2",
   "remarks" : "Success"
}

...&type=xml

Επιστρέφει:

<response>
   <status>1</status>
   <total>2</total>
   <remarks>Success</remarks>
   <sms>
            <id>1231223122</id>
            <status>d</status>
   </sms>
   <sms>
            <id>1234561232</id>
            <status>f</status>
   </sms>
</response>

Δοκίμασέ το   (status/get)

http://easysms.gr/api/status/get?key=&type=
Δοκίμασέ το