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"
}
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."
}
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);
InputStream body = request.getInputStream();
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!');
?>
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,
));
}
}
?>
<?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);
}
?>
