Especificaciones de la Interfaz HTTP para envı́o de

SMS, landings web y firma de documentos

Especificaciones de la Interfaz
HTTP para envı́o de SMS,
landings web y firma de documentos
Altiria TIC, S.L.U.
Versión: 2.9

Copyright © Altiria TIC 2023

Este documento sólo puede ser reproducido por completo o en parte, almacenado, recuperado o transmitido por medios
electrónicos, mecánicos, fotocopiado o cualquier otro medio con el consentimiento previo de los autores de acuerdo con
los términos que estos indiquen.
Historial de cambios

Versión Cambios
Eliminamos en la documentación la posibilidad de login con
dominio, usuario/e-mail y contraseña para todos los comandos.
2.9 Para las cuentas nuevas el login se realiza por apiKey y apiSe-
cret. Para cuentas antiguas se sigue permitiendo el login con
usuario/e-mail y password.

Nuevo parámetro urlAck en el comando “sendsms” (2.1).

Nuevo código de error 041 relativo a la validación correcta del
2.8 parámetro urlAck.
Se elimina el parámetro “disableVerified” al terminar el soporte
a los sms verificados.

Se permite la autentificación mediante los parámetros “apiKey”

2.7 y “apiSecret” en los comandos “sendsms” (2.1), “getcredit” (2.2),
“certpdffile” (2.8) y “checkpdffile” (2.9).

Actualizaciones menores en diversos apartados.

2.6 Se añaden los ejemplos de uso mediante librerı́as (2.10.1).

Se añade el parámetro opcional “multiSig” al comando “certPdf-

File” para definir más de un firmante por documento ası́ como la
posición de la firma (2.8.1).
2.5 Se añade la sección 2.8.2 para detallar todos los aspectos relativos
a la ubicación de las firmas en el documento.
Se añaden los códigos de error 012, 013, 030, 031 y 032 (sec-
ción 2.8.5).

Se añaden los parámetros opcionales “title” y “forwardEmail” al

comando “certpdffile” para la firma de documentos (2.8.1).
2.4 Se actualiza la información devuelta en el comando “checkpdffile”
(2.8.4).
Se actualizan los ejemplos de programación (sección 2.10).

Se añaden dos nuevas secciones sobre la firma de documentos

2.3 (2.8) y la actualización de su estado (2.9).
Se actualizan los ejemplos de programación (sección 2.10).

Se añade el parámetro opcional “certDelivery” al comando

“sendsms” para solicitar la certificación de la entrega del SMS
enviado mediante un documento digital con sello certificado de
2.2 tiempo (sección 2.4.1).
Se añade una nueva notificación de estado “CERT(url)” para
recibir la URL de acceso al documento del certificado de entrega
(cuadro 2.7).

1
Historial de cambios

Versión Cambios
Se añade una nueva sección sobre los enlaces a web móvil (2.6) y
una subsección sobre la parametrización de webs móviles (2.6.1).
Se actualiza la información del parámetro “msg” y se añaden los
2.1 parámetros “landing”, “params” y “webParams” en el cuadro 2.1,
todo en relación a los enlaces a web móvil (sección 2.6).
Se añaden los códigos de error 035, 036, 037, 038 y 039 (sec-
ción 2.4.3).

Se añaden los códigos de error 018 y 019 (sección 2.4.3).

Se admite la autentificación sin el parámetro “domainId” en caso
2.0 de que el login sea un email.
Se actualizan los ejemplos de programación (sección 2.10).

Se añade dos nuevos estados de confirmación de entrega:

1.16 “ERROR 114” y “ERROR 115” (cuadro 2.7).
Se actualizan los ejemplos de programación (sección 2.10).

Se modifica la lista de caracteres válidos para el remitente de

1.15 los mensajes ası́ como la gestión de los caracteres inválidos en el
parámetro “senderId” (sección 2.4.1).

Se reorganiza el documento para agrupar la información de forma

más clara.
El parámetro “idAck” de los comandos de envı́o pasa a admitir
hasta 20 caracteres en lugar de 10 (sección 2.4.1).
Se añade el código de error 002 (sección 2.4.3).
Se precisa la información sobre el parámetro “senderId” para
permitir el envı́o de remitentes numéricos (sección 2.4.1).
1.14 Se añade la posibilidad de enviar mensajes concatenados mediante
el parámetro “concat” (sección 2.4.1).
Se añade la posibilidad de enviar mensajes codificados en UNI-
CODE mediante el parámetro “encoding” (sección 2.4.1).
Se amplı́a la lista de caracteres permitidos para los mensajes SMS
de texto en la codificación por defecto añadiendo los caracteres
extendidos (sección 2.5.1).
Se actualizan las referencias bibliográficas del final del documento.

Se añade una referencia a la sección de preguntas frecuentes de

1.13 nuestro portal web (sección 1).

2
Historial de cambios

Versión Cambios
Se incluye un nuevo ejemplo en ASP 3.0 y se corrige una errata
en el ejemplo en PHP (sección 2.10).
Se detalla el modo de codificar los caracteres si los parámetros de
la petición se envı́an en la URL (sección 2.2).
1.12 Se añaden dos parámetros opcionales al comando “sendsms” para
permitir especificar el puerto origen y destino del SMS a enviar
(sección 2.4.1).
Se añaden nuevos códigos de error correspondientes a los nuevos
parámetros: 033 y 034 (sección 2.4.3).

3
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Índice general

1. Introducción 5

2. Descripción de la API 6
2.1. Envı́o de la petición . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Codificación de caracteres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3. Respuesta a la petición . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4. Comandos de la API de envı́o de SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4.1. Envı́o de un mensaje de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4.2. Consulta del crédito disponible . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4.3. Códigos de estado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.5. Mensajes de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.5.1. Codificación por defecto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.5.2. Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.5.3. Longitud del mensaje . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.6. Enlaces a web móvil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.6.1. Parametrización de la web móvil . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.7. Confirmación de entrega . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.8. Comandos de la API de firma de contrato online . . . . . . . . . . . . . . . . . . . . . . 20
2.8.1. Firma de un documento PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.8.2. Posicionamiento de las firmas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.8.3. Envı́o del documento PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.8.4. Consulta del estado de firma de un documento PDF . . . . . . . . . . . . . . . . 26
2.8.5. Códigos de estado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.9. Actualización del estado de firma de documentos . . . . . . . . . . . . . . . . . . . . . . 28
2.10. Ejemplos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.10.1. Envı́o de un mensaje mediante librerı́as . . . . . . . . . . . . . . . . . . . . . . . 30
2.10.2. Envı́o de un mensaje en PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.10.3. Envı́o y firma de documento PDF en PHP . . . . . . . . . . . . . . . . . . . . . . 37
2.10.4. Envı́o de un mensaje en JAVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.10.5. Envı́o y firma de documento PDF en JAVA . . . . . . . . . . . . . . . . . . . . . 45
2.10.6. Envı́o de un mensaje en VBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

4
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.10.7. Envı́o de un mensaje en .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

2.10.8. Envı́o de un mensaje en Delphi . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
2.10.9. Envı́o de un mensaje en Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2.10.10.Envı́o y firma de documento PDF en Perl . . . . . . . . . . . . . . . . . . . . . . 54
2.10.11.Envı́o de un mensaje en Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.10.12.Envı́o y firma de documento PDF en Ruby . . . . . . . . . . . . . . . . . . . . . 57
2.10.13.Envı́o de un mensaje en Python . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.10.14.Envı́o y firma de documento PDF en Python . . . . . . . . . . . . . . . . . . . . 60
2.10.15.Envı́o de un mensaje en node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.10.16.Envı́o y firma de documento PDF en node.js . . . . . . . . . . . . . . . . . . . . 63

5
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Capı́tulo 1

Introducción

En este documento se presenta la API disponible para el envı́o de mensajes cortos, landings web y
firma de documentos sobre la interfaz de Altiria a través de peticiones sobre el protocolo HTTP.
Para hacer uso de la interfaz HTTP el cliente enviará una petición HTTP POST y esperará la
respuesta del servidor.
El servicio de envı́o de mensajes cortos está disponible en muchos paises. Para conocer los paises
permitidos, las operadoras válidas en cada paı́s y las posibles restricciones geográficas (salvedades al
funcionamiento general detallado en este documento que pudieran aplicar en cada caso) se puede enviar
un correo electrónico a [email protected].
El servicio opcional de confirmación de entrega requiere que el cliente configure un servidor de
peticiones HTTP para recibir la información de confirmación (ver la sección 2.7).
Si durante la integración de la API se presentan problemas, se recomienda revisar la sección de
preguntas frecuentes ([FAQ]) de nuestro portal web.

6
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Capı́tulo 2

Descripción de la API

2.1. Envı́o de la petición

La URL sobre la que envı́ar las peticiones HTTP es https://www.altiria.net:8443/api/http
Cada petición HTTP POST enviada se corresponde con un comando de la API.
El cuerpo de cada petición HTTP está compuesto por una lista de pares [nombre,valor], según la
norma application/x-www-form-encoded.
Cada par representa un parámetro del comando. Cada comando tiene un conjunto de parámetros
diferente, como se verá a continuación. Todos ellos comparten el primer parámetro, de nombre “cmd”,
referido al tipo de comando que se está empleando.
También es posible enviar la lista de pares [nombre,valor] como parte de la cadena de caracteres
que conforma la URL de la petición POST, siguiendo el siguiente esquema:
https://www.altiria.net:8443/api/http?nombre1=valor1&nombre2=valor2&nombre3=valor3
Debido a las limitaciones en el número máximo de caracteres de la URL, dependientes de numerosos
factores, se desaconseja este método de envı́o de los parámetros.
En ningún caso se permitirán peticiones HTTP GET.

2.2. Codificación de caracteres

Los parámetros enviados en el cuerpo de la petición HTTP POST deben codificarse con el juego
de caracteres “UTF-8”. En el apartado 2.10 se dan varios ejemplos.
En caso de enviar los parámetros como parte de la URL, será preciso codificar su valor previamente
a su inclusión en la misma. Esto consiste en obtener la representación en hexadecimal en UTF-8 de
cada carácter y añadirlo a la URL con un “ %” para cada par de dı́gitos hexadecimales.
Como se ha visto la URL se compondrá a partir de varios parámetros del estilo

nombre1=valor1&nombre2=valor2&nombre3=valor3

De acuerdo a lo indicado cada uno de los valores de los parámetros deberá codificarse en UTF-8
antes de incluirlo en la URL. Por ejemplo una “ñ” se codificarı́a como “ %C3 %B1”.
Esto es especialmente necesario en los siguientes casos (se indica el carácter y su codificación en la
URL en UTF-8):

7
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

+ => %2B
% => %25
& => %26

De cualquier modo es fundamental codificar los datos de la petición según se ha detallado, de lo

contrario la interfaz HTTP podrı́a recibir caracteres incorrectos, siendo esto especialmente grave en
aquellos que conforman el mensaje corto a enviar.

2.3. Respuesta a la petición

Cada petición HTTP lleva asociada una respuesta desde el servidor HTTP de Altiria, variable en
función del comando enviado.
En los siguientes apartados se detalla la respuesta para cada comando. De todos modos, antes de
analizar la respuesta es preciso comprobar que el código de estatus devuelto por el servidor HTTP es
200, de lo contrario el resto de la respuesta no se ajustará a los patrones esperados.
Como mecanismo preventivo se recomienda establecer un tiempo máximo de espera, de modo que
si la respuesta no llega antes de su vencimiento se cierre la conexión HTTP establecida y se reintente
la petición de nuevo.
La respuesta a cada petición HTTP se remite codificada con el juego de caracteres “UTF-8”.

2.4. Comandos de la API de envı́o de SMS

A continuación se detallan los comandos disponibles en la API. Para cada comando se representa
un cuadro con los parámetros que lo componen. Cada parámetro puede ser obligatorio u opcional y en
algunos casos puede aparecer múltiples veces.
Los comandos se distinguen entre sı́ mediante el parámetro “cmd”, obligatorio en todos los casos.

2.4.1. Envı́o de un mensaje de texto

Permite enviar un mensaje corto de texto a uno o a varios teléfonos destinatarios.
Este comando tiene la lista de parámetros del cuadro 2.1.
Los datos de autentificación son los parámetros “apiKey” y “apiSecret”, gestionados desde
la sección de desarrolladores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360])).
Para enviar el mensaje a varios destinatarios basta repetir el parámetro “dest” tantas veces
como sea preciso sin sobrepasar el lı́mite máximo permitido (consultar al soporte técnico de Altiria
en [email protected]), asignándole cada vez el valor de un número de teléfono distinto (los teléfo-
nos repetidos son descartados). Se recomienda en cualquier caso no exceder de 100 destinatarios por
petición.

Nombre Valor Obligatorio

cmd ”sendsms” sı́
apiKey Código alfanumérico identificador gestionado desde la sección de desarro- sı́
lladores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).
apiSecret Clave asociada a un “apiKey” gestionada desde la sección de desarrolla- sı́
dores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).

8
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

dest Número de teléfono móvil del destinatario del mensaje. Se especificará sı́
en formato de numeración internacional sin prefijo ’00’ ni el signo ’+’. Ej:
34645852126. Es fundamental incluir el prefijo del paı́s (34 para España)
para que el mensaje llegue al destino esperado. No debe superar los 16
dı́gitos.
msg Mensaje a enviar. La lista de caracteres válidos y la longitud máxima sı́
permitida se detalla en la sección 2.5. No puede estar vacı́o (cadena
vacı́a). Se pueden añadir identificadores de web móvil para gene-
rar enlaces acortados únicos en el texto del mensaje. Consultar la
sección 2.6 para conocer más detalles sobre las webs móviles.
senderId Remitente del mensaje a enviar, autorizado por Altiria . La posibilidad no
de personalizar el remitente depende del paı́s destinatario del mensaje.
Puede tomar dos posibles valores: 1) valor alfanumérico de hasta 11
caracteres (números y letras de la “a” a la “z” tanto mayúsculas como
minúsculas excluyendo la “Ñ” y la “ñ”); 2) valor numérico de hasta
15 dı́gitos decimales comenzando por el carácter “+”. Los caracteres
inválidos serán suprimidos automáticamente. Si se pretende que
el receptor pueda responder al mensaje corto recibido se deberı́a usar
un remitente numérico (opción 2) incluyendo el prefijo de paı́s. Si no se
incluye o el valor escogido es inválido, el mensaje se enviará con el
remitente por defecto seleccionado por Altiria.
landing Número con la suma de identificadores de web móvil (si se repiten tam- no
bién suman) que se utilizan en el texto del mensaje (parámetro “msg”)
para citar una web móvil (su uso es obligatorio en este caso). Con-
sultar la sección 2.6 para conocer más detalles sobre las webs móviles.
params Número de webs móviles (de las citadas en el texto del mensaje mediante no
el parámetro “msg”) para las que se remiten valores parametrizados. Su
uso es obligatorio en caso de definir el parámetro “landing” (se debe
fijar a 0 si no hay webs parametrizadas). En caso de remitir valores para-
metrizados debe incluirse también parámetros tipo “webParams”.
Consultar la sección 2.6.1 para conocer más detalles sobre la parametri-
zación de las webs móviles.
webParams Se debe añadir para cada web móvil parametrizada el parámetro “webPa- no
rams” cualificado con el identificador de la web móvil. Define los paráme-
tros particulares de cada web. Su uso es obligatorio en caso de que
“params” sea mayor que 0. Consultar la sección 2.6.1 para conocer más
detalles sobre la parametrización de las webs móviles.
ack Solicitud de confirmación de entrega de los mensajes enviados (ver sec- no
ción 2.7). Si vale ”true” solicita confirmación de entrega de los SMS
enviados. Si adicionalmente se solicita certificar la entrega de los SMS
enviados (ver parámetro “certDelivery”), se remitirá la URL de acceso
al documento del certificado. En su ausencia o si tiene otro valor no
se solicita ni la confirmación de entrega ni la URL del documento del
certificado.
idAck Código identificativo para la confirmación de entrega (ver sección 2.7). no
Valor alfanumérico de hasta 20 caracteres (números y letras de la “a” a
la “z” tanto mayúsculas como minúsculas sin incluir ni “Ñ” ni “ñ”). De
rebasar la longitud máxima permitida será truncado. Los caracteres no
permitidos serán eliminados. Solo será considerado si el parámetro ack
se envı́a con valor ”true”. Si se incluye explı́citamente este parámetro
y toma como valor cadena vacı́a, anula la solicitud de confirmación de
entrega.
urlAck URL del cliente a la que Altiria remitirá la información de confirmación no
de entrega del envı́o (ver sección 2.7).

