API Envío de SMS / SMS MASIVO (7.0)

INTRODUCCION

API de integración de envío de mensajes SMS desde aplicaciones mediante peticiones https.

AUTENTICACIÓN

En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las Peticiones, por seguridad deben ralizarse en POST y con protocolo HTTPS Seguro.

Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.

Para generar el string codificado en Base64, simplemente genere el string UsuarioApi:APIToken y codifíquelo en base64 mediante cualquier función base64encode.

COMPATIBILIDAD Y VERSIONES

La versión 7 es compatible con versiones anteriores de la API a partir de la versión 3.3. y superiores cambiando el método de autenticación
Versión 1.0 – 1.5: Última actualización 2004. Se recomienda la actualización a versión 3.3 o superior. Versiones no soportadas actualmente. Contactar con soporte para ayuda a la migración.
Versión 2.0 – 2.3: última actualización 2009. Se recomienda actualización a versiones 3.3 o superior. Versiones no soportadas actualmente. Contactar con soporte para ayuda a la migración.
Versión 3.0 – 3.7: última actualización 2012. Versiones soportadas y compatibles con versiones superiores. Recomendado cambio a última versión. Migración directa (v5 compatible con estas versiones). Contactar con soporte para información sobre el cambio de versión.
Versión 4.0 a 4.4: Última actualización 2014. Versiones soportadas y compatibles 100% con versiones superiores. Recomendamos realizar un upgrade a versión 5 ya que dispone de más funciones y posibilidades. Las nuevas características se irán añadiendo a versión 5.
Versión 5.0: Lanzamiento y última actualización 2015. Versión compatible con versiones anteriores de la API a partir de la 3.3 (incluida).
Versión 5.1: Última actualización 2016. Versión compatible con versiones anteriores de la API a partir de la 3.3 (incluida). En esta revisión también se añaden algunas utilidades por petición mayoritaria de Clientes.
Versión 5.2 a 5.7: Última actualización 2017. Nuevas funcionalidades ya presentes en el panel como Fail2Voice, acortador de links, qrCode, landings, etc… Capacidad de cargar ficheros PDF y office para enviarlos en los SMS y SMS Certificado.
Versión 5.8: Última actualización 2018. Se añade la posibilidad de enviar variables por destinatario. Estas variables sirven para personalizar tanto el mensaje enviado como los links y Landing Pages.
Versión 6: Última revisión 2021. Nuevas funcionalidades.
Versión 7: Última revisión 2023. Autenticación mediante API User y API Token. Nuevas funcionalidades.

# A TENER EN CUENTA

Conexiones en vacío\: Es importante tener en cuenta que una conexión errónea de forma repetida será tratada por el sistema como spam y podrá llegar a bloquear temporalmente la conexión. Es conveniente evitar realizar repetidas conexiones con datos erróneos o conexiones rápidas ‘en vacío’ (sin realizar envíos) con los mismos datos para obtener el número de créditos o el mismo report.

Para obtener reports de forma óptima en tiempo real se recomienda configurar la API en el panel para recibirlos en un script de su web.
Respuesta de las peticiones: La mayoría de las funciones disponen de un parámetro denominado ‘Resp’. Este parámetro define el formato de la respuesta que se devolverá. Puede ser TXT, JSON, XML o no definido. Se recomienda siempre definir este parámetro ya que todas las funciones, por compatibilidad con versiones anteriores de la API, responden por defecto (si no se define este parámetro) tal y como lo hacían en versiones antiguas. En estos resultados de versiones de API anteriores se obvian algunas de las variables que se incluyen en esta versión de la API y que consideramos importantes para facilitar la integración e información de la cuenta. En los ejemplos incluidos siempre se tiene en cuenta que ha definido el parámetro. Si está trabajando directamente con la API versión >= 5, asumiremos que ha definido el parámetro en todas las peticiones.

