API HTTP-XML: programar SMS

sdk-httpxml-a

1. Descripción

El Interfaz HTTP-XML para programar mensajes te permite enviar mensajes prácticamente desde cualquier plataforma.

Solo tienes que integrar la llamada a una URL en el lenguaje de programación que estés utilizando.

Podrás enviar mensajes desde una página Web con un simple formulario, una aplicación gráfica en Windows, un script en linea de comandos en Linux, etc...

La llamada a la URL se hace pasando un parámetro con la trama XML completa en la que se especifica los datos de autenticación y los mensajes a enviar.

2. Documentación

URL:

https://www.descomsms.com/AP/descomMessage.servlet.Servlet

 

Programación de envío

Para poder enviar mensajes, deberás acceder al servidor seguro, a la URL arriba indicada
proporcionando el parámetro xml con la trama XML en el formato más abajo especificado en esta documentación.

Toda petición de envío tiene como respuesta un documento XML con el resultado de la operación realizada.

Parámetros POST:

Nombre Descripción
xml Trama XML con los datos de autentificación y acciones a realizar

 

Estructura básica XML de petición:

Etiqueta Raiz: <TXEnvio>

Esta etiqueta debe envolver todos los datos XML de la llamada.

<TXEnvio>  Tus datos....  </TXEnvio>

 

Definición de trama de autentificación:

Deberá pasar en primer lugar el nodo de autentificación, donde figurarán sus credenciales en Descom SMS

<Autentificacion>
    <Usuario>login usuario</Usuario>
    <Passwd>contraseña de usuario </Passwd>
    <Idcli>código de cliente</Idcli>
    <Remitente>texto remitente</Remitente>
</Autentificacion>

Donde:

Nombre
Parámetro
Descripción Posibles Valores Tipo de
Dato
Usuario Identificador de Usuario en Descom SMS Nombre de usuario Alfanumérico en Hexadecimal
Passwd Contraseña de acceso Contraseña Alfanumérico en Hexadecimal
IdCli Identificador de Cliente en Descom SMS Identificador Numérico
Remitente* Remitente personalizado para los mensajes Texto remitente hasta 11 caracteres Alfanumérico en Hexadecimal

* Puede personalizar el remitente de los SMS, con su número de móvil autorizado, en formato no internacional (ej: 111222333), o con una cadena de texto; en este caso, consulte antes con Esta dirección de correo electrónico está siendo protegida contra los robots de spam. Necesita tener JavaScript habilitado para poder verlo. para configurar su remitente.

 

Definición de trama de programación de mensajes:

Para la programación de mensajes deberás enviar en la trama XML el nodo <mensajes> según la estructura definida a continuación.
La programación se añade mediante el nodo <programacion> y definiendo sus atributos. 

<Mensajes  idenvioext="xxxxxxxx">
<programacion   progfini="ddmmyyyy" proghora="hhmm" idprog="nnnnn"
            progperiodo="repetición de programacion[1,D,S,M,A]"
            prognombre="nombre de programacion (en hexadecimal)"
            progavisar="avisar por correo[1,0]"
            progffin="fecha fin [ddmmyyyy]"
            progds="dias de la semana[1,2,3,4,5,6,7]"
            progdm="dia del mes[1..31]"
            progmes="mes[1..12]" />
    <EmailNot>n</EmailNot>
    <MaxSMS>n</MaxSMS>
    <Total>nnn</Total>
    <Control>n</Control>
    <Mensaje>
        <ID>xx</ID>
        <Destino>nnnnnnnnnn</Destino>
        <Texto>xxxxxxxxxxxxxxxxxxx</Texto>
        <Remitente></Remitente>
    </Mensaje>
    <Mensaje>
        <ID>xx</ID>
        <Destino>nnnnnnnnnn</Destino>
        <Texto>xxxxxxxxxxxxxxxxxxx</Texto>
        <Remitente></Remitente>
    </Mensaje>
    ...............................
</Mensajes>

 

Donde:

Parámetro Requerido Descripción Posibles Valores Tipo de
Dato
idenvioext No

Identificador del envío.
Este identificador sirve para identificar un envío en el servidor.
El envío de bloques de mensajes con el mismo idenvioext hará que todos los mensajes se agrupen en un mismo envío.
Si se deja en blanco se genera uno automáticamente en el servidor.