9
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

dPort Puerto destino del SMS a enviar. Valor numérico entre 1 y 65535 (solo no
dı́gitos decimales). Solo necesario si se desea cambiar el valor habitual
de esta propiedad. Si se define, la longitud máxima del mensaje a enviar
(parámetro “msg”) se verá reducida (ver la sección 2.5.3) y se invalidará
la posibilidad de enviar mensajes concatenados (ver parámetro “con-
cat”). Si solo se define “sPort”, este tomará el valor 0.
sPort Puerto origen del SMS a enviar. Valor numérico entre 1 y 65535 (solo no
dı́gitos decimales). Solo necesario si se desea cambiar el valor habitual
de esta propiedad. Si se define, la longitud máxima del mensaje a enviar
(parámetro “msg”) se verá reducida (ver la sección 2.5.3) y se invalidará
la posibilidad de enviar mensajes concatenados (ver parámetro “con-
cat”). Si solo se define “dPort”, este tomará el valor 0.
encoding El único valor permitido es “unicode” para cambiar la codificación del no
SMS a Unicode (ver la sección 2.5.2). En su ausencia o si tiene otro valor
el SMS tomará la codificación por defecto.
concat Si vale “true” permite concatenar mensajes para enviar un mensaje corto no
de longitud mayor que la habitual (ver la sección 2.5.3). En su ausen-
cia, si tiene otro valor o si se define el parámetro “sPort” o “dPort” se
deshabilita la concatenación de mensajes.
certDelivery Si vale “true” solicita certificar la entrega del SMS enviado mediante no
un documento digital con sello certificado de tiempo. Este servicio tiene
sobrecoste y solo está disponible en Europa. Si tiene dudas contacte con
[email protected]. En su ausencia o si tiene otro valor no se solicita
el certificado. Si adicionalmente se solicita la confirmación de entrega del
SMS enviado (ver parámetro “ack”), se podrá recibir la URL de acceso
al documento del certificado.
Cuadro 2.1: Lista de parámetros para sendsms

Las respuestas a este comando pueden ser:

Una lı́nea para cada destinatario, indicando alguna de las siguientes informaciones:
• En caso de éxito y de solicitar confirmacion de entrega (ver sección 2.7):
OK dest:xxxxxxxxxxx idAck:wwwwwwwwww
Si no se solicita la confirmación de entrega o si la petición de confirmación de entrega no es
aceptada, no aparecerá la parte del “idAck”.

• En caso de error:
ERROR dest:xxxxxxxxxxx errNum:yyy
Una única lı́nea informando de algún error general que afecta a todos los envı́os. Tendrá el
siguiente formato:

ERROR errNum:yyy

El valor de “dest”se corresponde con el número de teléfono del destinatario. Si se hubiese enviado
un mensaje concatenado (ver el parámetro “concat”) a un único destinatario le corresponderán varios
mensajes, tantos como fragmentos compongan el mensaje concatenado. En ese caso aparecerán lı́neas
independientes para cada fragmento siendo cualificado el valor de “dest” con un sufijo que diferencie
cada fragmento con un ı́ndice numérico comenzando por 0. Por ejemplo para un mensaje concatenado
de tres fragmentos enviado al número “xxxxxxxxxxx”:

10
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

OK dest:xxxxxxxxxxx(0) idAck:wwwwwwwwww
OK dest:xxxxxxxxxxx(1) idAck:wwwwwwwwww
OK dest:xxxxxxxxxxx(2) idAck:wwwwwwwwww

El valor de “errNum” se corresponde con uno de los códigos de estado del apartado 2.4.3.
El valor de “idAck” se corresponde con el código de identificación asociado a la solicitud de confir-
mación de entrega (ver sección 2.7).
La infomación de éxito para un destinatario concreto implica que el mensaje ha sido aceptado por
la pasarela, no que haya sido enviado y recibido por el destinatario. Un mensaje puede ser aceptado
aún cuando no se disponga de crédito suficiente para su envı́o (ver sección 2.4.2).
Para asegurar el adecuado funcionamiento de este comando se recomienda probar la correcta recep-
ción de todos los caracteres permitidos en un teléfono móvil antes de poner el sistema en producción.

2.4.2. Consulta del crédito disponible

Permite conocer el crédito instantáneo disponible para enviar mensajes.
Este comando tiene la lista de parámetros del cuadro 2.2.
Los datos de autentificación se proporcionan mediante los parámetros “apiKey” y “apiSecret”,
gestionados desde la sección de desarrolladores del perfil del usuario en el portal web de envı́o de SMS
Altiria360 ([ALTIRIA360]).
La única forma de averiguar si se tiene crédito suficiente para enviar los mensajes, aparte de llevar
un contador propio de saldo disponible, es mediante una consulta previa a través de este comando.
El comando ofrece información del crédito disponible en un momento dado. Puesto que el sistema
decrementa el crédito justo al enviar el mensaje al destinatario, es necesario seguir el siguiente esquema
para utilizar adecuadamente el comando de consulta de crédito disponible:

Antes de comenzar con los envı́os, se calcula cuantos mensajes en total se desean enviar, por
ejemplo 5000.

Se consulta el valor del crédito disponible una única vez.

A partir del coste en créditos de cada mensaje a enviar y del saldo disponible se estima si se
podrán enviar o no todos los mensajes.
En caso positivo, se usan los comandos de envı́o de mensajes. En caso negativo se debe adquirir
más crédito

Cuando el sistema haya finalmente enviado todos los mensajes, una nueva consulta del crédito
disponible ofrecerá el valor actualizado.
En cualquier caso la comprobación efectiva del saldo disponible para efectuar un envı́o se realiza en
un proceso interno justo antes de efectuar el envı́o. En caso de que no se disponga de crédito suficiente,
el mensaje no será enviado y el cliente será informado a través de correo electrónico. Si posteriormente
se adquiere más crédito disponible, se podrá avisar a Altiria para reintentar los envı́os pendientes.

Nombre Valor Obligatorio

cmd ”getcredit” sı́
apiKey Código alfanumérico identificador gestionado desde la sección de desarro- sı́
lladores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).

11
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

apiSecret Clave asociada a un “apiKey” gestionada desde la sección de desarrolla- sı́

dores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).
Cuadro 2.2: Lista de parámetros para getcredit

La respuesta a este comando es una única lı́nea con el siguiente formato:

En caso de éxito:

OK credit(0):xxxx

En caso de error:

ERROR errNum:yyyy

El valor de “credit(0)” se corresponde con el crédito disponible. Será un número con dos decimales.
El valor de “errNum” se corresponde con uno de los códigos de estado del apartado 2.4.3.

2.4.3. Códigos de estado

El cuadro 2.3 presenta la lista de los posibles códigos de estado que podrán aparecer en la respuesta
a cada comando del API de envı́o de SMS (ver 2.4).

CÓDIGO DETALLE
001 Error interno. Contactar con el soporte técnico
002 Error de acceso al puerto seguro 443. Contactar con el soporte técnico
010 Error en el formato del número de teléfono
011 Error en el envı́o de los parámetros de la petición o codificación incorrecta.
013 El mensaje excede la longitud máxima permitida
014 La petición HTTP usa una codificación de caracteres inválida
015 No hay destinatarios válidos para enviar el mensaje
016 Destinatario duplicado
017 Mensaje vacı́o
018 Se ha excedido el máximo número de destinatarios autorizado
019 Se ha excedido el máximo número de mensajes autorizado
020 Error en la autentificación
033 El puerto destino del SMS es incorrecto
034 El puerto origen del SMS es incorrecto
035 La web móvil enlazada en el mensaje no pertenece al usuario
036 La web móvil enlazada en el mensaje no existe
037 Se ha excedido el máximo número de webs móviles enlazadas en el mensaje
038 Error de sintaxis en la definición del envı́o con enlace a web móvil
039 Error de sintaxis en la definición de los parámetros de la web móvil parametrizada
041 Error en la url para el ack, la url supera los 500 caracteres o bien no es una url válida

Cuadro 2.3: Lista de los códigos de estado

12
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.5. Mensajes de texto

Los caracteres permitidos para el texto del mensaje corto y la longitud máxima dependerán de
la codificación de caracteres seleccionada: codificación por defecto (ver sección 2.5.1) o la codificación
UNICODE (ver sección 2.5.2).

2.5.1. Codificación por defecto

La codificación por defecto permite los caracteres de la tabla 2.4.
La longitud máxima permitida se detalla en la sección 2.5.3.
Las vocales con tilde o acento agudo (á) son aceptadas pero se enviarán al teléfono móvil sin
acentuar.
Adicionalmente se admiten los caracteres extendidos de la tabla 2.5. Cada carácter extendido
ocupa el doble espacio que un carácter normal, esto debe considerarse para el cómputo de la
longitud máxima del mensaje.
En caso de que el mensaje a enviar contenga caracteres fuera de las listas presentadas, estos
serán reemplazados por el carácter “?” antes de enviar el mensaje.

@ ( 4 L W h s Ú ù
cr1 ) 5 A M X i t á
lf2 * 6 B N Y j u é
Ç + 7 C Ñ Z k v ı́
sp3 , 8 D O ¿ l w ó
! - 9 E P a m x ú
” . : F Q b n y Ü
# / ; G R c ñ z ü
$ 0 < H S d o Á à
% 1 = I T e p É è
& 2 > J U f q Í ı̀
’ 3 ? K V g r Ó ò

Cuadro 2.4: Lista de caracteres permitidos para mensajes de texto en la codificación por defecto

[ ] \ ^ { } | ~ B
C

Cuadro 2.5: Lista de caracteres extendidos permitidos para mensajes de texto

2.5.2. Unicode
La codificación UNICODE, forzada mediante el parámetro “unicode” (ver el cuadro 2.1), per-
mite todo el juego de caracteres UNICODE de 16bits.
La longitud máxima permitida se detalla en la sección 2.5.3, siendo siempre menor que usando
la codificación por defecto (ver la sección 2.5.1).
Con esta codificación serı́a posible por ejemplo el envı́o de vocales con tilde.
1 Retorno de carro
2 Nueva lı́nea
3 Espacio blanco

13
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.5.3. Longitud del mensaje

La longitud máxima de un mensaje de texto es un valor variable que depende de la codificación
de caracteres usada y de la posibilidad de concatenación. Los mensajes con enlaces a web móvil
(consultar la sección 2.6) o en caso de definir puertos origen o destino del SMS (ver los parámetros
sPort y dPort en el cuadro 2.1) si exceden la longitud máxima aplicable serán rechazados (no
enviados). En otro caso serán truncados a la longitud máxima permitida.

La longitud máxima de un mensaje corto con la codificación por defecto es de 160 carac-
teres (ver sección 2.5.1). Los caracteres extendidos (ver la tabla 2.5) ocupan el doble, por tanto
la longitud máxima se reduce. Por ejemplo si el texto del SMS contuviera el sı́mbolo del euro
“BC” y los corchetes “[ ]”, la longitud máxima del mensaje corto se reducirı́a a 157 caracteres.
La longitud máxima de un mensaje corto con la codificación UNICODE es de 70 caracteres
(ver sección 2.5.2).

En caso de definir puertos origen o destino del SMS (ver los parámetros sPort y dPort en el
cuadro 2.1) la longitud máxima se reduce de la siguiente forma:

152 caracteres para la codificación por defecto (ver sección 2.5.1). Igualmente hay que
considerar que los caracteres extendidos (ver la tabla 2.5) ocupan el doble.
66 caracteres para la codificación UNICODE (ver sección 2.5.2).

Mediante el uso de mensajes concatenados es posible ampliar esos lı́mites. Un mensaje

concatenado consiste en varios mensajes en secuencia recibidos como un único mensaje en el teléfono
del destinatario.
Los mensajes concatenados se posibilitan mediante el parámetro “concat” (ver el cuadro 2.1) siem-
pre que no se esten definiendo ni el puerto origen ni el puerto destino del SMS (ver los parámetros
sPort y dPort en el cuadro 2.1).
La plataforma de Altiria permite concatenar hasta 10 mensajes, aplicando en ese caso los
lı́mites siguientes a la longitud del mensaje:

1530 caracteres para la codificación por defecto (ver sección 2.5.1). Igualmente hay que
considerar que los caracteres extendidos (ver la tabla 2.5) ocupan el doble.
670 caracteres para la codificación UNICODE (ver sección 2.5.2).

14
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.6. Enlaces a web móvil

El portal web de envı́o de SMS Altiria360 ([ALTIRIA360]) permite también componer páginas
webs adaptadas para móviles ([LANDINGS]) de forma sencilla a partir de plantillas. Si desea más
detalles sobre esta u otras funciones del portal web, envie un correo electrónico solicitando información
a [email protected].
Las webs creadas en el portal Altiria360 se pueden enlazar fácilmente en el texto de los SMS
enviados mediante la pasarela (API). Para ello se debe añadir el identificador de la web en el texto del
SMS a enviar (parámetro “msg” del cuadro 2.1) con el siguiente formato:

{$identificador$}

Se puede obtener el valor del identificador de cada web en el portal Altiria360, en la columna de
edición de la web, junto a su nombre.

Se ilustra a continuación los parámetros necesarios para la web móvil de la figura anterior con
identificador 15880:

cmd="sendsms"
apiKey="YYYYY"
apiSecret="ZZZZZ"
dest="346XXXXXXXX"
msg="Estimado cliente, acceda a la promoción en el siguiente enlace: {$15880$}"
landing="1"
params="0"

El el momento del envı́o del SMS a cada destinatario, el identificador de la web será reemplazado
por un enlace a un acortador de URLs.
Cada enlace consta de un dominio acortado y un código hash alfanumérico único e irre-
petible de 7 caracteres.
El dominio del acortador por defecto es “http://go2.re” aunque se puede solicitar uno distinto
(remitir la petición a [email protected]).
Cuando el destinatario recibe el SMS, podrı́a leer por ejemplo el siguiente mensaje:

15
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Estimado cliente, acceda a la promoción en el siguiente enlace: http://go2.re/wD34f1q

Al tratarse de una URL única por destinatario, el portal Altiria360 guarda estadı́sticas precisas so-
bre qué destinatarios han visitado la web o rellenado un formulario dentro de la misma, pudiendo trazar
todo el proceso: envı́o SMS => entrega SMS => web visitada => formulario completado
Se deben satisfacer entonces los siguientes requisitos para añadir con éxito enlaces a webs móviles:

Cada identificador de web contenido en el parámetro “msg” debe ir precedido y seguido por al
menos un espacio, salto de lı́nea, inicio de mensaje o fin de mensaje. De esta forma se garantiza
que el terminal móvil que reciba el SMS reconocerá correctamente el enlace contenido y permitirá
la navegación por la web.
Se permite añadir hasta 10 identificadores distintos de web móvil en cada mensaje.
Añadir el parámetro “landing” (ver el cuadro 2.1) que es la suma total de identificadores de
web contenidos en el texto del SMS. Si alguna web se utiliza más de una vez, debe sumarse el
identificador correspondiente.
Añadir el parámetro “params” (ver el cuadro 2.1) indicando cuántas webs están parametrizadas
(ver el apartado siguiente 2.6.1). Se debe fijar a 0 si no hay webs parametrizadas.

2.6.1. Parametrización de la web móvil

Las webs enlazadas en el texto de los SMS enviados se pueden parámetrizar de forma que cada
destinatario acceda a una versión propia, con unos datos particulares.
En primer lugar desde el editor de web móvil en el portal Altiria360 se deben añadir los parámetros
oportunos al contenido de la web.
Se ilustra a continuación el parámetro “nombre” añadido a la siguiente web móvil:

Se observa que el editor del portal Altiria360 añade los parámetros al contenido de la web con el
siguiente formato;

{$parámetro$}

El enlace a la web móvil debe añadirse al SMS tal y como se ha detallado en el apartado anterior
(2.6). Además hay que satisfacer los siguientes requisitos adicionales:

Definir el parámetro “params” (ver el cuadro 2.1) para indicar cuántas de las webs móviles
enlazadas en el texto del SMS van a ser parametrizadas.

