Tabla de Contenidos

Resumen

Esta documentación describe como integrar la HTTP API de SoySMS.com con aplicaciones desarrolladas por terceros. Enviar SMS por medio de esta interfaz es simple y además muy fácil de integrar con aplicaciones escritas casi con cualquier lenguaje de programación. Los SMS se envían a nuestro servidor de la misma forma en la que se envían por POST desde un formulario web o simplemente escribir la URL en un navegador web (GET).

Integrando sus aplicaciones

La HTTP API de SoySMS.com admite ambos métodos de envío de parámetros tanto HTTP GET como HTTP POST. Para usar la HTTP API de SoySMS.com debe estar registrado en soysms.com, para más información visite http://www.soysms.com

URL de la HTTP API

Todas las peticiones deberán ser enviadas a la siguiente URL:

URL HTTP API Descripción
soysms.com/api URL principal
soysms.com/api/send URL para enviar el mensaje
soysms.com/api/status URL para comprobar el estado del mensaje
soysms.com/api/balance URL para comprobar el credito disponible
soysms.com/api/task URL para programar el envio de sms
soysms.com/api/checktask URL para comprobar el estado del mensaje programado
soysms.com/api/deltask URL para eliminar un envío programado

Realizar envíos sms

Parámetro Nombre Descripción Ejemplo
U User Name Email que usa para acceder a su cuenta usuario@dominio.com
P Password Contraseña de su cuenta password
D Destination Address Número de teléfono del destinatario con el código internacional. El código internacional debe ir entre parentesis (34)666111222
M Message Mensaje que desea enviar. Por favor llámame…
S Source Address Remitente personalizado, máximo 11 caracteres alfanumericos o 16 numéricos. Si se omite este parámetro se enviará el mensaje con el remitente que se registró en la plataforma. SoySMS ó 447973452378 ó 2527

Respuesta de envío de sms

La HTTP API retornará una cadena con la siguiente estructura:

[valid|invalid] [ok|failure] [error_num|msgid]

  • Ejemplo de una respuesta satisfactoria:

  • HTTP Header: 200 OK
  • Content: valid ok 1352138611

  • Ejemplo de respuestas con error:

  • HTTP Header: 200 OK
  • Content: invalid failure err_1089

Consultar estado de envío de sms

Parámetro Nombre Descripción Ejemplo
U User Name Email que usa para acceder a la cuenta usuario@donimio.com
P Password Contraseña de la cuenta password
MSGID Message ID Valor retornado cuando el envío del sms ha sido satisfactorio 135232188

Respuesta del servidor (Comprobar estado de envío programado)

La HTTP API retornará una cadena con la siguiente estructura si la respuesta ha sido satisfactoria:

[MSGID:numero] [MOVIL:teléfono] [ENVIO:fecha_hora] [RECEPCION:fecha_hora]

  • Ejemplo de una respuesta satisfactoria:

  • HTTP Header: 200 OK
  • Content: MSGID:3202395494 MOVIL:(34)666111222 ENVIO:2011-01-24 11:15:01 RECEPCION:2011-01-24 11:15:30

Eliminar envío programado

Parámetro Nombre Descripción Ejemplo
U User Name Email que usa para acceder a la cuenta usuario@donimio.com
P Password Contraseña de la cuenta password
MSGID Message ID Valor retornado cuando el mensaje ha sido programado correctamente 1034

Script PHP de ejemplos

Los siguientes script han sido realizados con php 5 con la librería libcurl instalado en el servidor.

Enviar SMS

URL: http://www.soysms.com/api/send 

<?php
function send_params($param) {
    $URL = "http://www.soysms.com/api/send";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $URL);
    curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT']);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    $retuned_data = curl_exec($ch);
    curl_close($ch);
    return $retuned_data;
}
 
