Integración HTTP GET
Versión 2.2
Índice
Introducción Pag: 3
Plataforma Técnica Pag: 4
Petición de envío de SMS Pag: 4
Respuestas a peticiones HTTP Pag: 5
Anexo A: Acuses de recibo Pag: 6
Anexo B: Conjunto de caracteres GSM7 Pag: 7
2
Introducción
La plataforma http server permite al usuario enviar mensajes a través de esta plataforma. Para poder acceder a tus
estadísticas y datos de facturación puedes acceder a la web https://msjes.servidoresymasivos.com con tus datos de
acceso.
La comunicación entre el cliente no se realizará a través de ningún API proporcionado por la empresa, sino que
simplemente se realizará una comunicación HTTP, con algunos parámetros a la URL indicada. Este proceso se detalla
a continuación.
3
PLATAFORMA TÉCNICA
Petición de envío de SMS
Para poder enviar SMS a través de la plataforma, el cliente nos lanzará una petición a la web indicada posteriormente,
usando ciertos parámetros (texto a enviar, número de teléfono destinatario, remitente, etc.), y nosotros le devolveremos
una respuesta de confirmación de que todo ha ido bien, o una respuesta de error en caso contrario.
A continuación se detallarán las opciones de configuración disponibles, la URL a la que se debe llamar, y los
parámetros que admite.
Para generar la URL el cliente deberá hacer una llamada GET a la siguiente dirección:
https://msjes.servidoresymasivos.com/Api/get/send.php
Pasándole una serie de parámetros:
text: Texto del mensaje. Como máximo puede tener 160 caracteres si no se especifica que el mensaje sea
multiparte (ver parámetro "parts"). El texto tiene que estar codificado en UTF-8
to: Número de teléfono móvil destinatario del mensaje. Debe incluir el prefijo (Ej: En España 34666666666).
Este campo permite indicar multiples destinatarios, para ello hay que separar los números de teléfono por el
un espacio (Ej: 34666666666 34666666667 34666666668)
from: Texto del Remitente, esta etiqueta se compondrá de 15 números o 11 caracteres alfanuméricos.
username: Usuario proporcionado por la empresa.
password: Clave de acceso del cliente en [email protected].
coding: Los posibles valores son "gsm", "gsm-pt" y "utf-16". El valor por defecto es "gsm". El número máximo
de caracteres para mensajes normales es de 160 para la codificación GSM7, 155 para la codificación GSM-
PT y 70 para la codifcación UCS2 (UTF16). El número máximo de caracteres para mensajes concatenados es
de 155 para la codificación GSM7, 149 para la codificación GSM-PT y 67 para la codifcación UCS2 (UTF16).
dlr-mask(opcional): Para recibir confirmaciones de entrega, dejar el parámetro en 8. En caso de no necesitar
confirmaciones, no es necesario especificar este parámetro.
fSend (opcional): Fecha de envío del mensaje. Si se necesita enviar mensajes programados se puede
especificar la fecha de envío indicando la fecha en formato YYYYmmddHHiiss (Ej: 20130215142000 sería el
15 de febrero de 2013 a las 14:20 UTC). La fecha se tiene que especificar en tiempo UTC (GMT+0). No se
podrán programar envíos mas tarde de los 30 días siguientes. En caso de envío inmediato no se tiene que
especificar este parámetro.
fExp (opcional): Fecha de expiración del mensaje en formato UTC. La fecha se tiene que especificar en
tiempo UTC (GMT+0). Formato YYYYmmddHHiiss. Ejemplo: 20130215142000 sería el 15 de febrero de 2013
a las 14:20:00.
parts (opcional): Indica el número máximo de partes en que se dividirá el mensaje para su envío. Esta
variable tiene valor 1 por defecto, por lo que si no se especifica y se envía un mensaje de mas de 160
caracteres para codificación 0, el mensaje fallará. Hay que tener en cuenta que los mensajes concatenados
solo pueden tener 153 caracteres por parte y que cada parte se tarifica como un envío. El servidor sólo
utilizará el mínimo de partes necesarias para realizar el envío del mensaje, aunque el número de partes
especificado sea superior al necesario. En caso de que el número de partes sea inferior al necesario para el
envío del texto, el envío fallará con el error 105.
trsec (opcional): Los valores posibles son 1 y 0. Con el valor 0 el servidor no modifica ningún carácter del
mensaje, este es el valor por defecto. Con el valor 1 el servidor se encarga de modificar los caracteres
comunes no validos en GSM7 a caracteres validos con la siguiente tabla de traducción: "á"=>"a", "í"=>"i",
"ó"=>"o", "ú"=>"u", "ç"=>"Ç", "Á"=>"A", "Í"=>"I", "Ó"=>"O", "Ú"=>"U", "À"=>"A", "È"=>"E", "Ì"=>"I", "Ò"=>"O",
"Ù"=>"U", "o"=>"", "a"=>"", "Õ"=>"O", "õ"=>"o", "â"=>"a", "ê"=>"e", "î"=>"i", "ô"=>"o", "û"=>"u", "Â"=>"A",
"Ê"=>"E", "Î"=>"I", "Ô"=>"O", "Û"=>"U", "ã"=>"a", "Ã"=>"A".
reference (opcional): Referencia del envío. Si no se especifica, se generará una referencia automáticamente
cada mes con la siguiente nomenclatura: API_SMS_yyyy_mm siendo yyyy el año actual y mm el mes actual.
tags (opcional): Tags separados por espacio. Ej: tag1 tag2
Incluir URL de baja:
Para generar una URL de baja hay que añadir: {UNSUB_URL} dentro del mensaje.
Ejemplo de llamada:
https://msjes.servidoresymasivos.com/Api/get/send.php?username=tu_user&password=tu_pass&to=3465467445+3462
4
7455334+34627545454&text= Prueba+de+envio&from=TEST&coding=0&dlr-mask=8
La clave de acceso (password) y el código del cliente (username) serán proporcionados por la empresa. Hay que
comentar que con objeto de aumentar la seguridad del sistema, el cliente deberá indicar la IP desde donde se va a
conectar, solo se permitirán envíos de la IP indicada por el cliente.
Como se observa, la respuesta que devuelve la plataforma ante una petición de envío de SMS tendrá la siguiente
sintaxis:
0: Accepted for delivery. ID 53337
En caso de error se devolverá una descripción del motivo del error.
5
Respuestas a peticiones HTTP
La sintaxis de las respuesta tiene el formato:
{codigo de error}: {mensaje descriptivo}. ID {identificador envío}
El identificador solo se entrega en caso de que la petición haya tenido éxito. Ejemplos de respuesta serian:
0: Accepted for delivery. ID 53337
105: Text message missing.
Las posibles respuestas son:
Código Descripción
0 Accepted for delivery
101 Internal Database error
102 No valid recipients
103 Username or password unknown
104 Text message missing
105 Text message too long
106 Sender missing
107 Sender too long
108 No valid Datetime for send
109 Notification URL incorrect
110 Exceeded maximum parts allowed or incorrect number of parts
111 Not enough credits
6
Anexo A: Acuses de recibo
Si se desean recibir los acuses de recibo en tiempo real se deberá especificar la variable “dlr-url” con la URL del cliente
donde quiere que se notifique el estado del envío.
El funcionamiento consiste en especificar en cada petición http la URL donde se desea que realice una petición de
nuestro servidor cuando se reciba una notificación por parte de la operadora. Para ello el cliente debe disponer de un
servidor http capaz de recibir esas notificaciones.
Nuestro servidor enviara las variables por el método GET tal como el cliente quiera, para ello en la URL que nos envía
tiene que poner el nombre de la variable seguido de un carácter de escape que contendrá el valor, los caracteres de
escape tienen la forma del carácter “%” seguido de una letra. Este seria un ejemplo de URL:
http://mi.server.com/notifica.php?remitente=%p&tel=%P&estado=%d
Estos son los caracteres de escape definidos:
%i Identificador de [email protected] que se entregó cuando se hizo el envío.
%d Valor del acuse de recibo.
%p El remitente del SMS.
%P El número de teléfono del receptor del mensaje SMS.
%t Fecha del envío del mensaje con formato "YYYY-MM-DD HH:MM", e.j., "2015-09-21 14:18".
%c coste del mensaje.
%s estado (REJECTD, DELIVRD, EXPIRED, DELETED, UNDELIV, ACCEPTD, UNKNOWN, RECEIVED).
%y fecha del DLR del mensaje con formato "YYYY-MM-DD HH:MM", e.j., "2020-09-21 14:19".
%n número de parte (mensajes concatenados).
%j código de error, e.j., 89 cuando el mensaje es rechazado por falta de saldo.
El valor %d es el que nos devolverá el estado final del envío, los valores posibles son:
1: El mensaje ha sido entregado al destinatario.
2: El mensaje no se ha podido entregar al destinatario.
4: El mensaje ha sido entregado al SMSC, es una notificación intermedia, no un resultado final
16: No se ha podido entregar a la operadora final
Para explicar mejor el proceso, a continuación se da un ejemplo de cómo seria el envío de un sms y la recepción de su
acuse de recibo.
En primer lugar enviamos el sms con la variable dlr-url donde indicaremos la URL donde queremos recibir la
notificación de entrega, añadiremos a esta URL nuestro identificador de envío para poder identificar inequívocamente
cuando lo recibamos. La url final para la notificación seria:
http://mi.server.com/notifica.php?idenvio=123&remitente=%p&tel=%P&estado=%d
Por tanto la llamada final que deberíamos hacer para enviar el SMS sería:
https://msjes.servidoresymasivos.com/Api/get/send.php?username=tu_user&password=tu_login&to=34666555444+346
66555333+34666555222&text=Prueba+de+envio&from=TEST&coding=0&dlr-mask=8&dlr-
url=http%3A%2F%2Fmi.server.com%2Fnotifica.php%3Fidenvio%3D7584%26remitente%3D%25p%26tel%3D%25P%2
6estado%3D%25d
Suponiendo que todos los mensajes puedan ser entregados, recibiremos al script notifica.php tres peticiones con el
estado=1, remitente=TEST, idenvio=7584 y el número de teléfono correspondiente.
7
Anexo B: Conjunto de caracteres GSM7
Conjunto de caracteres básico
0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70
0x00 @ ? SP 0 ¡ P ¿ p
0x01 £ _ ! 1 A Q a q
0x02 $ ? " 2 B B b r
0x03 ¥ ? # 3 C S c s
0x04 è ? ¤ 4 D T d t
0x05 é ? % 5 E U e u
0x06 ù ? ? 6 F V f v
0x07 ì ? ' 7 G W g w
0x08 ò ? ( 8 H X h x
0x09 Ç ? ) 9 I Y i y
0x0A LF ? * : J Z j z
0x0B Ø ESC + ; K Ä k ä
0x0C ø Æ , < L Ö l ö
0x0D CR æ - = M Ñ m ñ
0x0E Å ß . > N Ü n ü
0x0F å É / ? O § o à
Extensión del conjunto de caracteres básico, estos caracteres ocupan dos posiciones
0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70
0x00 |
0x01
0x02
0x03
0x04 ^
0x05 €
8
0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70
0x06
0x07
0x08 }
0x09 {
0x0A FF
0x0B SS2
0x0C [
0x0D CR2 ~
0x0E ]
0x0F \