16
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Añadir para cada web móvil parametrizada el parámetro “webParams” cualificado con el iden-
tificador de la web móvil. Este parámetro define en formato json los pares parámetro/valor
propios de la web. Si para algún parámetro se define un valor vacı́o, ası́ será representado al
visualizar la web móvil.
Se resalta que los caracteres del cuadro 2.6 deben ser representados de manera especial para
evitar errores de procesado del json en los parámetros “webParams”:

Carácter Representación
” \”
\ \\

Cuadro 2.6: Caracteres especiales json

Para el ejemplo de la web móvil de la figura anterior con identificador 15880 serı́an estos parámetros:

cmd="sendsms"
apiKey="YYYYY"
apiSecret="ZZZZZ"
dest="346XXXXXXXX"
msg="Estimado cliente, acceda a la promoción en el siguiente enlace: {$15880$}"
landing="1"
params="1"
webParams15880="{"nombre":"Pedro"}"

Como resultado, el receptor del SMS con el enlace a la web móvil parametrizada verá el siguiente
contenido:

Cada parámetro “webParams” puede contener tantos pares parámetro/valor como se hayan definido
a través del editor web. Basta añadirlos correctamente formateados en json de esta forma:

{ "parámetro1":"valor1" , "parámetro2":"valor2", "parámetro3":"valor3" ... }

En caso de no remitir valores para todos los parámetros definidos a través del editor web, se usará
el valor por defecto propio de cada parámetro, también definido a través del editor web.

17
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.7. Confirmación de entrega

El servicio de confirmación de entrega, solicitado a través del parámetro “ack” de los comandos de
envı́o, permite recibir notificaciones con información sobre el estado de entrega de los mensajes cortos
enviados mediante la pasarela.
La confirmación de entrega NO está disponible en todos los paı́ses y puede estar sujeta a un coste
adicional.
En España y Europa sı́ está disponible y es gratuita.
En la mayorı́a de paı́ses de Hispanoamérica (México, Colombia, Chile, Perú, Ecuador?) no se
dispone de esta información porque las operadoras de telefonı́a celular no la emiten. Aunque se solicite
la confirmación de entrega con el parámetro urlAck, Altiria no emitirá ninguna petición de confirmación
de entrega a la URL del cliente, aunque los mensajes sı́ serán enviados.
Puede consultar información actualizada sobre la confirmación de entrega aquı́.
Si adicionalmente se solicitó certificar la entrega del SMS a través del parámetro “certDelivery”,
permite recibir la URL de acceso al documento del certificado.
Para tener acceso a este servicio de confirmación de entrega, es preciso que el cliente o bien haya
notificado a Altiria la URL por defecto a donde se enviarán todas las confirmaciones de entrega, o bien
que lo solicite en cada petición usando el parámetro urlAck.
La confirmación de entrega se enviará con preferencia a la URL indicada en el parámetro urlAck.
Si el parámetro no se encontrase o se encontrase vacı́o, la confirmación de entrega se enviará a la URL
por defecto que el cliente solicitó a Altiria . En caso de no existir ninguna de las dos configuraciones,
las solicitudes de confirmación de entrega serán ignoradas aunque los mensajes sı́ serán enviados.
Para que el cliente pueda asociar la información recibida sobre el estado de entrega de un mensaje
con el propio mensaje enviado previamente a través de la pasarela, se usará el identificador devuelto
en la respuesta a los comandos de envio en la parte “idAck”.
Este identificador puede albergar dos tipos de valores:

Si en el propio comando de envı́o se incluye el parámetro “idAck” (es opcional), contendrá ese
valor truncado a veinte caracteres y formado solo por caracteres válidos. Es importante constatar
que el identificador devuelto en este caso solo coincidirá con el suministrado en el correpondiente
comando de envı́o si cumple los criterios de composición explicados en la tabla 2.1
Si en el propio comando de envı́o no se incluye el parámetro “idAck”, contendrá un valor numérico
de diez dı́gitos como máximo generado por la pasarela automáticamente.

Las notificaciones del estado de entrega serán enviadas a través de peticiones HTTP POST
dirigidas a la URL donde el cliente habrá configurado previamente un servidor HTTP a la escucha. La
petición POST incluirá un solo parámetro, “notification=destination,idAck,status”.
El contenido detallado de la petición HTTP POST enviada será del tipo (content-type):
“application/x-www-form-urlencoded” codificado con el juego de caracteres “UTF-8”.
El parámetro “notification” incluye los datos del cuadro 2.7, separados por comas.
El estado “NO ENTREGADO” aparece cuando el mensaje no puede ser entregado al teléfono móvil.
Es un estado definitivo, por lo que ese mensaje particular nunca será entregado. Las causas pueden ser
múltiples, desde que el teléfono haya estado apagado durante un tiempo superior al periodo de validez,
hasta que el número no exista. En general no se puede conocer la causa.
El estado “ERROR 100” indica que el mensaje por el momento no ha podido ser entregado al
destinatario debido a algún problema en su teléfono móvil. Las causas más comunes son: mala cober-
tura, buzón de mensajes cortos lleno o teléfono apagado. El mensaje se intentará enviar varias veces
con posterioridad durante un tiempo limitado. Si el problema en el teléfono se subsana a tiempo, el
mensaje será finalmente entregado, recibiéndose la correspondiente confirmación.

18
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Dato Valor
destination Número de teléfono móvil al que se refiere la información de es-
tado de entrega. Si esa información es relativa a un mensaje con-
catenado, el teléfono figurará cualificado con un sufijo que haga
referencia al fragmento particular del que se trate, por ejemplo
xxxxxxxxxxx(2) (ver la respuesta al enviar un mesaje concatena-
do en la sección 2.4.1).
idAck Identificador que coincidirá con el suministrado por Altiria al
cliente en la parte “idAck” de la respuesta al comando de envı́o.
El contenido de este campo se ha explicado en el inicio de esta
sección.
status Estado relativo a la entrega del mensaje. Podrá tomar los va-
lores: “ENTREGADO”, “NO ENTREGADO”, “ERROR 100”,
“ERROR 101”, “ERROR 114”, “ERROR 115” o “CERT(url)”.

Cuadro 2.7: Lista de datos de la confirmación de entrega

El estado “ERROR 101” indica que el mensaje por el momento no ha podido ser entregado al des-
tinatario debido a algún problema en la red de telefonı́a móvil del operador. Habitualmente, cuando
el operador solvente los problemas, el mensaje será entregado, recibiéndose la correspondiente confir-
mación.
El estado “ERROR 114” indica que el mensaje ha sido enviado pero no ha podido ser entregado
porque el número de teléfono destinatario no existe.
El estado “ERROR 115” indica que el mensaje ha sido enviado pero no ha podido ser entregado
porque el destinatario no acepta mensajes.
El estado “CERT(url)” referencia la URL de acceso al documento del certificado de entrega del
SMS (parámetro “certDelivery”). El certificado será global y único para todos los fragmentos que
pudieran componer el SMS (en caso de ser concatenado).
Opcionalmente se podrı́a configurar el envı́o de las notificaciones de entrega mediante la llamada a
un recurso REST del cliente según la especificación relativa a la confirmación de entrega de la pasarela
REST de Altiria para el envı́o de SMS.
Otra alternativa serı́a configurar el envı́o de las notificaciones de entrega mediante la llamada a un
servicio web SOAP del cliente como también se detalla en la especificación relativa a la confirmación
de entrega de la pasarela de Altiria de servicios web para el envı́o de SMS.
Consultar al soporte técnico de Altiria ([email protected]) para concer más detalles sobre estas
posibilidades.
El servidor HTTP del cliente deberá responder a la petición POST con un código de estatus
200 y un cuerpo tipo “text/plain” con un contenido simple, preferentemente una cadena de texto vacı́a
o algo sencillo como “OK”.
Finalmente para clarificar todos los elementos de la funcionalidad de confirmación de entrega, se
esquematizan los procesos involucrados en el envı́o de un mensaje a dos destinatarios:

1. El cliente efectúa un envı́o de SMS a través de la pasarela de Altiria incluyendo entre otros los
siguientes parámetros:
dest=346xxxxxxxx.
dest=346yyyyyyyy.
ack=true.
idAck=zzzz.

19
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2. La pasarela de Altiria recibe la petición y remite el mensaje a los destinatarios seleccionados.

Además la pasarela responde a la petición HTTP POST del cliente las siguientes dos lı́neas:

OK dest:346xxxxxxxx idAck:zzzz
OK dest:346yyyyyyyy idAck:zzzz

Si el cliente no hubiera incluido el parámetro “idAck” en el comando “sendsms” (punto 1 del

ejemplo), la pasarela de Altiria habrı́a autogenerado el identificador para añadirlo a la respuesta.
3. Tan solo uno de los destinatarios recibe en su teléfono el mensaje corto enviado.

4. El servidor HTTP del cliente, habilitado para recibir las notificaciones de estado de entrega, recibe
sendas peticiones HTTP POST desde la pasarela de Altiria , con el parámetro “notification”
conteniendo:

‘‘notification=346xxxxxxxx,zzzz,ENTREGADO’’
‘‘notification=346yyyyyyyy,zzzz,NO ENTREGADO’’

5. El servidor HTTP del cliente responde a cada petición POST el código de estatus 200 y una
cadena de texto vacı́a en formato “text/plain”.
6. Empleando el identificador zzzz, el cliente podrá asociar la confirmación de entrega con el mensaje
previamente enviado a cada uno de los destinatarios.
7. Si adicionalmente se solicitó certificar la entrega de los SMS a través del parámetro “certDeli-
very”, se recibirá también la URL de acceso al documento del certificado para el SMS entregado
con éxito:

‘‘notification=346xxxxxxxx,zzzz,CERT(http://...)’’

20
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.8. Comandos de la API de firma de contrato online

A continuación se detallan los comandos disponibles en el API para firma de documentos. Para
cada comando se representa un cuadro con los parámetros que lo componen. Cada parámetro puede
ser obligatorio u opcional y en algunos casos puede aparecer múltiples veces.
Los comandos se distinguen entre sı́ mediante el parámetro “cmd”, obligatorio en todos los casos.

2.8.1. Firma de un documento PDF

Permite iniciar el proceso de firma online sobre un destinatario.
Los datos de autentificación se proporcionan mediante los parámetros “apiKey” y “apiSecret”,
gestionados desde la sección de desarrolladores del perfil del usuario en el portal web de envı́o de SMS
Altiria360 ([ALTIRIA360]).
El destinatario se debe identificar con un número de teléfono y/o con una dirección de
correo electrónico; al menos se debe suministrar alguno de los datos. La notificación de documento
pendiente de firma se le remitirá por ambas vı́as si están disponibles.
Para identificar a la empresa que emite la solicitud de firma de documento es preciso con-
figurar un nombre comercial y una dirección de correo electrónico. Contactar con [email protected]
para solicitar la configuración de esos datos.
Es también obligatorio seleccionar al menos un mecanismo de firma del documento entre los
parámetros smsOtpSig, emailOtpSig, webSig, ecertSig y manSig. Se admite elegir más de un
mecanismo de firma por documento.
El comando en sı́ sólo define los parámetros del servicio de firma sin adjuntar el documento PDF.
A partir de la respuesta se obtendrá una URL sobre la que remitir el documento en un POST HTTP
independiente.
Este comando tiene la lista de parámetros del cuadro 2.8.

Nombre Valor Obligatorio

cmd certpdffile sı́
apiKey Código alfanumérico identificador gestionado desde la sección de desarro- sı́
lladores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).
apiSecret Clave asociada a un “apiKey” gestionada desde la sección de desarrolla- sı́
dores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).
multiSig Lista de firmantes del documento hasta un máximo de 15. Cada elemen- sı́*
to de la lista se compondrá de los siguientes subelementos: destination:
similar al parámetro ”destination”descrito más adelante; email: similar
al parámetro “email” descrito más adelante; sequence: valor opcional
entero entre 1 y el máximo de firmantes (el cero o valores negativos serán
omitidos). Define el número de orden de cada firmante. Los firmantes sin
número de orden recibirán la petición de firma en primer lugar de forma
simultanea. Los firmantes con número de orden recibirán la petición de
firma cuando los firmantes ordenados previamente hayan firmado el do-
cumento. Se puede repetir valor entre distintos firmantes, se consideran
firmantes con similar prioridad; sigLocX, sigLocY, sigLocWidth,
sigLocHeight y sigLocPage: parámetros de posicionamiento de cada
firma (consultar la sección 2.8.2).

21
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

destination Número de teléfono móvil del destinatario del documento. Se especificará sı́*
en formato de numeración internacional sin prefijo ’00’ ni el signo ’+’. Ej:
34645852126. Es fundamental incluir el prefijo del paı́s (34 para España)
para que el mensaje llegue al destino esperado. No debe superar los 16
dı́gitos. Su uso es obligatorio si no se incluye el parámetro “email”
o si se escoge el método de firma por OTP SMS mediante el parámetro
“smsOtpSig”.
email Dirección de correo electrónico del destinatario del documento. Su uso sı́*
es obligatorio si no se incluye el parámetro “destination” o si se escoge
el método de firma por OTP email mediante el parámetro “emailOt-
pSig”.
type Tipo de firma de contrato online solicitada. Solo puede tomar dos valores: sı́
“premium” o “simple”. Consultar las caracterı́sticas y los costes de cada
tipo de servicio en [email protected].
smsOtpSig SMS en el Web de firma. Sólo si vale “true” se escoge como mecanismo no*
de firma el envı́o de un código OTP por SMS. Será entonces obligato-
rio definir el teléfono móvil de cada firmante mediante el parámetro
“destination”. Es obligatorio escoger al menos un mecanismo
de firma entre “smsOtpSig”, “emailOtpSig”, “webSig”, “ecertSig” y
“manSig”.
emailOtpSig Correo-E en el Web de firma. Sólo si vale “true” se escoge como me- no*
canismo de firma el envı́o de un código OTP por email. Será entonces
obligatorio definir la dirección de correo electrónico de cada firmante
mediante el parámetro “email”. Es obligatorio escoger al menos
un mecanismo de firma entre las siguientes posibilidades: “smsOt-
pSig”, “emailOtpSig”, “webSig”, “ecertSig” y “manSig”.
webSig Click-Wrap en el Web de firma. Sólo si vale “true” se escoge como me- no*
canismo de firma marcar varios “checkbox” en la página de firma del
documento. Es obligatorio escoger al menos un mecanismo de
firma entre las siguientes posibilidades: “smsOtpSig”, “emailOtpSig”,
“webSig”, “ecertSig” y “manSig”.
ecertSig Firma-E en el Web de firma. Sólo si vale “true” se escoge como meca- no*
nismo de firma el uso del certificado electrónico digital del destinatario.
Está opción no aparecerá disponible si el destinatario accede a la firma
del documento desde un teléfono móvil. Será necesario además que la
primera vez instale un componente de firma especı́fico en su navegador.
Es obligatorio escoger al menos un mecanismo de firma entre
“smsOtpSig”, “emailOtpSig”, “webSig”, “ecertSig” y “manSig”.
manSig Firma-D en el Web de firma. Sólo si vale “true” se escoge la firma ma- no*
nuscrita como mecanismo. Si el destinatario accede a la firma del docu-
mento desde un teléfono móvil tendrá que usar el dedo para firmar. En
otro caso se usará el puntero del ratón o el “touchpad”. Es obligato-
rio escoger al menos un mecanismo de firma entre “smsOtpSig”,
“emailOtpSig”, “webSig”, “ecertSig” y “manSig”.
senderId Remitente a utilizar en los SMS enviados al destinatario del documento, no
autorizado por Altiria . Solo tendrá uso si se define el teléfono móvil del
destinatario mediante el parámetro “destination”. La posibilidad de
personalizar el remitente depende del paı́s destinatario del mensaje. Se
admite un valor alfanumérico de hasta 11 caracteres (números y letras
de la “a” a la “z” tanto mayúsculas como minúsculas excluyendo la “Ñ”
y la “ñ”). Los caracteres inválidos serán suprimidos automática-
mente. Si no se incluye o el valor escogido es inválido, el mensaje se
enviará con el remitente por defecto seleccionado por Altiria.

22
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

smsText Texto personalizado del SMS remitido al destinatario con la notifica- no