Cadena alfanumérica de hasta 25 caracteres Hexadecimal
progfini No Fecha inicial de la programación. Si no se envía se toma la fecha de hoy. Fecha en formato: ddmmyyyy  Numérico 
proghora Hora de la programación Hora en formato: hhmm  Numérico 
idprog No
Identificador de una programación anterior.
Se utiliza para poder añadir más mensajes a una programación ya dada de alta con anterioridad.
  Numérico
progperiodo No
Periodo de repetición de la programación 1-> Sólo una vez
D-> Diario
S-> Semanal
M-> Mensual
A-> Anual 
 
prognombre No
Nombre que le quieras dar a la programación. Si lo dejas en blanco se da un nombre de forma automática.   Hexadecimal
progavisar No
Avisar por correo electrónico cuando se realice el envío. 1 -> Se envía aviso
2 -> No se envía aviso
Nunmérico
progffin No
Fecha fin de programación. Para programaciones periódicas, indica la fecha a partir de la cual no se envía más la programación. Fecha en formato: ddmmyyyy   Nunmérico 
progds No
Para programaciones Semanalaes.
Días de la semana para enviar la programación. Puedes seleccionar varios días de la semama.
Ejemplos: Lu, Mi, Vie -> 135      Sa, Do -> 67    Lu,Ma,Mi,Ju,vi -> 12345
Si lo dejas en blanco  se envía todos los dias.

Lunes->1, Martes->2, Miércoles->3, Jueves->4, Viernes->5, Sábado->6, Domingo->7

 
 
progdm No Para programaciones Mensuales.
Día del mes para enviar la programación 
Del 1 a 31 según mes. Numérico
progmes No
Para programaciones Anuales.
Mes del año para enviar la programación. 
Del 1 al 12.
 
Numérico 
EmailNot No

Nos permite recibir por correo los reportes de entrega de los mensajes

1 -> para recibir el reporte de los envíos. 
Déjalo en blanco para no recibir reportes.
Numérico
MaxSMS No Número máximo de SMS que se enviarán por cada uno de los mensajes
Si se deja en blanco no hay límite.
1,2,3....
0 - sin límite 
Numérico
Total Número total de mensajes en el envío
Numérico
Control Control de mensajes dependiendo del saldo 0 - Si saldo es insuficiente, no enviar ningún mensaje
1 - Si saldo es insuficiente, enviar tantos mensajes como saldo exista
Numérico
Por cada mensaje:
   
ID Identificador de cada mensaje en la trama  1,2,3,...  Numérico 
destino Número de teléfono del destinatario del mensaje Teléfono en formato:
acceso internacional + cod. país + teléfono Ejemplo: 0034111222333
Numérico
texto Texto del mensaje.
Si el mensaje tiene más de 160 caracteres se dividirá en varios SMS según parámetro MaxSMS
Texto del mensaje en formato hexadecimal Hexadecimal

Remitente No Remitente personalizado específico para este mensaje. Si se deja en blanco se utilizará el remitente principal del nodo de autentificación   Hexadecimal

 

Ejemplo de trama XML para programar mensajes:

Programación de 1 mensaje para las 16:30 de hoy.

<TXEnvio>
<Autentificacion>
    <Usuario>xxxxxxxxxxxxx</Usuario>
    <Passwd>xxxxxxxx</Passwd>
    <Idcli>99</Idcli>
    <Remitente>xxxxxxxx</Remitente>
</Autentificacion>
<Mensajes  idenvioext="123456ABC">
<programacion proghora="1633"/>
    <EmailNot>1</EmailNot>
    <MaxSMS>0</MaxSMS>
    <Total>1</Total>
    <Control>1</Control>
    <Mensaje>
        <ID>1</ID>
        <Destino>0034111222333</Destino>
        <Texto>4F74726120507275656261</Texto>
    </Mensaje>
</Mensajes>
</TXEnvio>

Programación de 1 mensaje periódico semanal los lunes y viernes  para las 8:00.

<TXEnvio>
<Autentificacion>
    <Usuario>xxxxxxxxxxxxx</Usuario>
    <Passwd>xxxxxxxx</Passwd>
    <Idcli>99</Idcli>
    <Remitente>xxxxxxxx</Remitente>
</Autentificacion>
<Mensajes  idenvioext="123456ABC">
<programacion proghora="0800" progperiodo="S" progds="15" />
    <EmailNot>1</EmailNot>
    <MaxSMS>0</MaxSMS>
    <Total>1</Total>
    <Control>1</Control>
    <Mensaje>
        <ID>1</ID>
        <Destino>0034111222333</Destino>
        <Texto>4F74726120507275656261</Texto>
    </Mensaje>
