Español

Interfaz de Programación de Aplicaciones (API SMS)

Extremos

Lo primero que necesitas saber es a dónde enviar tu solicitud API. My-Cool-SMS acepta solicitudes tipo GET, POST y JSON vía puerto 80 o SSL en puerto 443. Puedes conectarte a las siguientes URLs, respectivamente.

HTTP

El extremo API para la solicitud HTTP es:
http://www.my-cool-sms.com/api-socket.php

HTTPS

Si requieres una conexión segura puedes usar el API via SSL en puerto 443.
El extremo API para la solicitud HTTPS es:
https://www.my-cool-sms.com/api-socket.php

Componentes API

My-Cool-SMS tiene dos tipos de componentes API. Funciones y Callbacks.

Funciones

Las funciones se usan, por ejemplo, para solicitar el envío de un mensaje, dejando ver tu saldo o reportes de entrega. Una función puede ser invocada usando la estructura de solicitud HTTP como se muestra más adelante.

Callbacks

Los callbacks son solicitudes de inserción enviados de My-Cool-SMS a tu servidor. Un callback es invocado en tiempo real cuando eventos como recibir un mensaje o un nuevo reporte de entrega ocurren, y se publica en una URL en tu servidor para ser procesado.

Estructura de Solicitud

Puedes enviar solicitudes via HTTP POST, GET o JSON. Aunque My-Cool-SMS no te impedirá usar POST o GET, se recomienda fuertemente usar solicitudes JSON. JSON es un formato de intercambio de datos ligero, que es fácil de leer y escribir por las personas y fácil de analizar y generar en el lenguaje de programación de tu preferencia.
Sobre todo, JSON es muy robusto al enviar mensajes en formato Unicode y no te exige implementar complejos procedimientos de codificación y decodificación UCS2. Si alguna vez tuviste que trabajar con codificación y decodificación UCS2, GSM7 o Unicode de servidor cruzado, sabes que evitar su uso es una bendición. Puedes averiguar más sobre JSON aquí.

Credenciales de Ingreso y Seleccionadores de Función

Una solicitud al API de My-Cool-SMS siempre debe contener tu usuario, contraseña y un seleccionador de función que le diga al API que es lo que deseas.

JSON

Demos un vistazo a un ejemplo de JSON que usarías si revisas tu saldo:
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

Con POST y GET la misma solicitud se vería así:
username=xxx&password=yyyy&function=getBalance

Parámetros Obligatorios y Opcionales

Mientras que el usuario, contraseña y parámetros de función se requieren siempre, cada función específicamente tiene parámetros obligatorios y opcionales que posiblemente también se deben dar.
Cuando se pide un reporte de entrega, por ejemplo, también querrás especificar de qué mensajes quieres el reporte. Esto se hace simplemente agregando un parámetro adicional, en este caso "id".
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Estructura de Respuesta

Una solicitud API siempre retorna un objeto JSON. Toda respuesta contiene un parámetro de éxito, que indica si la solicitud se procesó exitosamente o no. Dependiendo en si este parámetro es verdadero o falso, tú podrías querer dar un tratamiento diferente a la respuesta.

Respuesta Exitosa

Una solicitud exitosa a la función getDeliveryReport retornaría un objeto JSON como el siguiente:
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
Cada función tiene diferentes parámetros de respuesta. Puedes ver la especificación detallada aquí.

Respuesta de Error

Digamos que tienes un error tipográfico en el parámetro de contraseña. En este caso, el API retornará un objeto JSON con la siguiente estructura:
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
Puedes esperar siempre un código de error de tres dígitos y una descripción que te ayude a detectar el problema que se debe retornar cuando el parámetro de éxito en la respuesta es falso.

Manejo de Respuestas

Leer Respuesta

La respuesta API es siempre enviado en formato JSON. Todo lo que necesitas hacer con él es convertir los datos de respuesta en un objeto. Es realmente simple porque prácticamente todos los lenguajes de programación ofrecen métodos nativos para hacer justamente eso.
Para averiguar más información sobre JSON en tu lenguaje de programación ve a esta página y recórrela un poco.
En PHP harías algo de lo que está en las siguientes líneas para procesar la respuesta API:
// Let's assume you sent a getDeliveryReport request and
// the HTTP response is stored in $response...