ción de documento pendiente de firma. Como máximo 120 caracteres
de la sección 2.5.1. El texto completo enviado en el SMS contendrá al
final la URL de acceso al documento. Si no se define este parámetro el
destinatario recibirá un texto por defecto.
emailText Párrafo adicional añadido al texto del correo electrónico remitido al des- no
tinatario con la notificación de documento pendiente de firma. Como
máximo 1023 caracteres. El salto de lı́nea se debe marcar como “<br>”.
title Tı́tulo del envı́o de documento para identificarlo en el portal web no
Altiria360 ([ALTIRIA360]). Como máximo 50 caracteres del alfabeto
ISO8859-1. No se incluye en el documento que se firma.
forwardEmail Dirección de correo electrónico a la que se enviará una copia del docu- no
mento firmado.
refreshDays Número entero entre 1 y 7 representando cada cuantos dı́as se reenviará no
al destinatario, a modo de recordatorio, el correo electrónico con la no-
tificación de documento pendiente de firma. Se usa en conjunción con
el parámetro “refreshTimes”. Sólo se tendrá en cuenta si se solicita
servicio “premium” (ver el parámetro “type”) y se define la dirección
de correo del destinatario mediante el parámetro “email”; en otro caso
será omitido.
refreshTimes Número entero entre 1 y 10 representando el número máximo de recor- no
datorios que se reenviarán al destinatario. Sólo se tendrá en cuenta si
se define el parámetro “refreshDays”, se solicita servicio “premium”
(ver el parámetro “type”) y se define la dirección de correo del des-
tinatario mediante el parámetro “email”; en otro caso será omitido.
Por defecto toma el valor 1.
requestDni Sólo si vale “true” y se solicita servicio “premium” (ver el parámetro no
“type”) se requerirá la inclusión obligatoria de las dos caras del DNI
del destinatario durante el proceso de firma, mediante archivos de ima-
gen “jpg”. Si el destinatario accede a la firma del documento desde un
teléfono móvil, además de poder elegir una imagen almacenada, podrá
utilizar la cámara del dispositivo.
customClause Claúsula personalizada que aparecerá como requisito previo en las con- no
diciones de firma del documento. Cadena de texto formada por tres ele-
mentos separados por “;” con el siguiente formato: tı́tulo;ı́ndice;texto.
El tı́tulo es un identificador textual de la cláusula (máximo 50 caracte-
res del alfabeto ISO8859-1). No debe contener el carácter “;”. El ı́ndice
es un identificador numérico para ordenar la presentación de la claúsula
respecto de las demás que puedan aparecer (entero positivo que no debe
repetirse). El texto es el contenido en sı́ de la claúsula (máximo 10.000
caracteres del alfabeto ISO8859-1; el salto de lı́nea se debe marcar co-
mo “<br>”; se admiten etiquetas HTML para formatear el texto de la
claúsula). Si se agrega el sufijo * al tı́tulo de la claúsula, obliga a que el
destinatario la acepte para poder firmar el documento. Se puede incluir
más de una claúsula repitiendo este parámetro tantas veces como sea
necesario.
callback Si vale “true” solicita la recepción de las actualizaciones del estado de no
firma del documento enviado a través de un callback (ver sección 2.9).
Cuadro 2.8: Lista de parámetros para certpdffile

Los firmantes del documento se pueden definir de dos formas:

Mediante los parámetros ”destination/email”sólo si hay un único firmante.

23
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Repitiendo el parámetro ”multiSig para definir desde un firmante hasta 15. De esta forma se
permite además determinar el orden de cada firmante y la posición de cada firma en el documento
(consultar la sección 2.8.2).

A continuación se ilustra un ejemplo de cada caso:

Un ejemplo de parámetros del comando certPdfFile usando ”destination/email”:

Envı́o de la notificación de firma del documento a un único destinatario a través de email y SMS.
Servicio de firma “premium” por OTP desde SMS.

Solicitud de recepción de la actualización de estado mediante callback (ver sección 2.9).

serı́a este:

apiKey="YYYYY"
apiSecret="ZZZZZ"
destination="346XXXXXXXX"
email="[email protected]"
type="premium"
smsOtpSig="true"
callback="true"

Un ejemplo de parámetros del comando certPdfFile usando ”multiSig”:

Envı́o de la notificación de firma del documento a dos destinatarios a través de email y SMS.
Definición del orden para cada destinatario.
Servicio de firma “premium” por OTP desde SMS.

Solicitud de recepción de la actualización de estado mediante callback (ver sección 2.9).

serı́a este:

apiKey="YYYYY"
apiSecret="ZZZZZ"
multiSig="{"destination":"346XXXXXXXX","email":"[email protected]","sequence":1}"
multiSig="{"destination":"346YYYYYYYY","email":"[email protected]","sequence":2}"
type="premium"
smsOtpSig="true"
callback="true"

Se observa que el parámetro ”multiSig”se repite por cada firmante. El valor del parámetro
se formatea en json de la forma:

{ "parámetro1":"valor1" , "parámetro2":"valor2", "parámetro3":"valor3" ... }

La respuesta a este comando será un mensaje json con el elemento “status” representando un
código de estado general de los descritos en apartado 2.8.5
Si la operación ha resultado exitosa (código de estado “000”) la respuesta contendrá adicionalmente:

url: URL sobre la que subir el documento PDF a remitir al destinatario.

24
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

id: identificador alfanumérico de 33 caracteres de longitud correspondiente al documento PDF

pendiente de remitir. Ese identificador deberá ser utilizado posteriormente en el resto de coman-
dos para referenciar a ese documento en particular.

Un ejemplo de respuesta exitosa serı́a el mostrado a continuación:

{
"status":"000",
"url":"http://...",
"id":"XXXXXXXX_YYYYYYYYYYYYYYY_ZZZZZZZZ"
}

Un ejemplo de respuesta notificando un error en la autentificación serı́a este:

{
"status":"020"
}

2.8.2. Posicionamiento de las firmas

El parámetro ”multiSig”(ver el cuadro 2.8) permite definir la posición de las firmas en el documento.
Si no se suministra esa información (es opcional), las firmas se posicionan de acuerdo a las
siguientes reglas:

Si el documento no está firmado previamente de forma electrónica:

• Hasta dos firmantes: las firmas se ubican al pie de la última página con fondo transparente
para evitar tapar el texto en la medida de lo posible.
• Más de dos firmantes: se incluye una página final adicional en el documento; las firmas se
distribuyen en filas de tres en esa página con un fondo no transparente.
Si el documento ya está firmado previamente de forma electrónica:

• Hasta dos firmantes: las firmas se ubican al pie de la última página con fondo transparente
para evitar tapar el texto en la medida de lo posible.
• Más de dos firmantes: las firmas se distribuyen en la última página como aparecerı́an en la
página adicional del caso anterior. Serı́a recomendable que la última página del documento
estuviese vacı́a para que las firmas no tapen el texto.

Los elementos de posicionamiento explı́cito de la firma son: sigLocX, sigLocY, sigLocWidth,

sigLocHeight y sigLocPage.
En el momento en que se defina la posición de la firma para algún destinario se ha de especificar
también para todos los demás. Por otra parte se debe evitar solapar distintas firmas porque se
producirán errores durante el procesado posterior del documento, anulándose el envı́o.
A continuación se describen los 5 parámetros relativos a la posición de la firma y la lógica aplicada
a todos ellos en el momento en que alguno esté definido.
En todos los casos los valores asignados están establecidos en ”puntos”(pt). Las coordenadas 0,0
de la página se considera que empiezan en la esquina inferior izquierda de la hoja.
La correspondencia entre los puntos y la dimensión en mm de las hojas del documento se puede
encontrar en esta URL [POINTS2MM].

25
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

sigLocX: valor entero que se corresponde con el posicionamiento en el eje horizontal del cuadro
de firma, tomando como referencia el borde izquierdo de la página. Si no es recibido, es menor
que cero o la firma saldrı́a fuera del documento (cálculo a partir del ancho de la página y del
ancho de la firma)), la firma se situará en el borde derecho de la página. En caso contrario, se
aplicará el valor especificado por el usuario.
sigLocY: valor entero que se corresponde con el posicionamiento en el eje vertical del cuadro
de firma, tomando como referencia el borde inferior de la página. Si no es recibido o es menor
que cero, la firma se ajustará al borde inferior de la página. En caso de que la firma se saliese
fuera del documento (cálculo a partir del alto de la página y de la altura de la firma), la firma se
situará en el borde superior de la página. Para el resto de casos se aplicará el valor especificado
por el usuario.
sigLocWidth: valor entero que se corresponde con el tamaño para el ancho de la firma. Si no
es recibido o es menor que el mı́nimo admisible (140pt) se aplicará el valor mı́nimo descrito. En
caso de que el valor supere el máximo admisible (280pt) se aplicará el valor máximo descrito.
Para el resto de casos se aplicará el valor especificado por el usuario. Es importante definirlo en
consonancia con el tamaño de la altura de la firma para que esta guarde su relación de aspecto.
Lo ideal es mantener una relación de aspecto de 2:1.
sigLocHeight: valor entero que se corresponde con el tamaño para la altura de la firma. Si no
es recibido o es menor que el mı́nimo admisible (70pt) se aplicará el valor mı́nimo descrito. En
caso de que el valor supere el máximo admisible (140 pt) se aplicará el valor máximo descrito.
Para el resto de casos se aplicará el valor especificado por el usuario. Es importante definirlo en
consonancia con el tamaño de la anchura de la firma para que esta guarde su relación de aspecto.
Lo ideal es mantener una relación de aspecto de 2:1.
sigLocPage: valor entero que se corresponde con la página en que aparecerá la firma del desti-
natario. Si no es recibido o es menor que uno la firma se aplicará en la primera página. En caso
de que el valor supere el número total de páginas del documento, la firma se aplicará en la última
página.

2.8.3. Envı́o del documento PDF

Como se ha detallado en el comando de firma de documento (ver 2.8.1), el documento PDF se debe
subir efectuando una petición HTTP POST a la URL suministrada en la respuesta.
El cuerpo de la petición HTTP contendrá el código binario del documento PDF, sin ninguna
transformación. El PDF suministrado no debe estar protegido contra escritura ni por contraseña.
Se debe añadir a la petición la cabecera “content-type:application/pdf”.
La respuesta a esta petición será un mensaje json con el elemento “status” representando un
código de estado general de los descritos en apartado 2.8.5
Por ejemplo en caso de éxito:

{
"status":"000"
}

En deterinados casos excepcionales, ante errores genéricos producidos en el servidor, se recibirá

como respuesta un mensaje json con el elemento “message” representado la causa del error y el elemento
“status code” asociado al código de error HTTP producido en el servidor. Un ejemplo serı́a el siguiente:

{"message":"Not Found","status_code":404}

26
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.8.4. Consulta del estado de firma de un documento PDF

Permite consultar el estado del proceso de firma certificada asociado a un documento remitido
previamente.
Este comando tiene la lista de parámetros del cuadro 2.9.
Los datos de autentificación se proporcionan mediante los parámetros “apiKey” y “apiSecret”,
gestionados desde la sección de desarrolladores del perfil del usuario en el portal web de envı́o de SMS
Altiria360 ([ALTIRIA360]).

Nombre Valor Obligatorio

cmd checkpdffile sı́
apiKey Código alfanumérico identificador gestionado desde la sección de desarro- sı́
lladores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).
apiSecret Clave asociada a un “apiKey” gestionada desde la sección de desarrolla- sı́
dores del perfil del usuario en el portal web de envı́o de SMS Altiria360
([ALTIRIA360]).
id Identificador alfanumérico del documento remitido con éxito previamen- sı́
te.
Cuadro 2.9: Lista de parámetros para checkpdffile

La respuesta a este comando será un mensaje json con el elemento “status” representando
un código de estado general de los descritos en apartado 2.8.5
Si la operación ha resultado exitosa (código de estado “000”) la respuesta contendrá adicionalmente:

fileStatus: estado global del proceso de firma del documento enviado. Ver la sección 2.9 para
consultar detalles sobre los posibles estados.
files: lista de ficheros descargables asociados al proceso de firma. Ver la sección 2.9 para consultar
detalles sobre los ficheros descargables. Además de los tipos detallados en esa sección figurará el
tipo “all” para acceder a un archivo comprimido con todos los ficheros disponibles. Cada elemento
de la lista se compone a su vez de los siguientes subelementos:

• fileType: tipo del fichero descargable.

• fileUrl: URL de descarga del fichero

Un ejemplo de respuesta exitosa serı́a el mostrado a continuación:

{
"status":"000",
"fileStatus":"signed",
"files":
[{"fileType":"source", "fileUrl":"https://..."},
{"fileType":"signed", "fileUrl":"https://..."},
{"fileType":"all", "fileUrl":"https://..."}]
}

Un ejemplo de respuesta notificando un error en la autentificación serı́a este:

{
"status":"020"
}

27
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.8.5. Códigos de estado

El cuadro 2.10 presenta la lista de los posibles códigos de estado que podrán aparecer en la respuesta
a cada comando del API de firma de documentos (ver 2.8).

CÓDIGO DETALLE
000 Éxito
001 Error interno. Contactar con el soporte técnico
002 Error de acceso al puerto seguro 443. Contactar con el soporte técnico
003 No hay saldo suficiente para completar la operación
004 Servicio no disponible. Consultar con [email protected]
011 Error en el envı́o de los parámetros
012 Error en la definición del posicionamiento de alguna firma
013 Se ha superado el máximo número de firmantes del documento
020 Error en la autentificación
028 El identificador del documento no es válido o no existe
029 El documento no es un pdf válido
030 El documento está protegido con contraseña
031 No se admite un documento ya firmado electrónicamente en un contrato de tipo simple
032 El documento está protegido frente a escritura
040 Exceso de documentos pendientes de envı́o. Esperar unos minutos y reintentar

Cuadro 2.10: Lista de los códigos de estado

28
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.9. Actualización del estado de firma de documentos

El servicio de recepción de la actualización del estado de firma del documento enviado, solicitado a
través del parámetro “callback” del comando de firma de documento PDF (ver 2.8.1), permite recibir
notificaciones con cada nuevo estado por el que pasa el proceso de firma.
Para tener acceso a este servicio es preciso que el cliente haya notificado a Altiria la dirección de
Internet a donde se enviarán las notificaciones. En caso contrario, las solicitudes de actualización de
estado serán ignoradas aunque los documentos sı́ serán enviados para iniciar el proceso de firma.
Para que el cliente pueda asociar la información recibida sobre el estado de firma con un documento
enviado previamente a través de la pasarela, se usará el identificador devuelto en la respuesta del
comando de firma de documento PDF (ver 2.8.1) en el elemento “id”).
Las notificaciones del estado de firma serán enviadas a través de peticiones HTTP POST
dirigidas a la URL donde el cliente habrá configurado previamente un servidor HTTP a la escucha. La
petición POST incluirá un solo parámetro, “pdfNotification”, cuyo valor consta de un mensaje JSON
con los elementos del cuadro 2.11.
El contenido de la petición HTTP POST enviada será del tipo (content-type):
“application/x-www-form-urlencoded” codificado con el juego de caracteres “UTF-8”.
A continuación se esquematiza un ejemplo del parámetro “pdfNotification” recibido:

{"id":"XXXXXXXX_YYYYYYYYYYYYYYY_ZZZZZZZZ",
"fileStatus":"processing",
"fileType":"sentEmail",
"fileUrl":"http://..."}

Dato Valor
id Identificador alfanumérico del documento PDF remitido previa-
mente. Emitido como respuesta del comando de firma de docu-
mento PDF (ver 2.8.1).
fileStatus Estado global del proceso de firma del documento enviado. Ver a
continuación los posibles estados.
fileType Tipo del fichero descargable. Ver a continuación los posibles tipos
de ficheros.
fileUrl Url de descarga del fichero.

Cuadro 2.11: Lista de datos de la notificación del estado de firma

En cada notificación se informa del estado global del proceso de firma y se remite la URL
de acceso a un documento PDF asociado a dicho proceso.
Los posibles estados para fileStatus son:

pending: el proceso de firma del documento aún no se ha iniciado.

error: el proceso de firma del documento no ha podido ser iniciado y se ha cancelado.

processing: el proceso de firma del documento se ha iniciado.
signed: el destinatario ha firmado el documento remitido.

Los posibles estados para fileType son:

source: documento pdf original remitido al destinatario para su firma.

29
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

sentEmail: evidencia electrónica del envı́o al correo electrónico del destinatario de la notificación
de documento pendiente de firma.
sentSms: evidencia electrónica del envı́o al teléfono móvil del destinatario de un SMS con la
notificación de documento pendiente de firma.