Funcionamiento recomendado El funcionamiento recomendado, por ser el más sencillo y, a la vez, el más profesional es el siguiente
- PROCESO 1: Envío de SMS, Descrito la función EnviarSMS de este documento y en el siguiente gráfico en el recuadro sombreado en azul.
- PROCESO 2: Recepción automática de reports en su web (proceso descrito en el la sección 'Recepción de reports de entrega' y en el siguiente gráfico dentro del recuadro sombreado en verde.

Enviar SMS y SMS Masivo

/EnviarSMS

Función de envío de mensajes SMS desde aplicaciones. Definición de parámetros necesarios y opcionales.

ATENCIÓN: Chequee la sección de recepción de reports en tiempo real si desea recibir el estado de los mensajes enviados en tiempo real en un script de su web.

query Parameters
Remitente
required
string
Example: Remitente=MIEMPRESA

Es el teléfono, nombre de la empresa o persona que envía. Si se deja en blanco se enviará como remitente el teléfono móvil o remitente por defecto registrado por el usuario que envía el mensaje. ATENCIÓN Si es alfanumérico el Máximo es de 11 caracteres.

Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Movil":"34600000000","Variable_1":"Pedro"},{"Movil":"34600000001","Variable_1":"Ana"}]

Array JSON con los destinatario del sms. Puede añadir variables si desea personalizar el Mensaje por destinatario. Por ejemplo:


   [
    {
      "Movil": "34600000001",
      "Variable_1": "la Variable 1 (hasta variable_10) para cada destinatario "
    },
    {
      "Movil": "34600000002",
      "Variable_1": "Variable_1 para personalizar el mensaje del segundo destinatario. Sólo es obligatorio en el array el Móvil y, si se usan variables, desde Variable_1 a Variable_10"
    }
   ]
  

Mensaje
required
string
Example: Mensaje=A la atención de Ana, te recordamos tu cita en la Clínica Ejemplo el próximo martes 23, pulse en el siguiente link para confirmar o cancelar la cita. (SMSLAND:2:idLanding)

Mensaje que se enviará al/ a los destinatarios. Puede incluir Ficheros, Links acortados, link de baja, imágenes, QRCODE, Landings etc... Para incluir adjuntos/ficheros o cualquiera de estos elementos revise la documentación en el Apéndice 1. En el Apéndice 1 verá cómo incorporar Landings, encuestas, qrcode, imágenes, etc...

Fecha
string
Example: Fecha=2022-10-01 15:10

Fecha en la que queda programado el envío, el mensaje se enviará en esa fecha. Por defecto vacío que significa enviar inmediatamente. Formato Año-Mes-dia hora:minuto. La referencia horaria es CET/CEST (Zona horaria de España).

Referenciausuario
string
Example: Referenciausuario=Tu referencia

Parámetro que se utiliza como referencia para el usuario. Si se selecciona recibir el report en una URL, recibirá este parámetro en el resultado del envío.

Report
integer
Example: Report=0

Si desea recibir reports por correo electrónico o en un script de su web (activando en panel de usuario la configuración API).

Idmensaje
integer
Example: Idmensaje=1765987

Parámetro opcional. Se utiliza para unificar envíos dentro de un mismo código de mensaje (idMensaje). De esta forma, podrá consultar en los paneles las estadísticas de entrega de varios mensajes agrupados. Este parámetro se corresponde con el Msgid/idMensaje obtenido en una petición anterior. Si utiliza este parámetro, el remitente se forzará al del primer mensaje enviado (el que devolvió el Msgid/idMensaje). Adicionalmente no se permitirá enviar al mismo móvil dos mensajes con el mismo código idMensaje.

Fail2voice
integer
Example: Fail2voice=0

El servicio de Fail2Voice permite convertir el mensaje en voz y entregarlo como llamada en los casos en los que no sea posible la entrega del SMS al destinatario (por ejemplo, el destinatario es un número fijo).
0 - 'No utilizar el servicio'
1 - Utilizar Fallo a Voz

Lenguajevoz
string
Example: Lenguajevoz=0

(Sólo si Fail2Voice=1) Lenguaje en el que se traducirá el mensaje de texto a voz. El listado de lenguajes posibles está definido en el API de envío de mensajes de Voz (por ejemplo es-ES para español.

Remitentevoz
integer
Example: Remitentevoz=0

(Sólo si Fail2Voice=1) Es el teléfono llamante. El remitente de la llamada. Debe tener formato internacional y estar validado en los paneles de Mensatek. La validación es un proceso sencillo que realizará en unos segundos y no supone ningún coste para su línea móvil o fija. Es simplemente una cuestión de seguridad.

Unicode
integer
Example: Unicode=0

Activar Unicode para poder eniar cualquier caracter fuera del estándar GSM.
0 - Enviar en estándar GSM 3.38 - Por defecto- (ver listado de caracteres en el apéndice 1)
1 - Enviar en Unicode (admite cualquier carácter)

Fixutf8
integer
Example: Fixutf8=0

En ocasiones, cuando los desarrolladores utilizan una codificación que no es UTF8, los caracteres especiales pueden interpretarse de forma errónea . Si esto sucede, active (poner a 1) este parámetro para solucionarlo.
0 - 'Estoy enviando en UTF8, no hace falta arreglar la codificación'
1 - arreglar caracteres especiales

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de mensajes enviados.
-1 Error de autenticación.
-2 No hay créditos suficientes.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.

Error
string

En caso de Res -3 , obtendrá un error descriptivo del problema en este parámetro.

Destinatarios
Array of arrays

Número de destinatarios. Sólo se obtiene si se especifica el parámetro ‘Resp’ (tipo de respuesta) y el resultado es positivo (se envían mensajes)

Msgid
integer

(Por compatibilidad con versiones anteriores, duplicado de idMensaje). Identificador del mensaje o grupo de mensajes enviados. Sirve, por ejemplo, como identificación para obtener el report del mensaje enviado (si el teléfono ha sido dado de baja, tiempos de entrega, etc…). Se recibirá en las peticiones si activa la recepción de reports en tiempo real en un script de su web/servidor.

idMensaje
integer

Identificador del mensaje o grupo de mensajes enviados. Sirve, por ejemplo, como identificación para obtener el report del mensaje enviado (si el teléfono ha sido dado de baja, tiempos de entrega, etc…). Se recibirá en las peticiones si activa la recepción de reports en tiempo real en un script de su web/servidor.

Cred
double

Créditos que restan en la cuenta de usuario tras el envío.

Mensajes
integer

Número de mensajes SMS enviados. Sólo se obtiene si se especifica el parámetro ‘Resp’ (tipo de respuesta) y el resultado es positivo (se envían mensajes)

NoEnviados
integer

Número de mensajes no enviados. Normalmente por estar el destinatario repetido o porque el móvil no es correcto. Sólo se obtiene si se especifica el parámetro ‘Resp’ (tipo de respuesta) y el resultado es positivo (se envían mensajes)

CreditosUsados
integer

Número de créditos utilizados en el envío. Sólo se obtiene si se especifica el parámetro ‘Resp’ (tipo de respuesta) y el resultado es positivo (se envían mensajes).

CreditosNecesarios
integer

Número de créditos necesarios para enviar el mensaje. Sólo si no puede enviarse el mensaje por falta de créditos.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/EnviarSMS' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Remitente="MIEMPRESA"' \ 
--form 'Destinatarios="[{\"Movil\":\"34600000000\",\"Variable_1\":\"Pedro\"},{\"Movil\":\"34600000001\",\"Variable_1\":\"Ana\"}]"' \ 
--form 'Mensaje="A la atención de Ana, te recordamos tu cita en la Clínica Ejemplo el próximo martes 23, pulse en el siguiente link para confirmar o cancelar la cita. (SMSLAND:2:idLanding)"' \ 

Response samples

Content type
[
  • {
    }
]

Recepción de reports de entrega y cambios de estado de mensajes enviados

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

RECEPCIÓN EN TIEMPO REAL DE LOS ESTADOS DE ENTREGA EN UN SCRIPT DE SU SERVIDOR. Activando la opción de recibir los reports en tiempo real en un script en su servidor desde su panel de usuario, recibirá una petición POST con el formato indicado cada vez que cada mensaje enviado cambie de estado. Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA

Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de report que está recibiendo (el objetivo es distinguir entre los reports de los diferentes servicios). Los servicios a los que se refiere esta especificación recibirá SMSMASIVO

Resultado
required
integer

Estado del mensaje enviado indicado por la operadora destino. Los estados posibles son:

ESTADO DESCRIPCION SIGNIFICADO
`0` Esperando entrega Significado: La operadora está esperando la recepción de la confirmación de entrega por parte del móvil. Si este estado permanece durante más de 5-10 segundos, normalmente indica que el teléfono destino se encuentra apagado o fuera de cobertura. La operadora intentará la entrega en cuanto el móvil vuelva a estar operativo.
`1` Programado Significado: El mensaje se encuentra programado. Se enviará en el momento en que se indica en la sección [Fecha]
`2` Esperando entrega Significado: La operadora está esperando la recepción de la confirmación de entrega por parte del móvil. Si este estado permanece durante más de 5-10 segundos, normalmente indica que el teléfono destino se encuentra apagado o fuera de cobertura. La operadora intentará la entrega en cuanto el móvil vuelva a estar operativo.
`10` Esperando entrega Significado: La operadora está esperando la recepción de la confirmación de entrega por parte del móvil. Si este estado permanece durante más de 5-10 segundos, normalmente indica que el teléfono destino se encuentra apagado o fuera de cobertura. La operadora intentará la entrega en cuanto el móvil vuelva a estar operativo.
`13` Entregado al teléfono Significado: El mensaje ha sido entregado al teléfono destino. En caso de que el servicio sea un SMS Certificado el sistema está certificando la entrega y contenido. Puede verificar el tiempo de entrega en segundos y la Fecha hora a la que se entregó. Si el tiempo de entrega supera los 5-10 segundos, probablemente el teléfono estaba apagado o fuera de cobertura.
`14` SMS Certificado Entregado y Certificado Significado: El SMS Certificado ha sido entregado y Certificado. Dispone de un certificado en formato PDF con sellado de Tiempo.
`15` Esperando respuesta en SMS Contrato mediante respuesta SI/Acepto Significado: En un SMS Contrato una de las opciones de contratación es la respuesta SI/Acepto al SMS Certificado cerrándose un contrato, el sistema ha entregado el SMS Certificado y está esperando respuesta del receptor.
`16` Respuesta recibida. Certificando Significado: Se ha recibido la respuesta al SMS Certificado cerrando un SMS Contrato. Se está certificando el resultado.
`17` SMS Contrato mediante respuesta certificado Significado: Se ha recibido la respuesta y el contrato está a disposición para descarga.
`50` La Red responde que el teléfono no existe Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no existe o ha sido dado de baja. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`51` Falló la entrega al teléfono Significado: Ha habido un fallo repetido en la entrega a este teléfono. Como medida de calidad, en MENSATEK en exclusiva, reintentamos varias veces las entregas sin coste adicional para Ud. en este caso para evitar problemas temporales del teléfono. Con toda probabilidad este teléfono ya no existe.
`52` Falló la entrega a la red Significado: Error de la operadora que da servicio al móvil, Contacte con Soporte para chequearlo.
`53` El mensaje ha expirado. (El teléfono sigue no operativo) Significado: El móvil ha estado apagado durante un periodo prolongado (16-72 horas en función de operadora). Como medida de Calidad en exclusiva en MENSATEK, reintentamos la entrega varios periodos sin coste para Ud., si tras indicarnos la operadora repetidamente que el teléfono sigue apagado, aparece este mensaje. El dato de Fecha es el último intento de entrega.
`54` Número en Lista Negra Significado: El número se encuentra en la lista negra de la operadora o de su cuenta.
`55` Número Bloqueado Significado: El número está bloqueado.
`70` Entregado al teléfono. Tiempo de entrega no disponible Significado: El mensaje ha sido entregado por la operadora que da servicio al móvil pero no existe un dato concreto del momento de entrega por un fallo en comunicación móvil->Operadora.
`101` El mensaje ha expirado. (El teléfono sigue no operativo) Significado: El móvil ha estado apagado durante un periodo prolongado (16-72 horas en función de operadora). Como medida de Calidad en exclusiva en MENSATEK, reintentamos la entrega varios periodos sin coste para Ud., si tras indicarnos la operadora repetidamente que el teléfono sigue apagado, aparece este mensaje. El dato de Fecha es el último intento de entrega.
`102` Usuario dado de baja Significado: El usuario está dado de baja.
`103` El mensaje ha expirado. (El teléfono sigue no operativo) Significado: El móvil ha estado apagado durante un periodo prolongado (16-72 horas en función de operadora). Como medida de Calidad en exclusiva en MENSATEK, reintentamos la entrega varios periodos sin coste para Ud., si tras indicarnos la operadora repetidamente que el teléfono sigue apagado, aparece este mensaje. El dato de Fecha es el último intento de entrega.
`104` El teléfono no es correcto Significado: El número no es correcto, chequee el número y corríjalo.
`106` Entregado al teléfono. Tiempo de entrega no disponible Significado: El mensaje ha sido entregado por la operadora que da servicio al móvil pero no existe un dato concreto del momento de entrega por un fallo en comunicación móvil->Operadora.
`110` El teléfono no existe Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no existe o ha sido dado de baja. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`111` Teléfono dado de baja Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no existe o ha sido dado de baja. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`112` Teléfono sin servicio Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no tiene servicio. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`113` El mensaje ha expirado. (El teléfono sigue no operativo) Significado: El móvil ha estado apagado durante un periodo prolongado (16-72 horas en función de operadora). Como medida de Calidad en exclusiva en MENSATEK, reintentamos la entrega varios periodos sin coste para Ud., si tras indicarnos la operadora repetidamente que el teléfono sigue apagado, aparece este mensaje. El dato de Fecha es el último intento de entrega.
`120` Fallo en el SMSC destino Significado: El SMSC de la operadora destino ha dado un error grave. Probablemente se trata de una incidencia grave en la operadora, el mensaje se retiene para asegurar entregas.
`121` Congestión en el SMSC destino Significado: La operadora destino está congestionada. Mensatek (servicio exclusivo) está reintentando la entrega por canales prioritarios (este error es temporal y debe ser subsanado rápidamente). 
`122` Fallo en el SMSC destino Significado: El SMSC de la operadora destino ha dado un error grave. Probablemente se trata de una incidencia grave en la operadora, el mensaje se retiene para asegurar entregas.
`130` Error en el Teléfono destino Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no existe o ha sido dado de baja. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`131` El Móvil ha excedido la capacidad de memoria (no cabe el mensaje) Significado: Ha habido un fallo repetido en la entrega a este teléfono. Como medida de calidad, en MENSATEK en exclusiva, reintentamos varias veces las entregas sin coste adicional para Ud. en este caso para evitar problemas temporales del teléfono. 
`132` El Móvil no puede recibir mensajes Significado: Ha habido un fallo repetido en la entrega a este teléfono. Como medida de calidad, en MENSATEK en exclusiva, reintentamos varias veces las entregas sin coste adicional para Ud. en este caso para evitar problemas temporales del teléfono. Si este error se mantiene, con toda probabilidad este teléfono ya no existe.
`133` Fallo en móvil destino (dado de baja). Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no existe o ha sido dado de baja. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`134` Problema en el móvil destino.Reintentando... Significado: El móvil no ha podido recibir el mensaje. La operadora nos ha indicado un error temporal del terminal. Como medida de Calidad exclusiva de Mensatek, reintentaremos varias veces la entrega en intervalos de 15 minutos. Sólo daremos el mensaje como fallido si finalmente todos los intentos de entrega son erróneos, en cuyo caso le indicaremos el motivo (normalmente móvil con problemas de cobertura o dándose de baja).
`135` Problema en la red destino.Reintentando... Significado: El móvil no ha podido recibir el mensaje. La operadora nos ha indicado un error. Como medida de Calidad exclusiva de Mensatek, reintentaremos varias veces la entrega en intervalos de 15 minutos. Sólo daremos el mensaje como fallido si finalmente todos los intentos de entrega son erróneos, en cuyo caso le indicaremos el motivo (normalmente móvil con problemas o dado de baja).
`136` Teléfono sin servicio Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no tiene servicio o ha sido dado de baja recientemente. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`137` Teléfono dado de baja Significado: La operadora que daba servicio al móvil nos ha indicado que el teléfono ya no existe o ha sido dado de baja. Es conveniente que contacte con el destinatario para obtener su nuevo número móvil.
`140` Error de destino, contacte con soporte Significado: Contacte con soporte. Hay un problema en el envío de sus mensajes a la operadora/país destino.
`141` Error de destino, contacte con soporte Significado: Contacte con soporte. Hay un problema en el envío de sus mensajes a la operadora/país destino.
`150` La red de destino ha cerrado temporalmente la entrega de mensajes Significado: Contacte con soporte. Hay un problema en el envío de sus mensajes a la operadora/país destino.
`160` SMS Contrato. El usuario ha accedido al Contrato/PDF Significado: En un SMS Contrato en el que se adjunta un PDF para firma, este estado indica que el destinatario ha accedido al documento. Se envía ‘Variables’ como string JSON.
`161` SMS Contrato. Contrato Leído Significado: El destinatario ha leído el documento (ha visto hasta el final del mismo).
`162` SMS Contrato. Contrato Aceptado Significado: El destinatario/firmante ha aceptado el contrato.
`163` SMS Contrato. Contrato firmado Significado: El destinatario ha firmado el contrato.
`180` SMS Contrato. Estado Final. Contrato Aceptado por aceptación básica Significado: El destinatario ha finalizado la firma mediante aceptación explícita del contrato. El contrato está disponible para descarga. Se envía ‘Variables’ como string JSON.
`181` SMS Contrato. Estado Final. Contrato Aceptado y firmado con firma biométrica Significado: El destinatario ha aceptado el contrato y lo ha firmado con firma biométrica. El contrato certificado está disponible para descarga. Se envía ‘Variables’ como string JSON.
`190` SMS Contrato. Contrato rechazado Significado: El destinatario ha rechazado el contrato. Se envía ‘Variables’ como string JSON.
`195` SMS Contrato. Contrato expirado Significado: El contrato ha expirado sin finalizar la firma. Se envía ‘Variables’ como string JSON.
`1000` Esperando entrega Significado: La operadora está esperando la recepción de la confirmación de entrega por parte del móvil. Si este estado permanece durante más de 5-10 segundos, normalmente indica que el teléfono destino se encuentra apagado o fuera de cobertura. La operadora intentará la entrega en cuanto el móvil vuelva a estar operativo.
`1001` Programado Significado: El mensaje se encuentra programado. Se enviará en el momento en que se indica en la seccón [Fecha]
`1002` Enviando Significado: Entregando a operadora destino/Esperando a que la operadora destino confirme la recepción del mensaje para proceder a entregarlo al móvil.
`1003` Problema en el móvil destino. Reintentando... Significado: Ha habido un fallo repetido en la entrega a este teléfono. Como medida de calidad, en MENSATEK en exclusiva, reintentamos varias veces las entregas sin coste adicional para Ud. en este caso para evitar problemas temporales del teléfono. Con toda probabilidad este teléfono ya no existe.
`5000` SMS Contrato. Localización GPS del firmante. Significado: Se envía únicamente en caso de que el firmante acepte la localización GPS.
Remitente
required
string

Remitente utilizado en el envío.

Movil
required
string

Correo del destinatario al que se refiere el report.

Fecha
required
string

Fecha del report (fecha en la que la operadora que da servicio al móvil destino comunica el nuevo estado)

Segundos
required
string

Tiempo transcurrido hasta el cambio de estado (normalmente tiempo de entrega al móvil)

idMensaje
required
integer

Identificador único recibido como respuesta en la función de envío (idMensaje recibido en la función de envío)

Referencia
required
string

Referencia del usuario que se envió durante la petición de envío.

idReport
integer

Identificador único del mensaje.

Request samples

Content type
{
  • "Servicio": "SMSMASIVO",
  • "Resultado": 11,
  • "Remitente": "TUEMPRESA",
  • "Movil": "destino@dominio.com",
  • "Fecha": "2020-12-03 11:14:24",
  • "Segundos": 3,
  • "idMensaje": 10573758,
  • "Referencia": "Su referencia si la indicó",
  • "idReport": 1234567890
}

Recepción de respuestas a SMS si dispone de número exclusivo

https://{SuDominio}//path/de/su/script/de/recepción/de/sms

RECEPCIÓN DE LOS MENSAJES SMS RECIBIDOS EN SU NÚMERO CONTRATADO La configuración de la dirección del script (endpoint) donde desea recibir una petición por cada mensaje recibido en su número se realiza desde el panel de usuario. La contratación de los números de recepción de mensajes SMS se realizan a través de su comercial y requieren una verificación de identidad. Puede contratar el número de teléfonos que desee. Para conocer la cobertura y posibilidad de recepción internacional, consulte con su comercial. En el envío de SMS Contrato no es necesario contratar un número, el sistema se encargará de asignar uno genérico del pool de números de operadoras. Para recibir mensajes como respuesta a SMS normales sí es necesaria la contratación de un número. Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORMULARIO

Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de servicio del que se está recibiendo la petición. En este caso siempre es SMSRECIBIDO independientemente de si es respuesta a un SMS, SMS Certificado, SMS Contrato o es un mensaje originado en el cliente.

timestamp
required
integer

TimeStamp Unix del momento en el que se recibe el mensaje SMS en el número.

Fecha
required
string

Fecha de recepción enviada por la operadora).

Movil
required
string

Número de móvil que recibe el mensaje.

Remitente
required
string

Remitente del mensaje, normalmente móvil que envía el mensaje.

Mensaje
required
string

Mensaje recibido

idR
required
integer

identificación del mensaje original si éste es respuesta a uno enviado (identificación interna)

idM
required
integer

Identificación del mensaje origial si éste es respuesta a uno enviado previamente. El idM coincide con el idMensaje devuelto en la función de envío.

EsCert
required
boolean

En caso de ser respuesta a un mensaje enviado anteriormente, indica si el mensaje original era certificado (sería un SMS Contrato) o no.

Referencia
string

En caso de que este mensaje sea respuesta de uno previamente enviado, aquí se recibirá la referencia de usuario del mensaje enviado mediante la función de envío

Request samples

Content type
{
  • "Servicio": "SMSRECIBIDO",
  • "timestamp": 1664795529,
  • "Fecha": "2020-12-03 11:14:24",
  • "Movil": 34600000000,
  • "Remitente": "MIEMPRESA",
  • "Mensaje": "MIEMPRESA",
  • "idR": 56399876,
  • "idM": 78334454,
  • "EsCert": true,
  • "Referencia": "667887TR"
}

Cancelar SMS Programado

/CancelarSMS

Función para cancelar un SMS programado previamente mediante la función de envío.

query Parameters
Idmensaje
required
integer
Example: Idmensaje=1283876988

Identificador devuelto en la función de envío.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de destinatarios cancelados.
-1 Error de autenticación.
-2 Datos incorrectos (Sólo puede cancelar identificadores suyos, si intenta cancelar identificadores de mensaje de otro usuario, se podría considerar ataque y limitar el acceso de su conexión).
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-4 El mensaje ya está enviado/no se puede cancelar.
-5 El mensaje ya está cancelado/no se puede cancelar.

IDMENSAJE
integer

Número del identificador del mensaje efectivamente cancelado.

CRED
required
double

Créditos que restan en la cuenta de usuario tras la cancelación.

CREDR
double

Créditos recuperados en la cancelación.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/CancelarSMS' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Idmensaje="1283876988"' \ 

Response samples

Content type
[
  • {
    }
]

Reprogramar SMS Programado

/ReprogramarSMS

Función para reprogramar un SMS previamente programado mediante la función de envío para ser procesado en el futuro..

query Parameters
Idmensaje
required
integer
Example: Idmensaje=1283876988

Identificador devuelto en la función de envío.

Fecha
required
string
Example: Fecha=2022-12-03 11:15

Nueva fecha de envío. Es la fecha en la que quedará programado el mensaje para su envío. Debe ser posterior a la fecha/hora actual. El formato debe ser AAAA-MM-DD HH:mm

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de mensajes reprogramados.
-1 Error de autenticación.
-2 Datos incorrectos (Sólo puede modificar mensajes programados con identificadores enviados desde su cuenta, si intenta modificar identificadores de mensaje de otro usuario, se podría considerar ataque y limitar el acceso de su conexión).
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-4 El mensaje ya está enviado/no se puede reprogramar.
-5 El mensaje está cancelado/no se puede reprogramar.
-6 La nueva fecha no es correcta.
-7 La nueva fecha ya ha pasado.

Cred
required
double

Créditos que restan en la cuenta de usuario.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/ReprogramarSMS' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Idmensaje="1283876988"' \ 
--form 'Fecha="2022-12-03 11:15"' \ 

Response samples

Content type
[
  • {
    }
]

Consulta Simple de Report de SMS

/GetReportSMS

Obtención del report / estado de un SMS identificado por el idMensaje (identificador de mensaje) obtenido en la función de envío. Se recomienda utilizar la recepción de reports en su web ya que recibirá los cambios de estado de los mensajes enviados en tiempo real. Al poder enviar a más de un destinatario el resultado se recibe como un array de resultados en función de la respuesta elegida.

query Parameters
Idmensaje
integer
Example: Idmensaje=1283876988

Identificador devuelto en la función de envío.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
1 Operación correcta.
-1 Error de autenticación.
-2 No tiene permiso para consultar este mensaje.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-4 Error en respuesta/No tiene permiso para consultar este mensaje.

Destinatarios
required
integer

Número de destinatarios en el mensaje.

Cred
double

Créditos que restan en la cuenta de usuario.

Informe
required
Array of arrays

Array por destinatario con los datos del mensaje. Se recibirán los siguientes parámetros:
Fecha Fecha del report
Tiempo : Tiempo de entrega a destinatario
Telefono : Teléfono al que se refiere el report
Resultado : Resultado numérico (ver estados en el callback de recepción de reports)
Estado : Texto del Resultado

Ejemplo: [{'Fecha':'2021-09-04 19:37:21','Tiempo':3,'Telefono':'34601234567','Resultado':11,'Estado':'Entregado al Teléfono'},{'Fecha':'2021-09-04 19:37:27','Tiempo':3,'Telefono':'34656789012','Resultado':11,'Estado':'Entregado al Teléfono'}]

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/GetReportSMS' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 

Response samples

Content type
[
  • {
    }
]

Cargar un fichero a la biblioteca

/CargarFichero

Función para la carga en la Biblioteca de ficheros del usuario para poder ser adjuntados en un envío posterior de SMS . ATENCIÓN Hay un límite de número de ficheros y de espacio ocupado por Cliente. Puede contactar con Soporte para ampliarlo. En cualquier caso es buena práctica borrar el fichero una vez no se necesite.

query Parameters
Nombre
any
Example: Nombre=mifichero.pdf

Obligatorio sólo en caso de Tipo=BASE64. Nombre, incluida la extensión, con que quedará renombrado el fichero una vez cargado. Los nombres deben incluir la extensión y tener un máximo de 15 caracteres (sólo letras y números).

Tipo
required
any
Example: Tipo=mifichero.pdf

Cómo se env´a el fichero. Los valores posibles son FILES o BASE64.
FILES (Recomendado), se asume que el fichero se envía como un POST normal xwww-form-urlencoded
BASE64 Espera recibir el contenido del fichero en la variable Contenido codificado en Base64.

Contenido
any
Example: Contenido=JVBERi000000.............

Contenido del fichero en Base64 si el Tipo es BASE64.

Autoborrado
any
Example: Autoborrado=Si

(Sólo útil para SMS Certificado y SMS Contrato). La biblioteca de ficheros del usuario tiene un límite de almacenamiento y número de ficheros. Un Fichero sólo es necesario hasta que el mensaje se certifica. Una vez certificado el fichero se copia en una ubicación segura para su custodia por lo que es accesible por el destinatario sin necesidad de mantenerlo en la biblioteca de usuario. Si desea que el sistema, de forma automática, borre el fichero al certificar el mensaje, active esta opción. Hágalo sólo si el fichero se va a utilizar en un único SMS Certificado/Contrato.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada.

1 Correcto
-1 Error de autenticación.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-10 Ha excedido su capacidad de almacenamiento de ficheros, contacte con soporte para solicitar más espacio.
-11 Formato de fichero no admitido, se admiten PDF, Excel, Word y VCF. En caso de documentos, se recomienda PDF por máxima compatibilidad en los teléfonos.
-12 Ha indicado que enviaría un fichero en el modo BASE64 pero no ha enviado el contenido.
-13 Ha indicado que enviaría un fichero en el modo FILES y no ha llegado el contenido.
-15 Debe especificar Tipo FILES o BASE64.
-16 Fichero demasiado grande, consulte con soporte para ampliar límites.
-17 Ha ocurrido un error en la carga del fichero.
-18 Las cuentas de prueba no tienen capacidad de envío de ficheros, contacte con soporte.

Nombre
string

Se incluye el nuevo nombre del fichero. Sólo si Res=1.

Error
string

En caso de Res -3 , obtendrá un error descriptivo del problema en este parámetro.

Cred
double

Créditos que restan en la cuenta de usuario tras el envío.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/CargarFichero' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Tipo="mifichero.pdf"' \ 

Response samples

Content type
[
  • {
    }
]

Listar Ficheros en Biblioteca

/ListarFicheros

Función para litar los ficheros en la biblioteca del usuario. Devuelve un array/listado con los ficheros dentro de la cuenta de usuario.

query Parameters
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada.

1 Correcto
-1 Error de autenticación.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-10 Ha excedido su capacidad de almacenamiento de ficheros, contacte con soporte para solicitar más espacio.
-11 Formato de fichero no admitido, se admiten PDF, Excel, Word y VCF. En caso de documentos, se recomienda PDF por máxima compatibilidad en los teléfonos.
-12 Ha indicado que enviaría un fichero en el modo BASE64 pero no ha enviado el contenido.
-13 Ha indicado que enviaría un fichero en el modo FILES y no ha llegado el contenido.
-15 Debe especificar Tipo FILES o BASE64.
-16 Fichero demasiado grande, consulte con soporte para ampliar límites.
-17 Ha ocurrido un error en la carga del fichero.
-18 Las cuentas de prueba no tienen capacidad de envío de ficheros, contacte con soporte.

Error
string

En caso de Res -3 , obtendrá un error descriptivo del problema en este parámetro.

Ficheros
required
Array of arrays

Array con el listado de documentos. Se recibirán los siguientes parámetros:
Fecha Fecha de carga del fichero en la biblioteca
Nombre : Nombre del fichero
Ext : Extensión del fichero

Cred
double

Créditos que restan en la cuenta de usuario tras el envío.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/ListarFicheros' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 

Response samples

Content type
[
  • {
    }
]

Borrar un fichero de la Biblioteca

/BorrarFichero

Función para borrar un fichero de la Biblioteca del usuario. ATENCIÓN sólo debe borrar un fichero cuando el servicio ya haya terminado/se (no se vaya a acceder más al fichero). Hasta ese momento el fichero debe estar disponible en la biblioteca del usuario.

query Parameters
Nombre
required
any
Example: Nombre=mifichero.pdf

Nombre del fichero a borrar.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada.

1 Correcto
-1 Error de autenticación.
-2 El fichero no existe.

Error
string

En caso de Res -3 , obtendrá un error descriptivo del problema en este parámetro.

Cred
double

Créditos que restan en la cuenta de usuario tras el envío.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/BorrarFichero' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Nombre="mifichero.pdf"' \ 

Response samples

Content type
[
  • {
    }
]

Consulta de Créditos

/GetCreditos

Función que devuelve el número de créditos en la cuenta. Es una función de uso muy esporádico ya que la mayoría de las funciones devuelven en sus respuestas el número de Créditos restante en el usuario. Por tanto, se suele utilizar simplemente como prueba de funcionamiento o para obtener el número de créditos de forma ocasional

query Parameters
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
1 La función concluyó con éxito.
-1 Error de autenticación.

Cred
required
double

Créditos que restan en la cuenta de usuario tras el envío.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/GetCreditos' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 

Response samples

Content type
[
  • {
    }
]

Apéndice 2 - Sets de Caracteres

Puede utilizar alfabeto estándar GSM 3.38 (por defecto) o el set de caracteres Unicode enviando en la petición Unicode=1

Unicode

Admite cualquier caracter e, incluso, se pueden añadir emojis. Debe activar en la petición Unicode=1. Las operadoras cobran un SMS hasta 70 caracteres, si se superan los 70 caracteres, se cobra un SMS por cada 67 caracteres.

GSM 3.38

Los caracteres permitidos en el mensaje, si no se elige Unicode, son los incluidos en el estándar GSM 3.38 (alfabeto estándar de los SMS). Debe tener en cuenta que el € ocupa dos caracteres (se envía como combinación de dos) y que los acentos cerrados (tildes) no están en el estándar (excepto el de la é) por lo que, si se incluyen, se cambiarán por el carácter más similar.

Los caracteres admitidos en el estándar se incluyen en la tabla inferior, los de la tabla de extensión ( más a la derecha) ocupan dos caracteres y los de la primera (Básica a la izquierda) ocupan 1 carácter.

Para el remitente le aconsejamos:

1.- Sólo números (un móvil o fijo en formato internacional, p.e. +34600000000) hasta 15 dígitos

2.- Sólo letras, números, & y carácter subrayado hasta 11 caracteres. P.e. MiRemitente