</Mensajes>
</TXEnvio>

Programación de 1 mensaje de cumpleaños anual el 15 de agosto a las 9:00

<TXEnvio>
<Autentificacion>
    <Usuario>xxxxxxxxxxxxx</Usuario>
    <Passwd>xxxxxxxx</Passwd>
    <Idcli>99</Idcli>
    <Remitente>xxxxxxxx</Remitente>
</Autentificacion>
<Mensajes  idenvioext="123456ABC">
<programacion proghora="0900" progperiodo="A" progmes="8" progdm=15 />
    <EmailNot>1</EmailNot>
    <MaxSMS>0</MaxSMS>
    <Total>1</Total>
    <Control>1</Control>
    <Mensaje>
        <ID>1</ID>
        <Destino>0034111222333</Destino>
        <Texto>4F74726120507275656261</Texto>
    </Mensaje>
</Mensajes>
</TXEnvio>

 

 

Respuesta de Programación.

Estructura básica XML de respuesta:

Etiqueta Raiz: <RXEnvio>

Esta etiqueta debe envolver todos los datos XML de la llamada.

<RXEnvio>  Tus datos....  </RXEnvio>

 

Definición de trama de autentificación:

Todas las peticiones serán respondidas con un documento XML, conteniendo la siguiente estructura.
En primer lugar recibirás el resultado de tu autentificación Descom SMS.

<Autentificacion>    
  <Usuario>xxxxxxxxxxxx</Usuario>
  <Resultado>1</Resultado>
  <Comentario>Autentificacion satisfactoria.Remitente Aceptado</Comentario>
  <Saldo>xxxxx</Saldo>
</Autentificacion>

Donde:

Nombre
Parámetro
Descripción Posibles Valores Tipo de
Dato
Usuario Identificador de Usuario en Descom SMS Nombre de usuario Alfanumérico en Hexadecimal
Resultado Resultado de la autentificación en Descom SMS 1-> Autentificación correcta
0-> Fallo en la autentificación 
Numérico
Comentario Texto descriptivo del resultado de la autentificación
Alfanumérico
Saldo Saldo actual en Descom SMS de tu cuenta
Numérico

 

Definición de trama de respuesta de mensajes programados:

Para los mensajes enviados, recibirás la información del resultado de los envío en el nodo <mensajes> según la estructura definida a continuación.

 
<Mensajes idenvioext="xxxxxxxxxx" idenviodm="0" total_mensajes="nn" total_ok="nn" total_error="nn" total_creditos="nn" total_sms_ok="nn" total_sms_error="nn">
    <programacion idprog="555" progok="1" progerr="0" progresultado="1"/>
</Mensajes>

Se debe de consultar el nodo <programacion> para ver el resultado de la programación.

Donde:

Parámetro Descripción Posibles Valores Tipo de
Dato
idprog

Identificador numérico de la programación.
Este es el identificador proporcionado por Descom SMS para poder usarlo a posteriori a la hora de obtener información acerca de esta programación.

  Numérico
progok Número total de mensajes programados correctamente.
Numérico
progerr Número total de mensajes no programados por contener algún error.
  Numérico
progresultado Resultado de la programación 1-> Programación correcta
0-> Programación no realizada
Numérico

 

Ejemplo de trama de respuesta XML para 3 mensajes programados:

<?xml version="1.0" encoding="ISO-8859-1"?>
<RXEnvio>
<Autentificacion>
  <Usuario>7065706f7465</Usuario>
  <Resultado>1</Resultado>
  <Comentario>Autentificacion satisfactoria.Remitente Aceptado</Comentario>
  <Saldo>8888</Saldo>
</Autentificacion>
<Mensajes idenvioext="313233343536373839" idenviodm="0" total_mensajes="3" total_ok="3" total_error="0" total_creditos="0" total_sms_ok="0" total_sms_error="0">
 <programacion idprog="555" progok="3" progerr="0" progresultado="1"/>
</Mensajes>
</RXEnvio>

Puedes consultar y modificar cualquier progrmación a través de nuestra API HTTP-XML para Mensajes Programados.

3. Ejemplos

Descarga nuestros ejemplos: ejemplo en PHPejemplo en ASP.

4. Gráfico

Enviar-SMS-InterfazHTTP