accessedFile: evidencia electrónica del visualización del documento pendiente de firma por parte
del destinatario.
sentSmsOtp: evidencia electónica del envı́o al teléfono móvil del destinatario de un SMS con la
clave para la firma OTP del documento.

sentEmailOtp: evidencia electónica del envı́o al correo electrónico del destinatario de la clave
para la firma OTP del documento.
signedFile: evidencia electrónica constatando la firma del documento por parte del destinatario.
Contendrá las posibles imágenes del DNI del destinatario (ver el parámetro “requestDni” en la
sección 2.8.1) y las posibles claúsulas adicionales remitidas (ver el parámetro “customClause” en
la sección 2.8.1).
signed: documento pdf ya firmado por el usuario.
record: acta final que recoge las evidencias de todo el proceso.

En caso de solicitar la firma de tipo “simple” (ver el parámetro “type” en la sección 2.8.1), tan solo
se podrán emitir los estados “source” y “signed”, no quedando constancia de ninguna otra evidencia
ni fichero relacionado.
Opcionalmente se podrı́a configurar el envı́o de las notificaciones mediante la llamada a un recurso
REST del cliente según la especificación relativa a la actualización del estado de firma de la pasarela
REST de Altiria para la firma de documentos.
Otra alternativa serı́a configurar el envı́o de las notificaciones mediante la llamada a un servicio
web SOAP del cliente como también se detalla en la especificación relativa a la actualización del estado
de firma de la pasarela de servicios web de Altiria para la firma de documentos.
Consultar al soporte técnico de Altiria ([email protected]) para concer más detalles sobre estas
posibilidades.
El servidor HTTP del cliente deberá responder a la petición POST con un código de estatus
200 y un cuerpo tipo “text/plain” con un contenido simple, preferentemente una cadena de texto vacı́a
o algo sencillo como “OK”.

30
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.10. Ejemplos
Se presentan extractos de programación en varios lenguajes.
El código fuente de todos los ejemplos se puede descargar de esta URL [CODIGOFUENTE]
Altiria no se responsabiliza del funcionamiento de los ejemplos presentados. Se deben considerar
como fragmentos de código ilustrativos del acceso a algunas funcionalidades de la pasarela documen-
tada.
Con objeto de facilitar la lectura algunas lı́neas del código han sido partidas con saltos de
lı́nea que podrı́an afectar al correcto funcionamiento del programa en su ejecución.

2.10.1. Envı́o de un mensaje mediante librerı́as

Contamos con una serie de librerı́as que facilitan aún más la integración de nuestra API. Se trata
de clientes en varios lenguajes de programación que simplifican las operaciones más habituales.

Librerı́a PHP

Se puede incorporar esta librerı́a a un proyecto PHP mediante composer. La librerı́a está disponible
en nuestro repositorio en GitHub a través de esta URL [SMSPHPCLIENT].

Librerı́a Java

Se puede incorporar esta librerı́a a un proyecto Java mediante maven. La librerı́a está disponible
en nuestro repositorio en GitHub a través de esta URL [SMSJAVACLIENT].

Librerı́a Python

Se puede incorporar este módulo a un proyecto Python mediante pip. La librerı́a está disponible
en nuestro repositorio en GitHub a través de esta URL [SMSPYTHONCLIENT].

Librerı́a NodeJS

Se puede incorporar este módulo a un proyecto NodeJS mediante npm. La librerı́a está disponible
en nuestro repositorio en GitHub a través de esta URL [SMSNODEJSCLIENT].

2.10.2. Envı́o de un mensaje en PHP

Ejemplo usando Composer

Consultar la sección 2.10.1.

Ejemplo usando CURL

<?php
class AltiriaSMS {

protected $apikey;
protected $apisecret;
protected $senderId;
protected $encoding;

31
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

protected $concat;
protected $timeout=60;
protected $debug;

protected $url = ’https://www.altiria.net:8443/api/http’;

public function getSenderId() {

return $this->senderId;
}

public function setSenderId($val) {

$this->senderId = $val;
return $this;
}

public function getEncoding() {

return $this->encoding;
}

public function setEncoding($val) {

$this->encoding = $val;
return $this;
}

public function getConcat() {

return $this->concat;
}

public function setConcat($val) {

$this->concat = $val;
return $this;
}

public function getTimeout() {

return $this->timeout;
}

public function setTimeout($val) {

$this->timeout = $val;
return $this;
}

public function getDebug() {

return $this->debug;
}

public function setDebug($val) {

$this->debug = $val;
return $this;
}

public function getApikey() {

return $this->apikey;
}

32
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

public function setApikey($val) {

$this->apikey = $val;
return $this;
}

public function getApisecret() {

return $this->apisecret;
}

public function setApisecret($val) {

$this->apisecret = $val;
return $this;
}

public function sendSMS($destination, $message) {

$return=false;
// Set the curl parameters.
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->url);
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER,
array(’Content-type: application/x-www-form-urlencoded; charset=UTF-8’));
curl_setopt($ch, CURLOPT_HEADER, false);
// Max timeout in seconds to complete http request
curl_setopt($ch, CURLOPT_TIMEOUT, $this->getTimeout());
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

$COMANDO=’cmd=sendsms&apikey=’.$this->getApikey().’&apisecret=’.$this->getApisecret()
$COMANDO.=’&msg=’.urlencode($message);

//Como destinatarios se admite un array de teléfonos, una cadena de teléfonos

//separados por comas o un único teléfonos
if (is_array($destination)){
foreach ($destination as $telefono) {
$this->logMsg("Add destination ".$telefono);
$COMANDO.=’&dest=’.$telefono;
}
}
else{
if( strpos($destination, ’,’) !== false ){
$destinationTmp= ’&dest=’.str_replace(’,’,’&dest=’,$destination).’&’;
$COMANDO .=$destinationTmp;
$this->logMsg("Add destination ".$destinationTmp);
}
else{
$COMANDO.=’&dest=’.$destination;
}
}

//No es posible utilizar el remitente en América pero sı́ en Espa~

na y Europa
$senderId=$this->getSenderId();
if (!isset($senderId) || empty($senderId)) {
$this->logMsg("NO senderId ");

33
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

}
else{
$COMANDO.=’&senderId=’.$senderId;
$this->logMsg("Add senderId ".$senderId);
}

//Concat. Valores posibles true. Si no se especifica o es false, no se envı́a

$concat=$this->getConcat();
if (!isset($concat) || empty($concat) || $concat===false) {
$this->logMsg("NO concat ");
}
else{
$COMANDO.=’&concat=true’;
$this->logMsg("Add concat true");
}

//No es posible utilizar el remitente en América pero sı́ en Espa~

na y Europa
$encoding=$this->getEncoding();
if (!isset($encoding) || empty($encoding)) {
$this->logMsg("NO encoding");
}
else{
if ($encoding===’unicode’){
$COMANDO.=’&encoding=’.$encoding;
$this->logMsg("Add encoding ".$encoding);
}
else{
$this->logMsg("Ignoring encoding. Encoding has no allowed value: ".$encoding);
}
}

// Set the request as a POST FIELD for curl.

curl_setopt($ch, CURLOPT_POSTFIELDS, $COMANDO);

// Get response from the server.

$httpResponse = curl_exec($ch);

if(curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200){

$this->logMsg("Server Altiria response: ".$httpResponse);
if (strstr($httpResponse,"ERROR errNum")){
$this->logMsg("Error sending SMS: ".$httpResponse);
return false;
}
else
$return = $httpResponse;
}
else{
$this->logMsg("Error sending SMS: ".curl_error($ch).’(’.curl_errno($ch).’)’.$httpResponse);
$return = false;
}

curl_close($ch);
return $return;
}

34
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

public function getCredit() {

$return=false;
// Set the curl parameters.
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->url);
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER,
array(’Content-type: application/x-www-form-urlencoded; charset=UTF-8’));
curl_setopt($ch, CURLOPT_HEADER, false);
// Max timeout in seconds to complete http request
curl_setopt($ch, CURLOPT_TIMEOUT, $this->getTimeout());
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

$COMANDO=’cmd=getcredit&apikey=’.$this->getApikey().’&apisecret=’.$this->getApisecret();

// Set the request as a POST FIELD for curl.

curl_setopt($ch, CURLOPT_POSTFIELDS, $COMANDO);

// Get response from the server.

$httpResponse = curl_exec($ch);

if(curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200){

$this->logMsg("Server Altiria response: ".$httpResponse);
if (strstr($httpResponse,"ERROR errNum")){
$this->logMsg("Error asking SMS credit: ".$httpResponse);
$return = false;
}
else
$return = $httpResponse;
}
else{
$this->logMsg("Error getting credit: ".curl_error($ch).’(’.curl_errno($ch).’)’.$httpResponse);
$return = false;
}

curl_close($ch);
return $return;
}

public function logMsg($msg) {

if ($this->getDebug()===true){
echo(date(DATE_RFC2822)." : ".$msg."</br>");
error_log("\n".date(DATE_RFC2822)." : ".$msg."\r\n", 3, "app.log");
}
}

}
?>

<?php
// YY y ZZ se corresponden con los valores de identificacion del
// usuario en el sistema.

35
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

include(’httpPHPAltiria.php’);

$altiriaSMS = new AltiriaSMS();

$altiriaSMS->setApikey(’YY’);
$altiriaSMS->setApisecret(’ZZ’);
$altiriaSMS->setDebug(true);

//Use this ONLY with Sender allowed by altiria sales team

//$altiriaSMS->setSenderId(’TestAltiria’);
//Concatenate messages. If message length is more than 160 characters.
//It will consume as many credits as the number of messages needed
//$altiriaSMS->setConcat(true);
//Use unicode encoding (only value allowed).
//Can send áéı́óú but message length reduced to 70 characters
//$altiriaSMS->setEncoding(’unicode’);

//$sDestination = ’346xxxxxxxx’;
$sDestination = ’346xxxxxxxx,346yyyyyyyy’;
//$sDestination = array(’346xxxxxxxx’,’346yyyyyyyy’);

$response = $altiriaSMS->sendSMS($sDestination, "Mensaje de prueba");

if (!$response)
echo "El envı́o ha terminado en error";
else
echo $response;
?>

Ejemplo abriendo directamente un socket

<?php
// sDestination: lista de numeros de telefono separados por comas.
// Cada numero debe comenzar por el prefijo internacional de pais.
// sMessage: hasta 160 caracteres
// debug: Si es true muestra por pantalla la respuesta completa del servidor
// sSenderId: no es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
// YY y ZZ se corresponden con los valores de identificacion del
// usuario en el sistema.
function AltiriaSMS($sDestination, $sMessage, $debug, $sSenderId){

$sData =’cmd=sendsms&’;
$sData .=’apikey=YY&’;
$sData .=’apisecret=ZZ&’;
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
$sData .=’senderId=’.$sSenderId.’&’;
$sData .=’dest=’.str_replace(’,’,’&dest=’,$sDestination).’&’;
$sData .=’msg=’.urlencode(utf8_encode(substr($sMessage,0,160)));

//Tiempo máximo de espera para conectar con el servidor = 5 seg

$timeOut = 5;
$fp = fsockopen(’ssl://www.altiria.net’, 8443, $errno, $errstr, $timeOut);
if (!$fp) {
//Error de conexion o tiempo maximo de conexion rebasado
$output = "ERROR de conexion: $errno - $errstr<br />\n";
$output .= "Compruebe que ha configurado correctamente la direccion/url ";

36
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

$output .= "suministrada por altiria<br>";

return $output;
} else {
$buf = "POST /api/http HTTP/1.0\r\n";
$buf .= "Host: www.altiria.net\r\n";
$buf .= "Content-type: application/x-www-form-urlencoded; charset=UTF-8\r\n";
$buf .= "Content-length: ".strlen($sData)."\r\n";
$buf .= "\r\n";
$buf .= $sData;
fputs($fp, $buf);
$buf = "";

//Tiempo máximo de espera de respuesta del servidor = 60 seg

$responseTimeOut = 60;
stream_set_timeout($fp,$responseTimeOut);
stream_set_blocking ($fp, true);
if (!feof($fp)){
if (($buf=fgets($fp,128))===false){
// TimeOut?
$info = stream_get_meta_data($fp);
if ($info[’timed_out’]){
$output = ’ERROR Tiempo de respuesta agotado’;
return $output;
} else {
$output = ’ERROR de respuesta’;
return $output;
}
} else{
while(!feof($fp)){
$buf.=fgets($fp,128);
}
}
} else {
$output = ’ERROR de respuesta’;
return $output;
}
fclose($fp);
//Si la llamada se hace con debug, se muestra la respuesta completa del servidor
if ($debug){
print "Respuesta del servidor: <br>".$buf."<br>";
}
//Se comprueba que se ha conectado realmente con el servidor
//y que se obtenga un codigo HTTP OK 200
if (strpos($buf,"HTTP/1.1 200 OK") === false){
$output = "ERROR. Codigo error HTTP: ".substr($buf,9,3)."<br />\n";
$output .= "Compruebe que ha configurado correctamente la direccion/url ";
$output .= "suministrada por Altiria<br>";
return $output;
}
//Se comprueba la respuesta de Altiria
if (strstr($buf,"ERROR")){
$output = $buf."<br />\n";
$output .= " Ha ocurrido algun error. Compruebe la especificacion<br>";
return $output;
} else {

37
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

$output = $buf."<br />\n";

$output .= " Exito<br>";
return $output;
}
}
}

//No es posible utilizar el remitente en América pero sı́ en Espa~

na y Europa
$resp= AltiriaSMS("346xxxxxxxx,346yyyyyyyy", "Mensaje de prueba", false, "");
//Utilizar esta llamada solo si se cuenta con un remitente autorizado por Altiria
//$resp= AltiriaSMS("346xxxxxxxx,346yyyyyyyy", "Mensaje de prueba", false, "remitente");
echo $resp;

?>

2.10.3. Envı́o y firma de documento PDF en PHP

Ejemplo usando CURL

<?php
class AltiriaCert{

public $url;
public $debug;
public $apikey;
public $apisecret;

public function getUrl() {

return $this->url;
}

public function setUrl($val) {

$this->url = $val;
return $this;
}

public function getDebug() {

return $this->debug;
}

public function setDebug($val) {

$this->debug = $val;
return $this;
}

public function getApikey() {

return $this->apikey;
}

public function setApikey($val) {

$this->apikey = $val;
return $this;
}

38
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

public function getApisecret() {

return $this->apisecret;
}

public function setApisecret($val) {

$this->apisecret = $val;
return $this;
}

public function certPdf($destination, $type) {

$return=false;

// Set the curl parameters.

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $this->getUrl());

curl_setopt($ch, CURLOPT_VERBOSE, 1);

curl_setopt($ch, CURLOPT_HTTPHEADER,
array(’Content-type: application/x-www-form-urlencoded; charset=UTF-8’));
curl_setopt($ch, CURLOPT_HEADER, false);
// Max timeout in seconds to complete http request
curl_setopt($ch, CURLOPT_TIMEOUT, 60);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_POST, 1);

$COMANDO=’cmd=certpdffile&apikey=’.$this->getApikey().’&apisecret=’.$this->getApisecret();
$COMANDO.=’&destination=’.$destination;
$COMANDO.=’&type=’.$type;
$COMANDO.=’&websig=’.’true’;

// Set the request as a POST FIELD for curl.

curl_setopt($ch, CURLOPT_POSTFIELDS, $COMANDO);

// Get response from the server.

$httpResponse = curl_exec($ch);

if(curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200){

$this->logMsg("Server Altiria response: ".$httpResponse);
$json_parsed = json_decode($httpResponse);
$status = $json_parsed->status;
echo ’Código de estado Altiria: ’.$status.’<br/>’;
if ($status != ’000’){
$this->logMsg("Error cert pdf: ".$httpResponse);
return false;
}else
$return = $httpResponse;
}else{
$this->logMsg("Error cert pdf: ".curl_error($ch).
’(’.curl_errno($ch).’)’.$httpResponse);
$return = false;
}
curl_close($ch);

39
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

return $return;
}

public function uploadCertPdf($url, $path) {

$return=false;

// Set the curl parameters.

$ch = curl_init();

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(’Content-Type: application/pdf’));
$filesize = filesize($path);
$fp = fopen($path, ’rb’);
$binary = fread($fp, $filesize);
fclose($fp);
curl_setopt($ch, CURLOPT_POSTFIELDS, $binary);

// Get response from the server.

