Documentation de l’API SMS PRO

Probar la API

Si tienes una necesidad específica, ¡contáctanos!

Versiones

Num Modificaciones Fecha de aplicación
1.0.0 Versión inicial
1.1.0
  • Los mensajes comerciales deben incluir obligatoriamente la mención ‘STOP sms-s.top’.
  • Se añade el código de error 400 – Mención STOP faltante
 16/12/2021
1.1.1 11/07/2022

1. Introducción

La API HTTP es la forma más sencilla de integrar el servicio de comunicación SMS de TextingHouse.

Esta interfaz puede utilizarse tanto en HTTP POST como en HTTP GET.
Se recomienda usar POST cuando el volumen de datos sea importante, ya que GET tiene limitación de tamaño.

Las respuestas de TextingHouse son textos simples (content-type: text/plain; charset=utf-8), por ejemplo: ID del SMS, código de estado, crédito o errores. Se devuelven directamente en el cuerpo HTTP.

La comunicación con la API se realiza mediante HTTPS en el puerto 443.
Todas las solicitudes deben estar “URL-encoded”.

Nota: es importante leer toda la documentación antes de contactar soporte.

Todos los ejemplos usan HTTP GET.

2. Requisitos previos

Para utilizar la API de envío de SMS necesitas una cuenta activa con saldo positivo en TextingHouse.
Los identificadores se muestran como ‘XXXX’ en los ejemplos.

Para registrarte, haz clic aquí: Registro – API TextingHouse.

3. Ejemplos

A continuación se muestran ejemplos básicos de implementación para el envío de un SMS a través de la API de TextingHouse.

Los parámetros distinguen entre mayúsculas y minúsculas.

Ejemplo de comando GET básico
GET :

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXX&cmd=sendsms&to=999&txt=XXXXX&iscom=N
ID:5d726149a129c829e8c23f7b
Ejemplo de comando GET básico
axios :

const axios = require('axios');    

axios({
  method: 'post',
  url: 'https://api.textinghouse.com/http/v1/do',
  data: {
    user: 'XXXX',
    pass: 'XXXX',
    cmd: 'sendsms',
    to: '999',
    txt: 'Mon SMS de test',
    iscom: 'N'
  },
  responseType: 'text'
})
.then((res) => {
  console.log(res.data)
})
.catch((error) => {
  console.error(error)
});
Ejemplo PHP - cURL
cURL :

$data = array(
    'user' => 'XXXX',
    'pass' => 'XXXX',
    'cmd' => 'sendsms',
    'to' => '999',
    'txt' => 'Mon SMS de test',
    'iscom' => 'N'
);
$url = 'https://api.textinghouse.com/http/v1/do';
$ch = curl_init($url);
$postString = http_build_query($data, '', '&');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

4. Funcionamiento de la API

4.1 Autenticación

Tras crear tu cuenta sobre la API textingHouse, tus credenciales están disponibles en “Configuración”:

  • user: identificador API
  • pass: contraseña asociada

También se puede añadir una restricción por dirección IP desde la página “Configuración”, en la pestaña “Bloqueo por IP” de la interfaz, para permitir únicamente el envío desde una dirección IP específica. Esta opción es recomendada por motivos de seguridad.

4.2 Comandos

Los comandos se especifican mediante el parámetro «cmd». Los valores posibles son:

 

Valor cmd Parámetros Descripción
sendsms sí Enviar SMS
Ver sección “Envío de un mensaje”.
getstatus sí Permite obtener el estado de un mensaje a través de su ID.
Ver sección “Consulta de estado”.
getcredit no Permite consultar el saldo de la cuenta del cliente.
Ver sección “Consulta de crédito”.

4.3 Envío de un mensaje

El envío de un mensaje se realiza utilizando el comando «sendsms».

&cmd=sendsms

 

Los parámetros del comando «sendsms» son los siguientes:

 

Parámetro Obligatorio Descripción
to sí Número de teléfono del destinatario con el prefijo del código internacional del país. Ejemplo: 34 para España
txt sí Texto del mensaje.
El texto debe estar «URL encoded».
Ten en cuenta que algunos caracteres especiales pueden ser reemplazados según la red de destino del SMS.
Ver sección 5.3 Caracteres permitidos en SMS.
climsgid no ID del mensaje del cliente.
Definido por el cliente para realizar seguimiento.
Hasta 32 caracteres.
from no