// Now simply convert the response into a PHP object
$oResponse = json_decode($response);

//$oResponse is now an object

if($oResponse->success) {
    //Great. It worked!
    echo($oResponse->smsid);
    echo($oResponse->status);
} else {
    //Oops. something went wrong.
    echo($oResponse->errorcode);
    echo($oResponse->description);
}

Manejo de Callbacks

Leer Entrada

Los callbacks no son muy diferentes de las funciones y puedes convertirlos en un objeto exactamente igual a como se hizo antes. Sin embargo, algo que necesitas saber es cómo capturar la entrada de solicitud HTTP sin procesar. El callback no se envía vía GET ni POST, sino como datos HTTP sin procesar, los cuales puedes leer tal como se explica a continuación.
En PHP harías algo de lo que está en las siguientes líneas para procesar la solicitud de callback:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
En Java es prácticamente igual:
InputStream body = request.getInputStream();
Por favor nota que cualquiera sea el lenguaje de programación que uses, solo puedes leer una vez la entrada. Almacena el contenido en algún otro sitio para el procesamiento.

Ejemplos de PHP

Función: sendSms

Demos una mirada a cómo se vería un código real para enviar un mensaje. Probablemente quieres implementar el API usando el menor número de líneas posible. ¿Cómo te parece lo siguiente?
<?php

$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

?>
¿Interesante? Si eso es todo lo que necesitas, simplemente descarga el Kit para principiantes de mensajes de texto PHP, mira los comentarios en el código, ejecuta send-sms.php y listo.

Kit para principiantes para mensajes de texto PHP

Descargar Kit para principiantes de mensajes de texto PHP
El kit para principiantes contiene código suficiente para invocar funciones API y manejar callbacks.

Para usuarios avanzados

Si eres un poco más avanzado, tal vez te gustaría ver propiamente la clase que puede manejar la solicitud:
<?php

class MyCoolSMS {

    function __construct() {
    
        $this->username = 'xxx'; //your username here...
        $this->password = 'yyy'; //your password here...
        $this->endpoint = 'http://www.my-cool-sms.com/api-socket.php';
    }

    public function sendSms($number, $message, $senderid='MyNumber') {
    	
        return($this->request(json_encode(array(
            'username' => $this->username,
            'password' => $this->password,
            'function' => 'sendSms',
            'number' => $number,
            'senderid' => $senderid,
            'message' => $message
        ))));
        
    }
    
    public function getDeliveryReport() {}
    
    public function getBalance() {}
    
    //add more functions as you please...
    
    private function request($oRequest) {
    
        $oCurl = curl_init($this->endpoint);
        curl_setopt($oCurl, CURLOPT_POST, 1);
        curl_setopt($oCurl, CURLOPT_POSTFIELDS, $oRequest);
        curl_setopt($oCurl, CURLOPT_RETURNTRANSFER, 1);
        
        if(curl_errno($oCurl) == 0) {
            $oResponse = json_decode(curl_exec($oCurl));
            if(!is_object($oResponse)) {
                $oResponse = $this->getError('001', 'Bad Response');
            }
        } else {
            $oResponse = $this->getError(curl_error($oCurl));
        }		
    
        curl_close($oCurl);
        
        return $oResponse;
    
    }
	
    private function getError($error = '000', $description = NULL) {

        return json_encode(array(
            'success' => false,
            'error' => $error,
            'description' => $description,
        ));
        
    }

}

?>
Guarda el código anterior en un archivo llamado MyCoolSMS.php y empieza a usarlo así:
<?php

require_once('MyCoolSMS.class.php');

$oMyCoolSMS = new MyCoolSMS();
$oResponse = $oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

if($oResponse->success) {
    //Great, it worked!
    print_r($oResponse);
} else {
    //Oops, Something went wrong...
    print_r($oResponse);
}

?>

¡Sigue adelante!

Ahora demos un vistazo a la documentación de función y callback API.
¿Olvidamos algo? ¿Tienes preguntas? ¿Tienes alguna sugerencia o algo que deberíamos agregar aquí? Si así es, háznoslo saber!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Français
Nederlands
Polski
Português
Руccкий
繁体中文