$msg = "SoySMS is distributed in the hope that it will be useful";
$sa = "SoySMS";
$da = "(34)666111222";
$us = "usuario@dominio.com";
$pa = "password";
$PARAM = "U=$us&P=$pa&D=$da&M=$msg&S=$sa";
$resultado = send_params($PARAM);
echo $resultado;
?>

Consultar envío SMS

URL: http://www.soysms.com/api/status 

<?php
function send_params($param) {
    $URL = "http://www.soysms.com/api/status";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $URL);
    curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT']);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    $retuned_data = curl_exec($ch);
    curl_close($ch);
    return $retuned_data;
}
$us = "usuario@dominio.com";
$pa = "password";
$si = "135232188";
$PARAM = "U=$us&P=$pa&MSGID=$si";
$resultado = send_params($PARAM);
echo $resultado;
?>

Consultar créditos disponibles

URL: http://www.soysms.com/api/balance 

<?php
function send_params($param) {
   $URL = "http://www.soysms.com/api/balance";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $URL);
    curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT']);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    $retuned_data = curl_exec($ch);
    curl_close($ch);
    return $retuned_data;
}
$PARAM = "U=usuario@dominio.com&P=password";
$resultado = send_params($PARAM);
echo $resultado;
?>

Programar envíos SMS

URL: http://www.soysms.com/api/task 

<?php
function send_params($param) {
    $URL = "http://www.soysms.com/api/task";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $URL);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    $retuned_data = curl_exec($ch);
    curl_close($ch);
    return $retuned_data;
}
$msg = "Contando con un equipo cualificado y con grán experiencia";
$sa = "SoySMS";
$da = "(34)666111222";
$us = "usuario@dominio.com";
$pa = "password";
$ti = "2011-01-14 11:15:00";
$PARAM = "U=$us&P=$pa&D=$da&M=$msg&S=$sa&T=$ti";
$resultado = send_params($PARAM);
echo $resultado;
?>

Consultar estado de envío programado

URL: http://www.soysms.com/api/checktask 

<?php
 function send_params($param) {
    $URL = "http://www.soysms.com/api/checktask";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $URL);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    $retuned_data = curl_exec($ch);
    curl_close($ch);
    return $retuned_data;
}
$us = "usuario@dominio.com";
$pa = "password";
$si = 1031;
$PARAM = "U=$us&P=$pa&MSGID=$si";
$resultado = send_params($PARAM);
echo $resultado;
?>

Eliminar envío programado

URL: http://www.soysms.com/api/deltask 

<?php
function send_params($param) {
    $URL = "http://www.soysms.com/api/deltask";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $URL);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    $retuned_data = curl_exec($ch);
    curl_close($ch);
    return $retuned_data;
}
$us = "usuario@dominio.com";
$pa = "password";
$si = 1034;
$PARAM = "U=$us&P=$pa&MSGID=$si";
$resultado = send_params($PARAM);
echo $resultado;
?>

Recibir variables del servidor con el estado del envío

URL: http://www.midominio.com/request.php 

<?php
 
if (isset($_POST["delivery_status"])) {
    $dstatus = $_POST["delivery_status"];
 
    /**
     * Hacemos algo con los datos recibidos y devolvemos “ok” 
     */
    $dstatus = explode(" ", $dstatus);
    $msgid = $dstatus[1];
    $status = $dstatus[3];
    $date_receipt = $dstatus[5] . " " . $dstatus[6];
    echo "ok";
}
?>

Respuestas de error

ERROR DESCRIPCIÓN
err_1085 Unsent message
err_1086 Message sent, can not be deleted
err_1087 Message ID not exists
err_1088 Message ID can not be empty
err_1089 Invalid Username or Password
err_1090 Destination not recognised
err_1091 Source address not recognised
err_1092 Message can not be empty
err_1093 Invalid Destination or Destination not Covered
err_1094 Not Enough Credit
err_1095 System Error, Please Retry
err_1096 Request Error, Do not Retry
err_1097 Invalid Timestamp format