$httpResponse = curl_exec($ch);

if(curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200){

$this->logMsg("Server Altiria response: ".$httpResponse);

$json_parsed = json_decode($httpResponse);
$status = $json_parsed->status;
echo ’Código de estado Altiria: ’.$status.’<br/>’;
if ($status != ’000’){
$this->logMsg("Error upload cert pdf: ".$httpResponse);
return false;
}else
$return = $httpResponse;
}else{
$this->logMsg("Error upload cert pdf: ".curl_error($ch).
’(’.curl_errno($ch).’)’.$httpResponse);
$return = false;
}
curl_close($ch);
return $return;
}

public function logMsg($msg) {

if ($this->getDebug()===true)
error_log("\n".date(DATE_RFC2822)." : ".$msg."\r\n", 3, "app.log");
}
}
?>

<?php
include(’httpPHPAltiriaCert.php’);

// YY y ZZ se corresponden con los valores de identificacion

// del usuario en el sistema.

40
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

$altiriaCert = new AltiriaCert();

$altiriaCert->setUrl("https://www.altiria.net:8443/api/http");
$altiriaCert->setApikey(’YY’);
$altiriaCert->setApisecret(’ZZ’);
$altiriaCert->setDebug(true);

$response = $altiriaCert->certPdf(’346xxxxxxxx’, ’simple’);

if (!$response)
echo "El certificado ha terminado en error";
else {
echo "Response certpdffile: ".$response."\n";
$decodedJson = json_decode($response, true);
$responseUpload = $altiriaCert->uploadCertPdf($decodedJson[’url’],’file.pdf’);

if (!$responseUpload)
echo ’Error al subir el certificado’;
else
echo ’Response upload certPdf: ’.$responseUpload;
}
?>

Ejemplo abriendo directamente un socket