Permite personalizar el remitente del SMS.

La personalización del nombre del remitente está limitada a un conjunto de nombres autorizados para tu cuenta. Las solicitudes se realizan desde la página “Configuración” de la interfaz API.

Limitado a 11 caracteres sin acentos (a-zA-Z0-9).

La personalización del remitente no está disponible en algunas destinos (limitaciones técnicas de ciertos operadores), por lo que TextingHouse se reserva el derecho de reemplazar el remitente elegido por el cliente en el momento del envío.
iscom sí

Indica si se trata de un mensaje de carácter comercial o no.

Valores posibles:

  • ‘Y’: Sí, es un mensaje de carácter comercial.
  • ‘N’: No, no es un mensaje de carácter comercial.

 

Los mensajes de carácter comercial deben enviarse obligatoriamente en días laborables y en horario diurno. Los horarios permitidos (según la hora local del destinatario) son los siguientes:

  • De lunes a viernes entre las 08:00 y las 20:00
  • Sábados entre las 10:00 y las 15:00

Los envíos comerciales los domingos y días festivos no están permitidos.

Los SMS de carácter comercial enviados fuera de los horarios autorizados serán retenidos y enviados en la siguiente franja laboral disponible, sin que el cliente pueda reclamar ni cancelar el envío.

Cada mensaje de carácter comercial debe incluir obligatoriamente:

  • la identidad del anunciante,
  • la mención ‘STOP sms-s.top’.

Ver detalle a continuación: SMS de carácter comercial / marketing

 

Ejemplo de envío del SMS con el mensaje «SMS de prueba con acentos vía TextingHouse» al número español 06 28 00 00 00, con el ID de cliente ES78913246:

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=sendsms&to=33628000000&txt=SMS%20accentu%C3%A9%20de%20test%20via%20TextingHouse&climsgid=FRS78913246&from=test&iscom=N

 

Respuesta :

ID:<api_id>

api_id es el identificador único proporcionado por TextingHouse.
Ejemplo

ID:5d726149a129c829e8c23f7b

Tras el envío, la API devuelve el ID del mensaje, lo que confirma que el mensaje ha sido correctamente procesado. Este ID será necesario para correlacionar los estados recibidos con los mensajes enviados.

 

O, en caso de error:

ERR: <code_erreur> | description erreur

Ejemplo:

ERR: 101 | Authentication failed

En caso de error, deben tenerse en cuenta los siguientes códigos:

Código de error Descripción
100 Parámetro faltante
101 Error de autenticación: nombre de usuario, contraseña o dirección IP inválidos
104 Crédito insuficiente
350 Stop flooding. Solo se permite un mensaje (mismo contenido y mismo número de teléfono) por destinatario cada 10 segundos. Si se supera este límite, la API devuelve este error.
400

Falta la mención STOP.

El mensaje es comercial pero no contiene la mención STOP sms-s.top.

 

SMS de carácter comercial / marketing

El parámetro “iscom” (obligatorio) del comando “sendsms” permite indicar si el SMS tiene carácter comercial (o de marketing) o si se trata de un mensaje de servicio.

 

Recordatorio de la normativa española aplicable a los SMS comerciales:

El envío de publicidad por SMS está permitido en España siempre que los destinatarios hayan dado previamente su consentimiento expreso para recibir comunicaciones comerciales al facilitar su número de teléfono móvil, de conformidad con el RGPD, la LSSI y las directrices de la AEPD.

Todo mensaje de carácter comercial debe obligatoriamente:

  • indicar claramente la identidad del anunciante o de la empresa remitente,
  • incluir un medio sencillo y gratuito para oponerse a futuras comunicaciones (mención STOP o mecanismo equivalente),
  • respetar horarios razonables de envío y la normativa vigente en materia de comunicaciones comerciales electrónicas.

 

STOP SMS

Todos los SMS comerciales (iscom=Y) deben incluir la mención STOP sms-s.top al final del texto del mensaje.