<?php
// destination: destinatario.
// type: simple/premium
// debug: Si es true muestra por pantalla la respuesta completa del servidor
// YY y ZZ se corresponden con los valores de identificacion del
// usuario en el sistema.
function AltiriaCertPdfFile($destination, $type, $debug){

$sData =’cmd=certpdffile&’;
$sData .=’apikey=YY&’;
$sData .=’apisecret=ZZ&’;
$sData .=’destination=’.$destination.’&’;
$sData .=’type=’.$type.’&’;
$sData .=’websig=’.’true’.’&’;

//Tiempo máximo de espera para conectar con el servidor = 5 seg

$timeOut = 5;
$fp = fsockopen(’ssl://www.altiria.net’, 8443, $errno, $errstr, $timeOut);
if (!$fp) {
//Error de conexion o tiempo maximo de conexion rebasado
$output = "ERROR de conexion: $errno - $errstr<br />\n";
$output .= "Compruebe que ha configurado correctamente la direccion/url ";
$output .= "suministrada por altiria<br>";
return $output;
} else {
$buf = "POST /api/http HTTP/1.0\r\n";
$buf .= "Host: www.altiria.net\r\n";
$buf .= "Content-type: application/x-www-form-urlencoded; charset=UTF-8\r\n";
$buf .= "Content-length: ".strlen($sData)."\r\n";
$buf .= "\r\n";

41
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

$buf .= $sData;
fputs($fp, $buf);
$buf = "";

//Tiempo máximo de espera de respuesta del servidor = 60 seg

$responseTimeOut = 60;
stream_set_timeout($fp,$responseTimeOut);
stream_set_blocking ($fp, true);
if (!feof($fp)){
if (($buf=fgets($fp,128))===false){
// TimeOut?
$info = stream_get_meta_data($fp);
if ($info[’timed_out’]){
$output = ’ERROR Tiempo de respuesta agotado’;
return $output;
} else {
$output = ’ERROR de respuesta’;
return $output;
}
} else{
while(!feof($fp)){
$buf.=fgets($fp,128);
}
}
} else {
$output = ’ERROR de respuesta’;
return $output;
}

fclose($fp);

//Si la llamada se hace con debug, se muestra la respuesta completa del servidor
if ($debug){
return $buf;
}

//Se comprueba que se ha conectado realmente con el servidor

//y que se obtenga un codigo HTTP OK 200
if (strpos($buf,"HTTP/1.1 200 OK") === false){
$output = "ERROR. Codigo error HTTP: ".substr($buf,9,3)."<br />\n";
$output .= "Compruebe que ha configurado correctamente la direccion/url ";
$output .= "suministrada por Altiria<br>";
return $output;
}
//Se comprueba la respuesta de Altiria
echo "buffer: ".$buf;

$json_parsed = json_decode($buf);
$status = $json_parsed->status;
echo ’Código de estado Altiria: ’.$status.’<br/>’;
if ($status != ’000’){
$output = $buf."<br />\n";
$output .= " Ha ocurrido algun error. Compruebe la especificacion<br>";
return $output;
}else

42
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

return $output;
}
}

function AltiriaCertPdfUpload($url, $path, $debug){

//Read cert file

$filesize = filesize($path);
$fp = fopen($path, ’rb’);
$sData = fread($fp, $filesize);
fclose($fp);

//Tiempo máximo de espera para conectar con el servidor = 5 seg

$timeOut = 5;
$fp = fsockopen(’ssl://www.altiria.net’, 8443, $errno, $errstr, $timeOut);
if (!$fp) {
//Error de conexion o tiempo maximo de conexion rebasado
$output = "ERROR de conexion: $errno - $errstr<br />\n";
$output .= "Compruebe que ha configurado correctamente la direccion/url ";
$output .= "suministrada por altiria<br>";
return $output;
} else {
$url = substr($url,strrpos($url,"80")+2);
$buf = "POST ".$url." HTTP/1.0\r\n";
$buf .= "Host: www.altiria.net\r\n";
$buf .= "Content-type: application/pdf;\r\n";
$buf .= "Content-length: ".strlen($sData)."\r\n";
$buf .= "\r\n";
$buf .= $sData;
fputs($fp, $buf);
$buf = "";

//Tiempo máximo de espera de respuesta del servidor = 60 seg

$responseTimeOut = 60;
stream_set_timeout($fp,$responseTimeOut);
stream_set_blocking ($fp, true);
if (!feof($fp)){
if (($buf=fgets($fp,128))===false){
// TimeOut?
$info = stream_get_meta_data($fp);
if ($info[’timed_out’]){
$output = ’ERROR Tiempo de respuesta agotado’;
return $output;
} else {
$output = ’ERROR de respuesta’;
return $output;
}
} else{
while(!feof($fp)){
$buf.=fgets($fp,128);
}
}
} else {
$output = ’ERROR de respuesta’;
return $output;

43
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

fclose($fp);

//Si la llamada se hace con debug, se muestra la respuesta completa del servidor
if ($debug){
return $buf;
}

//Se comprueba que se ha conectado realmente con el servidor

//y que se obtenga un codigo HTTP OK 200
if (strpos($buf,"HTTP/1.1 200 OK") === false){
$output = "ERROR. Codigo error HTTP: ".substr($buf,9,3)."<br />\n";
$output .= "Compruebe que ha configurado correctamente la direccion/url ";
$output .= "suministrada por Altiria<br>";
return $output;
}
//Se comprueba la respuesta de Altiria
$json_parsed = json_decode($buf);
$status = $json_parsed->status;
echo ’Código de estado Altiria: ’.$status.’<br/>’;
if ($status != ’000’){
$output = $buf."<br />\n";
$output .= " Ha ocurrido algun error. Compruebe la especificacion<br>";
return $output;
}else
return $output;
}
}

$resp= AltiriaCertPdfFile(’346xxxxxxxx’, ’simple’, true);

echo "=>Response certpdffile:\n".$resp."\n\n";

//Get json object

$json = substr($resp,strrpos($resp,"{"));

//Parse json object

$decodedJson = json_decode($json, true);

if($decodedJson[’status’]==’000’) {
$resp= AltiriaCertPdfUpload($decodedJson[’url’],’file.pdf’,true);
echo "=>Response certPDf upload:\n".$resp."\n";
}
?>

2.10.4. Envı́o de un mensaje en JAVA

Ejemplo usando Maven

Consultar la sección 2.10.1.

44
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Ejemplo usando Httpclient

En este ejemplo se utiliza Httpclient 4.5 como cliente HTTP (ver [HTTPCLIENT]).
Esta librerı́a depende de los siguientes paquetes:

commons-logging versión 1.2

commons-codec versión 1.9

httpcore versión 4.4.3

//Se fija el tiempo máximo de espera para conectar con el servidor (5000)
//Se fija el tiempo máximo de espera de la respuesta del servidor (60000)
RequestConfig config = RequestConfig.custom()
.setConnectTimeout(5000)
.setSocketTimeout(60000)
.build();

//Se inicia el objeto HTTP

HttpClientBuilder builder = HttpClientBuilder.create();
builder.setDefaultRequestConfig(config);
CloseableHttpClient httpClient = builder.build();

//Se fija la URL sobre la que enviar la petición POST

HttpPost post = new HttpPost("https://www.altiria.net:8443/api/http");

//Se crea la lista de parámetros a enviar en la petición POST

List<NameValuePair> parametersList = new ArrayList <NameValuePair>();
//YY y ZZ se corresponden con los valores de identificación del
//usuario en el sistema.
parametersList.add(new BasicNameValuePair("cmd", "sendsms"));
parametersList.add(new BasicNameValuePair("apiKey", "YY"));
parametersList.add(new BasicNameValuePair("apiSecret", "ZZ"));
parametersList.add(new BasicNameValuePair("dest", "346xxxxxxxx"));
parametersList.add(new BasicNameValuePair("dest", "346yyyyyyyy"));
parametersList.add(new BasicNameValuePair("msg", "Mesaje de prueba"));
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
//Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
//parametersList.add(new BasicNameValuePair("senderId", "remitente"));

try {
//Se fija la codificacion de caracteres de la peticion POST
post.setEntity(new UrlEncodedFormEntity(parametersList,"UTF-8"));
}
catch(UnsupportedEncodingException uex) {
System.out.println("ERROR: codificación de caracteres no soportada");
}

CloseableHttpResponse response = null;

try {
System.out.println("Enviando petición");
//Se envı́a la petición
response = httpClient.execute(post);
//Se consigue la respuesta

45
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

String resp = EntityUtils.toString(response.getEntity());

//Error en la respuesta del servidor

if (response.getStatusLine().getStatusCode()!=200){
System.out.println("ERROR: Código de error HTTP: " + response.getStatusLine().getStatusCode());
System.out.println("Compruebe que ha configurado correctamente la direccion/url ");
System.out.println("suministrada por Altiria");
return;
}else {
//Se procesa la respuesta capturada en la cadena ’response’
if (resp.startsWith("ERROR")){
System.out.println(resp);
System.out.println("Código de error de Altiria. Compruebe las especificaciones");
} else
System.out.println(resp);
}
}
catch (Exception e) {
System.out.println("Excepción");
e.printStackTrace();
return;
}
finally {
//En cualquier caso se cierra la conexión
post.releaseConnection();
if(response!=null) {
try {
response.close();
}
catch(IOException ioe) {
System.out.println("ERROR cerrando recursos");
}
}
}

2.10.5. Envı́o y firma de documento PDF en JAVA

Ejemplo en Java utilizando Httpclient 4.5 como cliente HTTP (ver [HTTPCLIENT]).
Esta librerı́a depende de los siguientes paquetes:

commons-logging versión 1.2

commons-codec versión 1.9

httpcore versión 4.4.3

Adicionalmente se utilizan las siguientes librerı́as:

gson versión 2.8.5

commons-io versión 2.6

//Se fija el tiempo máximo de espera para conectar con el servidor (5000)

46
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

//Se fija el tiempo máximo de espera de la respuesta del servidor (60000)

RequestConfig config = RequestConfig.custom()
.setConnectTimeout(5000)
.setSocketTimeout(60000)
.build();

//Se inicia el objeto HTTP

HttpClientBuilder builder = HttpClientBuilder.create();
builder.setDefaultRequestConfig(config);
CloseableHttpClient httpClient = builder.build();

//Se fija la URL sobre la que enviar la petición POST

HttpPost post = new HttpPost("https://www.altiria.net:8443/api/http");

//Se crea la lista de parámetros a enviar en la petición POST

List<NameValuePair> parametersList = new ArrayList <NameValuePair>();
// YY y ZZ se corresponden con los valores de identificación del
// usuario en el sistema.
parametersList.add(new BasicNameValuePair("cmd", "certpdffile"));
parametersList.add(new BasicNameValuePair("apikey", "YY"));
parametersList.add(new BasicNameValuePair("apisecret", "ZZ"));
parametersList.add(new BasicNameValuePair("destination", "346xxxxxxxx"));
parametersList.add(new BasicNameValuePair("type", "simple"));
parametersList.add(new BasicNameValuePair("websig", "true"));

try {
//Se fija la codificacion de caracteres de la peticion POST
post.setEntity(new UrlEncodedFormEntity(parametersList,"UTF-8"));
}catch(UnsupportedEncodingException uex) {
System.out.println("ERROR: codificación de caracteres no soportada");
}

CloseableHttpResponse response = null;

InputStream is = null;
try {
System.out.println("Enviando petición al comando certPdfFile");
//Se envı́a la petición
response = httpClient.execute(post);
//Se consigue la respuesta
String resp = EntityUtils.toString(response.getEntity());

//Error en la respuesta del servidor

if (response.getStatusLine().getStatusCode()!=200){
System.out.println("ERROR: Código de error HTTP: "
+ response.getStatusLine().getStatusCode());
System.out.println("Compruebe que ha configurado"
+" correctamente la direccion/url ");
System.out.println("suministrada por Altiria");
return;
}else {
if(response!=null) {
response.close();
response = null;
}
//Se procesa la respuesta capturada en la cadena ’response’

47
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Gson gson = new GsonBuilder().create();

TreeMap<String,String> map = gson.fromJson(resp, TreeMap.class);

String status = map.get("status");

if(!status.equals("000"))
System.out.println("ERROR: código de estado: "+status);
else {
String url = map.get("url");
File file = new File("file.pdf");
is = new FileInputStream(file);

post = new HttpPost(url);

post.setEntity(new ByteArrayEntity(IOUtils.toByteArray(is)));
post.setHeader("Content-type", "application/pdf");

System.out.println("Subiendo fichero");
//Se envı́a la petición
response = httpClient.execute(post);
//Se consigue la respuesta
resp = EntityUtils.toString(response.getEntity());

if (response.getStatusLine().getStatusCode() != 200)
System.out.println("ERROR AL SUBIR EL FICHERO:Código de error HTTP: "
+response.getStatusLine().getStatusCode());
else {
// Se procesa la respuesta capturada en la cadena ’response’
gson = new GsonBuilder().create();
map = gson.fromJson(resp, TreeMap.class);
status = map.get("status");
if(status.equals("000"))
System.out.println("Fichero subido correctamente: "+resp);
else
System.out.println("ERROR: Error al subir el fichero: "+resp);
}
}
}
}catch (Exception e) {
System.out.println("Excepción");
e.printStackTrace();
return;
}finally {
//En cualquier caso se cierra la conexión
post.releaseConnection();
if(response!=null) {
try {
response.close();
}catch(IOException ioe) {
System.out.println("ERROR cerrando recursos");
}
}
if(is!=null) {
try {
is.close();
}catch(IOException ioe) {
System.out.println("ERROR cerrando recursos");

48
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

}
}
}

2.10.6. Envı́o de un mensaje en VBA

Ejemplo en Visual Basic para aplicaciones usando ServerXMLHTTP como cliente HTTP

’Se fija la URL sobre la que enviar la petición POST

Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
objHTTP.Open "POST", "https://www.altiria.net:8443/api/http", False
objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded; charset=UTF-8"
’YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
objHTTP.Send ("cmd=sendsms&apikey=YY&apisecret=ZZ&dest=346xxxxxxxx&msg=Mensaje de prueba")
’No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
’Utilizar esta llamada solo si se cuenta con un remitente autorizado por Altiria
’objHTTP.Send ("cmd=sendsms&apiKey=YY&apiSecret=ZZ
’ &dest=346xxxxxxxx&msg=Mensaje de prueba&senderId=remitente")
MsgBox (objHTTP.Status)
MsgBox (objHTTP.ResponseText)

2.10.7. Envı́o de un mensaje en .NET

Todos los ejemplos de .NET se han desarrollado con Visual Studio 2015

Ejemplo en Visual C# usando HttpWebRequest 4.0 como cliente HTTP

//Se fija la URL sobre la que enviar la petición POST

HttpWebRequest loHttp =
(HttpWebRequest)WebRequest.Create("https://www.altiria.net:8443/api/http");

// Compone el mensaje a enviar

// YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
string lcPostData =
"cmd=sendsms&apikey=YY&apisecret=ZZ&dest=346xxxxxxxx&dest=346yyyyyyyy&msg=Mensaje de prueba";
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
//Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
//cmd=cmd + "&senderId=remitente";

// Se codifica en utf-8
byte[] lbPostBuffer = System.Text.Encoding.GetEncoding("utf-8").GetBytes(lcPostData);
loHttp.Method = "POST";
loHttp.ContentType = "application/x-www-form-urlencoded";
loHttp.ContentLength = lbPostBuffer.Length;

//Fijamos tiempo de espera de respuesta = 60 seg

loHttp.Timeout = 60000;
String error = "";
String response = "";
// Envı́a la peticion
try {
Stream loPostData = loHttp.GetRequestStream();

49
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

loPostData.Write(lbPostBuffer, 0, lbPostBuffer.Length);
loPostData.Close();
// Prepara el objeto para obtener la respuesta
HttpWebResponse loWebResponse = (HttpWebResponse)loHttp.GetResponse();
// La respuesta vendrı́a codificada en utf-8
Encoding enc = System.Text.Encoding.GetEncoding("utf-8");
StreamReader loResponseStream =
new StreamReader(loWebResponse.GetResponseStream(), enc);
// Conseguimos la respuesta en una cadena de texto
response = loResponseStream.ReadToEnd();
loWebResponse.Close();
loResponseStream.Close();
}
catch (WebException e) {
if (e.Status == WebExceptionStatus.ConnectFailure)
error = "Error en la conexión";
else if (e.Status == WebExceptionStatus.Timeout)
error = "Error TimeOut";
else
error = e.Message;
}
finally {
if (error != "")
Console.WriteLine(error);
else
Console.WriteLine(response);
}

Ejemplo en Visual C# usando HttpClient 4.5 como cliente HTTP

HttpClient client = new HttpClient();

client.BaseAddress = new Uri("https://www.altiria.net:8443");
//Establecemos el TimeOut para obtener la respuesta del servidor
client.Timeout = TimeSpan.FromSeconds(60);

//Se compone el mensaje a enviar

// YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
var postData = new List<KeyValuePair<string, string>>();
postData.Add(new KeyValuePair<string, string>("cmd", "sendsms"));
postData.Add(new KeyValuePair<string, string>("apiKey", "YY"));
postData.Add(new KeyValuePair<string, string>("apiSecret", "ZZ"));
postData.Add(new KeyValuePair<string, string>("dest", "346xxxxxxxx"));
postData.Add(new KeyValuePair<string, string>("dest", "346yyyyyyyy"));
postData.Add(new KeyValuePair<string, string>("msg", "Mensaje de prueba"));
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
//Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
//postData.Add(new KeyValuePair<string, string>("senderId", "remitente"));

HttpContent content = new FormUrlEncodedContent(postData);

String err = "";
String resp="";
try {
//Se fija la URL sobre la que enviar la petición POST
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "/api/http");
request.Content = content;

50
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

content.Headers.ContentType.CharSet = "UTF-8";
request.Content.Headers.ContentType =
new MediaTypeHeaderValue("application/x-www-form-urlencoded");
HttpResponseMessage response = client.SendAsync(request).Result;
var responseString = response.Content.ReadAsStringAsync();
resp = responseString.Result;
}
catch (Exception e) {
err = e.Message;
}
finally {
if (err != "")
Console.WriteLine(err);
else
Console.WriteLine(resp);
}

Ejemplo en Visual Basic usando HttpWebRequest 4.0 como cliente HTTP

’Se fija la URL sobre la que enviar la petición POST

Dim loHttp As HttpWebRequest
loHttp =
CType(WebRequest.Create("https://www.altiria.net:8443/api/http"), HttpWebRequest)

’Compone el mensaje a enviar

’YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
Dim lcPostData As String =
"cmd=sendsms&apikey=YY&apisecret=ZZ&dest=346xxxxxxxx&dest=346yyyyyyyy&msg=Texto de prueba"
’ No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
’ Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
’ lcPostData += "&senderId=remitente"

’Lo codifica en utf-8

Dim lbPostBuffer As Byte() =
System.Text.Encoding.GetEncoding("utf-8").GetBytes(lcPostData)

loHttp.Method = "POST"
loHttp.ContentType = "application/x-www-form-urlencoded"
loHttp.ContentLength = lbPostBuffer.Length

’Fijamos TimeOut de espera de respuesta del servidor = 60 seg

loHttp.Timeout = 60000
Dim err As String = ""
Dim response As String = ""

’Envı́a la peticion
Try
Dim loPostData As System.IO.Stream = loHttp.GetRequestStream()
loPostData.Write(lbPostBuffer, 0, lbPostBuffer.Length)
loPostData.Close()

’Prepara el objeto para obtener la respuesta

Dim loWebResponse As HttpWebResponse = CType(loHttp.GetResponse(), HttpWebResponse)
’La respuesta vendrı́a codificada en utf-8

51
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Dim enc As System.Text.Encoding = System.Text.Encoding.GetEncoding("utf-8")

Dim loResponseStream As System.IO.StreamReader =
New System.IO.StreamReader(loWebResponse.GetResponseStream(), enc)
’Conseguimos la respuesta en una cadena de texto
response = loResponseStream.ReadToEnd()
loWebResponse.Close()
loResponseStream.Close()

Catch e As WebException
If (e.Status = WebExceptionStatus.ConnectFailure) Then
err = "Error en la conexión"
ElseIf (e.Status = WebExceptionStatus.Timeout) Then
err = "Error Time Out"
Else
err = e.Message
End If

Finally
If (err <> "") Then
Console.WriteLine(err)
Else
Console.WriteLine(response)
End If
End Try

Ejemplo en Visual Basic usando HttpClient 4.5 como cliente HTTP

Dim client As HttpClient = New HttpClient

client.BaseAddress = New Uri("Https://www.altiria.net:8443")
’Fijamos TimeOut de espera de respuesta del servidor = 60 seg
client.Timeout = TimeSpan.FromSeconds(60)

’Se compone el mensaje a enviar

’YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
Dim postData As List(Of KeyValuePair(Of String, String))
postData = New List(Of KeyValuePair(Of String, String))
postData.Add(New KeyValuePair(Of String, String)("cmd", "sendsms"))
postData.Add(New KeyValuePair(Of String, String)("apiKey", "YY"))
postData.Add(New KeyValuePair(Of String, String)("apiSecret", "ZZ"))
postData.Add(New KeyValuePair(Of String, String)("dest", "346xxxxxxxx"))
postData.Add(New KeyValuePair(Of String, String)("dest", "346yyyyyyyy"))
postData.Add(New KeyValuePair(Of String, String)("msg", "Mensaje de prueba"))
’ No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
’ Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
’ postData.Add(New KeyValuePair(Of String, String)("senderId", "remitente"))

Dim content As HttpContent = New FormUrlEncodedContent(postData)

Dim err = ""
Dim resp = ""
Try
’Se fija la URL sobre la que enviar la petición POST
Dim request As HttpRequestMessage
request = New HttpRequestMessage(HttpMethod.Post, "/api/http")
request.Content = content
content.Headers.ContentType.CharSet = "UTF-8"

52
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Dim contentType = "application/x-www-form-urlencoded"

request.Content.Headers.ContentType = New Headers.MediaTypeHeaderValue(contentType)
Dim response As HttpResponseMessage = client.SendAsync(request).Result

Dim responseString = response.Content.ReadAsStringAsync

resp = responseString.Result

Catch e1 As Exception
err = e1.Message
Finally
If (err <> "") Then
Console.WriteLine(err)
Else
Console.WriteLine(resp)
End If
End Try

2.10.8. Envı́o de un mensaje en Delphi

Se ha programado Delphi en RAD Studio 10.

Ejemplo en usando IdHTTP como cliente HTTP

try
//Se fija la URL sobre la que enviar la petición POST
SUrl:=’https://www.altiria.net:8443/api/http’;
//Compone el mensaje a enviar
//YY y ZZ se corresponden con los valores de identificación del usuario en el sistema
Parametros := TStringList.Create();
Parametros.Add(’cmd=sendsms’);
Parametros.Add(’apikey=YY’);
Parametros.Add(’apisecret=ZZ’);
Parametros.Add(’dest=346xxxxxxxx’);
Parametros.Add(’dest=346yyyyyyyy’);
Parametros.Add(UTF8Encode(’msg=Mensaje de prueba’));
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
//Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
//Parametros.Add(’senderId=remitente’);

IdHTTP1:= TIdHTTP.Create(nil);

//Se fija el tiempo máximo de espera para conectar con el servidor (5000)
//Se fija el tiempo máximo de espera de la respuesta del servidor (60000)
IdHTTP1.ConnectTimeout := 5000;
IdHTTP1.ReadTimeout:=60000;

IdHTTP1.Request.ContentType :=’application/x-www-form-urlencoded’;
IdHTTP1.Request.Charset := ’UTF-8’;
IdHTTP1.Request.ContentEncoding := ’UTF-8’;

// Enviamos un mensaje, recibiendo en "DResultado" la respuesta del servidor

DResultado:=IdHTTP1.Post(SUrl,Parametros);
WriteLn(DResultado);

53
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

except
on E: Exception do
if E.ClassName=’EIdConnectTimeout’ then
WriteLn (’ERROR Connect Timeout’)
else if E.ClassName=’EIdReadTimeout’ then
WriteLn (’ERROR Response Timeout’)
else
Writeln(E.ClassName, ’: ’, E.Message);
end;
Parametros.Free;
IdHTTP1.Free;
end.

Ejemplo en usando TnetHTTPClient como cliente HTTP

begin
try
client := TNetHTTPClient.Create(nil);
client.ContentType :=’application/x-www-form-urlencoded’;
//Se fija la URL sobre la que enviar la petición POST
SUrl:=’https://www.altiria.net:8443/api/http’;
//YY y ZZ se corresponden con los valores de identificación del usuario en el sistema
Parametros := TStringList.Create();
Parametros.Add(’cmd=sendsms’);
Parametros.Add(’apikey=YY’);
Parametros.Add(’apisecret=ZZ’);
Parametros.Add(’dest=346xxxxxxxx’);
Parametros.Add(’dest=346yyyyyyyy’);
Parametros.Add(UTF8Encode(’msg=Mensaje de prueba’));
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
//Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
//Parametros.Add(’senderId=remitente’);

Response:=client.Post(SUrl,Parametros);

if Response.StatusCode = 200 then

WriteLn(Response.ContentAsString())
else
begin
WriteLn(’Código de error: ’ + IntToStr(Response.StatusCode));
WriteLn(Response.StatusText);
end;
except
on E: ENetHTTPClientException do
WriteLn (’ERROR Conexión. ’ + E.Message);

on E: Exception do
Writeln(E.ClassName, ’: ’, E.Message);
end;
Parametros.Free;
Client.Free;
end.

54
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

2.10.9. Envı́o de un mensaje en Perl

Ejemplo en strawberryPerl 5.22.0.1 para Windows (ver [PERL]) usando LWP::UserAgent como
cliente HTTP.

#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use utf8;
use Encode qw(decode encode);

my $ua = new LWP::UserAgent();

# Timeout en segundos
$ua->timeout(60);
# Se fija la URL sobre la que enviar la petición POST
my $req = new HTTP::Request POST => "https://www.altiria.net:8443/api/http";
$req->header(’content-type’=>’application/x-www-form-urlencoded;charset=UTF-8’);

# YY y ZZ se corresponden con los valores de identificación del usuario en el sistema

my $data =("cmd=sendsms&apikey=YY&apisecret=ZZ".
#"&dest=346xxxxxxx&dest=346yyyyyyyy&msg=Mensaje de prueba".
#No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
#Descomentar la lı́nea solo si se cuenta con un remitente autorizado por Altiria
#"&senderId=remitente".
"");

$data = encode(’UTF8’,$data);

$req->content($data);

my $resp = $ua->request($req);
if ($resp->is_success) {
# $resp->code = 200
my $message = $resp->decoded_content;
print "\nRespuesta: \n$message\n";
}else {
print "HTTP POST error code: ", $resp->code, "\n";
print $resp->decoded_content;
}

2.10.10. Envı́o y firma de documento PDF en Perl

Ejemplo en strawberryPerl 5.22.0.1 para Windows (ver [PERL]) usando LWP::UserAgent como
cliente HTTP.
Es preciso además instalar los módulos JSON y JSON::Parse.

#!/usr/bin/perl

use strict;
use warnings;
use LWP::UserAgent;
use utf8;
use Encode qw(decode encode);

55
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

use JSON;
use JSON::Parse ’parse_json’;
use Try::Tiny;

binmode(STDOUT, ":utf8");

try {
my $ua = new LWP::UserAgent();
# Timeout en segundos
$ua->timeout(60);
# Se fija la URL sobre la que enviar la petición POST
my $req = new HTTP::Request POST => "https://www.altiria.net:8443/api/http";
$req->header(’content-type’=>
’application/x-www-form-urlencoded;charset=UTF-8’);

# YY y ZZ se corresponden con los valores de identificación del

# usuario en el sistema
# my $data =("cmd=certpdffile&apikey=XX&apisecret=YY".
"&destination=346xxxxxxxx&type=simple&websig=true");

$data = encode(’UTF8’,$data);

$req->content($data);

my $resp = $ua->request($req);
if ($resp->is_success) {
# $resp->code = 200
my $message = $resp->decoded_content;
print "\nRespuesta comando certPdfFile: \n$message\n";

my $parsedJson = parse_json ($message);

my $status = $parsedJson->{status};
if ($status != ’000’) {
print "\nERROR COMANDO CERTPDFFILE: Código Altiria: \n$status\n";
}else {
print "\nSubiendo fichero\n";

# Se fija la URL sobre la que enviar la petición POST

$req = new HTTP::Request POST => $parsedJson->{url};
$req->header(’content-type’=>’application/pdf’);

# Se lee el fichero y se almacena en un buffer

my $fname = ’file.pdf’;
my $BLOCK_SIZE=1024;
open(F,"<$fname") or die("Fichero no encontrado: $fname, $!");
binmode(F);
my $buf;
my $ct=0;
while(read(F,$buf,$BLOCK_SIZE,$ct*$BLOCK_SIZE)){
$ct++;
}
close(F);

$req->content($buf);

56
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

$resp = $ua->request($req);
if ($resp->is_success) {
$message = $resp->decoded_content;
print "\nRespuesta al subir certificado: \n$message\n";
$parsedJson = parse_json ($message);
$status = $parsedJson->{status};
if ($status != ’000’) {
print "\nERROR AL SUBIR FICHERO:".
" Código Altiria: \n$status\n";
}else {
print "\nProceso terminado con exito.\n";
}
}else {
print "HTTP POST error al subir el fichero.".
" Code: ", $resp->code, "\n";
print $resp->decoded_content;
}
}
}else {
print "HTTP POST error en la petición al comando. Code: ", $resp->code, "\n";
print $resp->decoded_content;
}
}catch { #Se capturan posibles errores en el lado cliente
print "Error inesperado: $_\n";
};

2.10.11. Envı́o de un mensaje en Ruby

Ejemplo en Ruby de cliente HTTP.

# encoding: UTF-8

require ’net/http’
require ’json’
require ’uri’

def altiriaSms(destinations, message, senderId, debug)

if debug
puts "Enter altiriaSms: destinations=#{destinations}, message=#{message}, senderId=#{senderId}"
end

begin

#Se fija la URL sobre la que enviar la petición POST

url = "https://www.altiria.net:8443/api/http"
uri = URI.parse(url)
http = Net::HTTP.new(uri.host, uri.port)
#Se fija el tiempo máximo de espera para conectar con el servidor (5 segundos)
#Se fija el tiempo máximo de espera de la respuesta del servidor (60 segundos)
http.open_timeout = 5
http.read_timeout = 60

#Se crea la lista de parámetros a enviar en la petición POST

#YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.

57
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

#No es posible utilizar el remitente en América pero sı́ en Espa~

na y Europa
post_data = {’cmd’ => ’sendsms’, ’apikey’ => ’YY’, ’apisecret’ => ’ZZ’,
’dest’ => destinations.split(","), ’msg’ => message, ’senderId’ => senderId}

#Se envı́a la petición y se consigue la respuesta

#La codificación es de tipo "application/x-www-form-urlencoded;charset=utf-8"
#fijado por el método "post_form"
response = Net::HTTP.post_form( uri, post_data)

if debug
unless response.code == "200" #Error en la respuesta del servidor
puts("ERROR GENERAL: #{response.code}")
puts("#{response.body}")
else #Se procesa la respuesta
puts("Código de estado HTTP: #{response.code}")
if "#{response.body}".include? "ERROR errNum:"
puts("Error de Altiria: #{response.body}")
else
puts("Cuerpo de la respuesta: \n#{response.body}")
end
end
end

return response

rescue Net::OpenTimeout
puts "Tiempo de conexión agotado"
rescue Net::ReadTimeout
puts "Tiempo de respuesta agotado"
rescue Exception => e
puts "Error interno: #{e.class}"
end

end

puts "The function altiriaSms returns:"+

"#{altiriaSms(’346xxxxxxxx,346yyyyyyyy’,’Mensaje de prueba’, ’’, true).body}"
#No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
#Utilizar esta llamada solo si se cuenta con un remitente autorizado por Altiria
#puts "The function altiriaSms returns:"+
#"#{altiriaSms(’346xxxxxxxx,346yyyyyyyy’,’Mensaje de prueba’, ’remitente’, true).body}"

2.10.12. Envı́o y firma de documento PDF en Ruby

Ejemplo en Ruby de cliente HTTP.

# encoding: utf8

require ’net/http’
require ’json’
require ’uri’

def altiriaCert(destination, type)

puts "Enter altiriaCert: destination=#{destination}, type=#{type}"

58
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

begin
#Se fija la URL sobre la que enviar la petición POST
url = "https://www.altiria.net:8443/api/http"
uri = URI.parse(url)
http = Net::HTTP.new(uri.host, uri.port)
#Se fija el tiempo máximo de espera para conectar con el servidor (5 segundos)
#Se fija el tiempo máximo de espera de la respuesta del servidor (60 segundos)
http.open_timeout = 5
http.read_timeout = 60

#Se crea la lista de parámetros a enviar en la petición POST

#YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
post_data = {’cmd’ => ’certpdffile’,
’apikey’ => ’YY’, ’apisecret’ => ’ZZ’,
’destination’ => destination, ’type’ => type, ’webSig’ => ’true’}

#Se envı́a la petición y se consigue la respuesta

#La codificación es de tipo "application/x-www-form-urlencoded;charset=utf-8"
#fijado por el método "post_form"
response = Net::HTTP.post_form( uri, post_data)
unless response.code == "200" #Error en la respuesta del servidor
puts("ERROR GENERAL cmd: #{response.code}")
puts("#{response.body}")
else #Se procesa la respuesta
puts("Código de estado HTTP cmd: #{response.code}")
puts("Cuerpo respuesta cmd: #{response.body}")
parsedJson = JSON.parse(response.body)
unless parsedJson[’status’].include? "000"
puts("Error de Altiria cmd: #{response.body}")
else
puts("Código de estado Alriria cmd: #{parsedJson[’status’]}")

file = File.open("file.pdf", "rb")

#Se fija la URL base de los recursos REST

uri = URI.parse(parsedJson[’url’])

#Se inicia el objeto HTTP y se envı́a la petición

#Se a~
nade el JSON al cuerpo de la petición codificado en UTF-8
request = Net::HTTP::Post.new(uri.request_uri,’Content-Type’ => ’application/pdf’)
request.body = file.read

#Se consigue la respuesta

response = http.request(request)
unless response.code == "200" #Error en la respuesta del servidor
puts("ERROR GENERAL subiendo fichero: #{response.code}")
puts("#{response.body}")
else #Se procesa la respuesta
puts("Código de estado HTTP subiendo fichero: #{response.code}")
puts("Cuerpo respuesta subiendo fichero: #{response.body}")
parsedJson = JSON.parse(response.body)
unless parsedJson[’status’].include? "000"
puts("Error de Altiria subiendo fichero: #{response.body}")
else

59
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

puts("Proceso terminado con éxito")

end
end
end
end
rescue Net::OpenTimeout
puts "Tiempo de conexión agotado"
rescue Net::ReadTimeout
puts "Tiempo de respuesta agotado"
rescue Exception => e
puts "Error interno: #{e}"
end
end

altiriaCert(’346xxxxxxxx’,’simple’)

2.10.13. Envı́o de un mensaje en Python

Ejemplo usando Pip

Consultar la sección 2.10.1.

Ejemplo usando Request

En este ejemplo se utiliza la librerı́a Requests como cliente HTTP (ver [REQUESTS]).

# -*- coding: utf-8 -*-

import requests

def altiriaSms(destinations, message, senderId, debug):

if debug:
print ’Enter altiriaSms: ’+destinations+’, message: ’+message+’, senderId: ’+senderId

try:
#Se crea la lista de parámetros a enviar en la petición POST
#YY y ZZ se corresponden con los valores de identificación del usuario en el sistema.
payload = [
(’cmd’, ’sendsms’),
(’apikey’, ’YY’),
(’apisecret’, ’ZZ’),
#No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
(’senderId’, senderId),
(’msg’, message)
]

#add destinations
for destination in destinations.split(","):
payload.append((’dest’, destination))

#Se fija la codificacion de caracteres de la peticion POST

contentType = {’Content-Type’:’application/x-www-form-urlencoded;charset=utf-8’}

#Se fija la URL sobre la que enviar la petición POST

60
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

url = ’https://www.altiria.net:8443/api/http’

#Se envı́a la petición y se recupera la respuesta

r = requests.post(url,
data=payload,
headers=contentType,
#Se fija el tiempo máximo de espera para conectar con el servidor (5 segundos)
#Se fija el tiempo máximo de espera de la respuesta del servidor (60 segundos)
timeout=(5, 60)) #timeout(timeout_connect, timeout_read)

if debug:
if str(r.status_code) != ’200’: #Error en la respuesta del servidor
print ’ERROR GENERAL: ’+str(r.status_code)
else: #Se procesa la respuesta
print ’Código de estado HTTP: ’+str(r.status_code)
if (r.text).find("ERROR errNum:"):
print ’Error de Altiria: ’+r.text
else:
print ’Cuerpo de la respuesta: \n’+r.text

return r.text

except requests.ConnectTimeout:
print "Tiempo de conexión agotado"

except requests.ReadTimeout:
print "Tiempo de respuesta agotado"

except Exception as ex:

print "Error interno: "+str(ex)

print ’The function altiriaSms returns: \n’

+altiriaSms(’346xxxxxxxx,346yyyyyyyy’,’Mensaje de prueba’, ’’, True)
#No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
#Utilizar esta llamada solo si se cuenta con un remitente autorizado por Altiria
#print ’The function altiriaSms returns: \n’
# +altiriaSms(’346xxxxxxxx,346yyyyyyyy’,’Mensaje de prueba’, ’remitente’, True)

2.10.14. Envı́o y firma de documento PDF en Python

Ejemplo en Python utilizando la librerı́a Requests como cliente HTTP (ver [REQUESTS]).

# -*- coding: utf-8 -*-

import requests
import json

def altiriaCert(destination, fType):

print ’Enter altiriaCert: destination= ’+destination+’, fType= ’+fType

try:
# Se crea la lista de parámetros a enviar en la petición POST
# YY y ZZ se corresponden con los valores de identificación
# del usuario en el sistema.

61
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

payload = [
(’cmd’, ’certpdffile’),
(’apikey’, ’YY’),
(’apisecret’, ’ZZ’),
(’destination’, destination),
(’type’, fType),
(’webSig’, ’true’)
]

#Se fija la codificacion de caracteres de la peticion POST

contentType = {’Content-Type’:’application/x-www-form-urlencoded;charset=utf-8’}

#Se fija la URL sobre la que enviar la petición POST

url = ’https://www.altiria.net:8443/api/http’

#Se envı́a la petición y se recupera la respuesta

r = requests.post(url,
data=payload,
headers=contentType,
#Se fija el tiempo máximo de espera para conectar con el servidor (5 segundos)
#Se fija el tiempo máximo de espera de la respuesta del servidor (60 segundos)
timeout=(5, 60)) #timeout(timeout_connect, timeout_read)

if str(r.status_code) != ’200’: #Error en la respuesta del servidor

print ’Error general comando certPdfFile: ’+str(r.status_code)
else: #Se procesa la respuesta
print ’Codigo de estado HTTP cmd: ’+str(r.status_code)
print ’Respuesta certPdfFile: ’+str(r.text)
parsed_json = json.loads(r.text)
status = parsed_json[’status’]
if status == ’000’:
print ’Codigo de estado Altiria cmd: ’+status
url = parsed_json[’url’]
f = open("file.pdf", "rb")
try:
contentType = {’Content-Type’:’application/pdf’}
r = requests.post(url,
data=f,
headers=contentType,
# Se fija el tiempo máximo de espera para conectar
# con el servidor (5 segundos)
# Se fija el tiempo máximo de espera de la respuesta
# del servidor (60 segundos)
timeout=(5, 60)) #timeout(timeout_connect, timeout_read)
finally:
f.close()
if str(r.status_code) != ’200’: #Error en la respuesta del servidor
print ’Error general subiendo fichero: ’+str(r.status_code)
else: #Se procesa la respuesta
print ’Codigo de estado HTTP subiendo fichero: ’+str(r.status_code)
print ’Respuesta subiendo fichero: ’+str(r.text)
parsed_json = json.loads(r.text)
status = parsed_json[’status’]
if status == ’000’:
print ’Proceso terminado con exito’

62
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

else:
print "Error Altiria. Codigo de estado: "+status
else:
print "Error Altiria. Codigo de estado: "+status

except requests.ConnectTimeout:
print "Tiempo de conexión agotado"

except requests.ReadTimeout:
print "Tiempo de respuesta agotado"

except Exception as ex:

print "Error interno: "+str(ex)

altiriaCert(’346xxxxxxxx’,’simple’)

2.10.15. Envı́o de un mensaje en node.js

Ejemplo usando npm

Consultar la sección 2.10.1.

Ejemplo usando el objeto http

var querystring = require(’querystring’);

var https = require(’https’);

function sendSMS(apikey, apisecret, tel, sender, text) {

// Se contruye la cadena del post desde un objeto

var post_data = querystring.stringify({
’cmd’ : ’sendsms’,
’apikey’: apikey,
’apisecret’: apisecret,
’dest’ : tel,
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
’senderId’ : sender,
’msg’ : text
});

// Un objeto de opciones sobre donde se envia el post

var post_options = {
host: ’www.altiria.net’,
port: ’8443’,
path: ’/api/http’,
method: ’POST’,
headers: {
’Content-Type’: ’application/x-www-form-urlencoded’,
’Content-Length’: Buffer.byteLength(post_data)
}
};

// Se efectua la petición
var post_req = https.request(post_options, function(res) {

63
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

res.setEncoding(’utf8’);
res.on(’data’, function (chunk) {
//Es necesario procesar la respuesta y los posibles errores
console.log(’Response: ’ + chunk);
});
});

// post the data

post_req.write(post_data);
post_req.end();

// YY y ZZ se corresponden con los valores de identificacion del

// usuario en el sistema.
sendSMS(’YY’,’ZZ’,’346xxxxxxxx,346yyyyyyyy’,’’,’Mensaje de prueba’);
//No es posible utilizar el remitente en América pero sı́ en Espa~
na y Europa
//Utilizar esta llamada solo si se cuenta con un remitente autorizado por Altiria
//sendSMS(’YY’,’ZZ’,’346xxxxxxxx,346yyyyyyyy’,’remitente’,’Mensaje de prueba’);

2.10.16. Envı́o y firma de documento PDF en node.js

Ejemplo usando el objeto http.

const querystring = require(’querystring’);

const https = require(’https’);
const URL = require(’url’).URL;
const fs = require(’fs’);

function altiriaCert(apikey, apisecret, destination) {

// Se contruye la cadena del post desde un objeto

var post_data = querystring.stringify({
’cmd’ : ’certpdffile’,
’apikey’: apikey,
’apisecret’: apisecret,
’destination’ : destination,
’type’ : type,
’webSig’: ’true’
});

// Un objeto de opciones sobre donde se envia el post

var post_options = {
host: ’www.altiria.net’,
port: ’8443’,
path: ’/api/http’,
method: ’POST’,
headers: {
’Content-Type’: ’application/x-www-form-urlencoded’,
’Content-Length’: Buffer.byteLength(post_data)
}
};

// Se efectua la petición

64
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

var post_req = https.request(post_options, function(res) {

res.setEncoding(’utf8’);
res.on(’data’, function (data) {
//Es necesario procesar la respuesta y los posibles errores
console.log(’Respuesta cmd: ’ + data);
var parsedJson = JSON.parse(data);
if(parsedJson.status!=’000’) {
console.log("Error de Altiria cmd:"+data);
}else{
console.log("Codigo de estado Alriria cmd: "+parsedJson.status);
var options = new URL(parsedJson.url);
const imageBuffer = fs.readFileSync(’file.pdf’);

// Un objeto de opciones sobre donde se envia el post

var post_options = {
host: options.hostname,
port: options.port,
path: options.pathname,
method: ’POST’,
headers: {
’Content-Type’: ’application/pdf’
}
};
var post_req = http.request(post_options, function(res) {
res.setEncoding(’utf8’);
res.on(’data’, function (data) {
console.log(’Respuesta subir fichero: ’ + data);
var parsedJson = JSON.parse(data);
if(parsedJson.status!=’000’) {
console.log("Error de Altiria al subir fichero:"+data);
}else{
console.log("Proceso terminado con exito");
}
}, function (error) {
console.log("Codigo de estado HTTP subiendo fichero: "+error)
});
});
post_req.write(imageBuffer);
post_req.end();
}
}, function (error) {
console.log("Codigo de estado HTTP cmd: "+error)
});
});
// post the data
post_req.write(post_data);
post_req.end();
}

// YY y ZZ se corresponden con los valores de identificacion del

// usuario en el sistema.
altiriaCert(’YY’,’ZZ’,’346xxxxxxxx’,’simple’);

65
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

Referencias

[ALTIRIA360] Plataforma Altiria360:

https://www.altiria.net/web
[LANDINGS] Páginas webs adaptadas a móvil:
https://www.altiria.com/sms-landing
[FAQ] Preguntas frecuentes de la pasarela de envı́o de SMS de Altiria:
http://www.altiria.com/preguntas-frecuentes-faq-pasarela-sms-api
[HTTPCLIENT] El proyecto HTTPCLIENT de Apache:
http://hc.apache.org/httpcomponents-client-ga/
[NUSOAP] Librerı́a NuSOAP en Sourceforge:
http://sourceforge.net/projects/nusoap/
[WSIMPORT] Herramienta para generación de WS en Java:
http://docs.oracle.com/javase/8/docs/technotes/tools/unix/wsimport.html
[PERL] Página oficial de descargas de perl:
https://www.perl.org/get.html
[CODIGOFUENTE] Enlace a la descarga del código fuente de los ejemplos:
https://static.altiria.com/especificaciones/altiria-push-ejemplos-codigo-fuente.zip
[REQUESTS] Página oficial de Requests:
http://docs.python-requests.org
[SAVON] Página oficial de Savon:
http://savonrb.com
[SUDS] API de Suds:
https://pypi.python.org/pypi/suds
[SOAPLite] API de SOAP::Lite:
http://search.cpan.org/ phred/SOAP-Lite-1.20/lib/SOAP/Lite.pm
[POINTS2MM] Conversión de puntos a milı́metros:
https://www.google.com/search?q=point+to+mm
[SMSPHPCLIENT] Enlace al repositorio GitHub de nuestro cliente PHP:
https://github.com/altiria/sms-php-client
[SMSJAVACLIENT] Enlace al repositorio GitHub de nuestro cliente Java:
https://github.com/altiria/sms-java-client

66
 Interfaz HTTP para envı́o de SMS, landings web y firma de documentos

[SMSPYTHONCLIENT] Enlace al repositorio GitHub de nuestro cliente Python:

https://github.com/altiria/sms-python-client
[SMSNODEJSCLIENT] Enlace al repositorio GitHub de nuestro cliente NodeJS:
https://github.com/altiria/sms-nodejs-client

67