TextingHouse recopilará automáticamente las solicitudes STOP de sus destinatarios para permitirles darse de baja de sus comunicaciones.

Si un SMS comercial no incluye la mención STOP sms-s.top, será rechazado (error 400).

 

Restricciones horarias :

La normativa sobre prospección comercial por SMS establece que los mensajes comerciales solo pueden enviarse en días laborables y en horario diurno. Por ello, los horarios autorizados por TextingHouse son los siguientes:

  • de lunes a viernes entre las 08:00 y las 20:00
  • los sábados entre las 10:00 y las 15:00

Los envíos comerciales no están permitidos los domingos ni los días festivos.

Los SMS comerciales enviados fuera de los horarios autorizados serán retenidos y enviados automáticamente en el siguiente horario hábil, sin que el cliente pueda presentar reclamaciones ni solicitar cancelaciones.

 

Coste de los SMS

Cada SMS enviado a la API (excepto los SMS de prueba enviados al 999) se factura según la tarifa vigente en el momento del envío. Si el SMS supera los 160 caracteres, cada SMS adicional se facturará según la segmentación del mensaje (ver FAQ: Longitud de un SMS, ¿qué longitud de mensaje puedo enviar por SMS?).

4.4 Solicitud de estado

Recomendamos utilizar la devolución automática de estados mediante la URL de callback: ver Devolución de estados.

No obstante, también es posible solicitar el estado de un mensaje indicando su ID TextingHouse o su ID de cliente mediante el comando “getstatus”:

&cmd=getstatus

Los parámetros son los siguientes:

Parámetro Descripción
api_id ID TextingHouse devuelto por la API durante el envío
climsgid ID cliente proporcionado durante el envío

Si ambos parámetros están presentes, solo se tendrá en cuenta el api_id.

Ejemplo:

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getstatus&api_id=1c97394eea5806c0741be3601d8fca0b

O bien:

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getstatus&climsgid=FRS78913246

Respuesta:

<code_statut>

Ejemplo:

3

Códigos de estado: ver Codificación de estados

Códigos de error:

Códigos de error Descripción
100 Parámetro faltante
101 Error de autenticación: nombre de usuario, contraseña o dirección IP inválidos
201 api_id desconocido
202 climsgid desconocido

4.5 Devolución de estados

La API de TextingHouse enviará los estados mediante una petición HTTP POST que contiene el estado en formato JSON a una URL proporcionada por el cliente (callback URL). Esta URL se configura desde la interfaz API, página “Parámetros”, pestaña “Callbacks DLR y MO”.

Por ejemplo, si la URL configurada es: https://www.midominio.com/miscript.do. La petición enviada por TextingHouse tendrá la siguiente forma: 

POST https://www.mondomaine.com/monscript.do HTTP/1.1
Content-Type: application/json

{
  "apimsgid": "5d726149a129c829e8c23f7b",
  "climsgid": "FR-6468446",
  "status": "3"
}

Con los siguientes parámetros:

  • apimsgid : ID proporcionado por la API de TextingHouse (string)
  • climsgid : ID proporcionado opcionalmente por el cliente (string)
  • status : código de estado definitivo (string) – Lista de códigos de estado SMS: ver Codificación de estados

Solo se envían los estados definitivos (ver Codificación de estados). Los estados temporales no se transmiten mediante la URL de callback. Sin embargo, sí están disponibles mediante una consulta de estado clásica usando el comando “getstatus”.

El script del lado cliente debe responder con un código HTTP de tipo 2XX. El cuerpo de la respuesta no es procesado por TextingHouse.

4.6 Devolución de respuestas SMS (SMS MO)

La API puede devolver las respuestas a los SMS* mediante una petición HTTP POST que contiene la respuesta SMS en formato JSON a una URL proporcionada por el cliente (SMSMO callback URL). Esta URL se configura desde la interfaz API, página “Parámetros”, pestaña “Callbacks DLR y MO”.

* Dependiendo de los operadores y de los países de envío. Atención: cuando se utiliza un nombre de remitente (parámetro from del comando sendsms), los destinatarios no pueden responder a los SMS.

Por ejemplo, si la URL configurada es: https://www.midominio.com/miscript.do, la petición enviada por TextingHouse tendrá la siguiente forma:

POST https://www.mondomaine.com/monscript.do HTTP/1.1
Content-Type: application/json

{
  "apimsgid": "5d726149a129c829e8c23f7b",
  "climsgid": "FR-6468446",
  "from": "33600000000",
  "txt": "Texte du message",
  "date": "2019-04-01T13:09:16Z"
}

Con los siguientes parámetros:

  • apimsgid : ID proporcionado por la API de TextingHouse (string)
  • climsgid : ID proporcionado opcionalmente por el cliente (string)
  • from : número de teléfono del remitente del mensaje (string)
  • txt : contenido del mensaje (string)
  • date : fecha UTC del mensaje en formato ISO 8601: ‘YYYY-MM-DDTHH:mm’ (string)

El script del lado cliente debe responder con un código HTTP de tipo 2XX. El cuerpo de la respuesta no es procesado por TextingHouse.

4.7 Consulta de crédito

La consulta del crédito se realiza mediante el comando getcredit:

&cmd=getcredit

Ejemplo:

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getcredit

Respuesta:

<valeur>

Ejemplo:

1423

4.8 SMS de prueba al 999

El envío de un SMS al número 999 es una forma sencilla de probar la API, tanto para desarrollos como para supervisión del servicio.

El envío de un SMS a este número requiere autenticación, igual que un SMS estándar enviado a un destinatario “normal”. Cabe destacar que los SMS enviados al 999 no se facturan.

La API gestionará estas pruebas del mismo modo que los SMS estándar (ver secciones Envío de un mensaje, Solicitud de estado y Devolución de estados), lo que implica especialmente:

  • devolución de un ID de mensaje.
  • gestión de sus IDs internos (opcional),
  • devolución de un acuse de recibo con estado “entregado”. Este acuse virtual se genera únicamente con fines de prueba (el SMS no se entrega a ningún operador), pero confirma el correcto funcionamiento de nuestra cadena de envío y especialmente la comunicación entre los frontales API y nuestras plataformas de envío,
  • posibilidad de consultar el estado de este ID de mensaje.

El contenido del SMS de prueba es libre y no se tiene en cuenta.

4.9 Garantice la continuidad de su servicio gracias a la redundancia de la API

En el marco de la integración con nuestra API SMS, recomendamos encarecidamente implementar un mecanismo de conmutación automática (failover) en sus desarrollos.

Concretamente, si una solicitud enviada a la URL principal api.textinghouse.com no obtiene respuesta, le recomendamos reenviar inmediatamente la misma solicitud a nuestro servidor de respaldo api2.textinghouse.com.

Esta buena práctica permite garantizar una mayor tolerancia a fallos y una continuidad de servicio óptima para su aplicación, incluso en caso de indisponibilidad temporal del frontal principal.

5. Anexos

5.1 Códigos de estado

Código Tipo de estado Descripción
0 temporal Mensaje aceptado por la API, procesamiento en curso.
1 temporal En curso: SMS aceptado, pendiente de un estado definitivo.
3 definitivo Entregado
4 definitivo Expirado o fuera de alcance
5 definitivo No abonado
6 definitivo No entregable
7 definitivo Envío imposible
20 definitivo Envío bloqueado por crédito insuficiente

5.2 Códigos de error

Códigos de error Descripción
100 Parámetros faltantes
101 Error de autenticación: nombre de usuario, contraseña o
104 Crédito insuficiente
201 api_id desconocido
202 climsgid desconocido
300 Error al procesar la solicitud
350

Flood detectado.

Solo se permite un mensaje (mismo contenido y mismo número de teléfono) por destinatario cada 10 segundos. Si se supera este límite, la API devuelve este error.

400

Falta la mención STOP.

El mensaje es comercial pero no contiene la mención STOP sms-s.top.

 

5.3 Caracteres permitidos en los SMS

Patrón JavaScript que representa los caracteres permitidos:

/[ 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZÄäàÅåÆæßÇèéÉìÖöòØøÑñÜüù#¤%&()*+,\-./:;<>=§$!?£¿·@¡'"\n\[\]{}~^|]/

Ver norma GSM 03.38