API de envío SMS http/POST
La API SMS http/POST está diseñada para técnicos y clientes que quieran conectar sus aplicaciones con la plataforma de mensajería SMS de FOXSYS.
Las funcionalidades de la API SMS http/POST son:
-
El envío de mensajes SMS de forma individual o masivo en tiempo real
-
Envío programado de mensajes SMS
-
Envío de mensajes SMS Unicode, SMS Concatenados y SMS Certificados
-
Consulta de saldo de créditos de una cuenta
Esta documentación explica detalladamente el proceso de integración y automatización de estas funcionalidades.
Para iniciar una integración con la API http/POST son imprescindibles los siguientes requisitos:
-
Una cuenta de FOXSYS asociada con un nombre de usuario (correo electrónico de registro). Crea una cuenta aquí.
-
Token API utilizado como contraseña y generado desde la sección Configuración API de tu cuenta.
-
URL del endpoint de la API http/POST y los valores de los parámetros para realizar la petición.
A tener en cuenta
La API http/POST de FOXSYS es una API REST que utiliza el protocolo HTTP POST, el formato JSON para el intercambio de información y una URL base común para todas las peticiones: https://api.foxsys.com/json/
Es recomendable utilizar una URL que incluya el protocolo HTTPS en cualquier versión de nuestra API.
Autenticación
El método de autenticación utilizado es Auth Basic HTTP.
Este tipo de autenticación consta de unas credenciales username:tokenapi que se incluyen en el encabezado de la petición HTTP codificado en base64().
Ejemplo de valor de encabezado de autenticación:
Authorization: Basic 9yewaXic21vYmlsZqS5jmSk04enFTbUU=
Recomendación
Se pueden generar tokens API desde la Configuración API de la cuenta. Recomendamos cambiar el token frecuentemente y utilizar diferentes tokens para cada uso, conexión o integración.
Configuración y filtros
A continuación se detallan variables de configuración y aspectos de seguridad importantes en una integración con la API de envío SMS http/GET:
-
Dirección IP desde donde se enviarán los mensajes. Si se activa esta opción, sólo se admitirán peticiones de la lista de dirección IPs introducida. Esta funcionalidad es opcional, por defecto se aceptarán mensajes de cualquier IP.
-
Remitente por defecto (por defecto FOXSYS). Sólo algunos operadores permiten la asignación dinámica y con valor alfanumérico del campo remitente.
-
Límite de mensajes diario, por defecto 100.000 sms/día.
-
Límite de mensajes por batch, por defecto 10.000 sms/petición.
-
Filtro por países, para que sólo se procesen mensajes de una lista de países.
-
Filtro anti-duplicados, para evitar enviar mensajes iguales a un mismo destinatario.
Todos estos parámetros se pueden activar y modificar en la Configuración API y Preferencias de la cuenta.
Importante
Se establece un máximo de 10 peticiones por segundo. Malos usos, abusos o un mayor volumen de peticiones provocarán un bloqueo temporal o permanente de la cuenta y/o dirección IP.
Recomendación
Recomendamos activar las Recargas automáticas para que siempre existan créditos disponibles en la cuenta y no se interrumpa el servicio de envío SMS.
Envío de mensajes SMS
Petición para el envío de mensajes SMS de forma individual o masiva.
Con esta funcionalidad se pueden enviar mensajes en tiempo real o de forma programada para un día y hora específicos. Además, se pueden añadir otros parámetros como el remitente, etiqueta, identificador, modo simulado, etc.
ENDPOINT
POST https://api.foxsys.com/json/send
PARÁMETROS
Los parámetros o datos se envían en el cuerpo una llamada http/POST en formato JSON. A continuación se describen los valores y funcionalidad de todos los parámetros.
recipient array obligatorio
Listado de números de los destinatarios. Array de parámetros msisdn.
msisdn string obligatorio
Números de teléfono de los destinatarios a los que se envía el mensaje. Los números deben cumplir el formato internacional E.164 y separados por comas (",") si se incluyen más de un número de destino.
Ejemplo: "msisdn":"34609033162"
message string obligatorio
Texto del mensaje a enviar. Si se envían SMS estándar sólo son válidos los caracteres del alfabeto GSM 3.38 7bit . Se pueden enviar también SMS Concatenados, SMS Unicode y SMS Certificados con los correspondientes parámetros.
Ejemplo: "message":"Hello world!"
scheduled YYYY-MM-DD HH:MM:SS
Programación del envío para el día y hora indicados. Si no se especifica este campo, se enviará el mensaje de forma inmediata. Formato: YYYY-MM-DD HH:MM:SS.
Importante: El valor de este campo se debe expresar en el uso horario GMT.
Ejemplo: "scheduled":"2024-04-12 10:00:00"
tpoa string
Campo remitente del mensaje SMS. Puede tener un valor numérico (longitud máxima 16 dígitos) o alfanumérico (capacidad máxima 11 caracteres).
La asignación y personalización del remitente sólo está disponible en algunos países y operadores. En caso contrario, el remitente será un valor numérico (shortcode o longcode) estático.
Ejemplo: "tpoa":"MyBrand"
subid string
Identificador de la petición. Longitud máxima de 20 caracteres.
Si no se incluye un valor en el parámetro subid, la plataforma asignará un identificador único de 13 caracteres que se mostrará en el resultado de la petición.
Ejemplo: "subid":"5aa3ea8028ce5"
label string
Campo de información libre para identificar y asignar atributos. Longitud máxima de 255 caracteres.
Posibles usos: usuario, aplicación, agrupación o campaña, etc.
Ejemplo: "label":"A05-enero-2024"
test 0 | 1
Activación del modo simulado de envío para pruebas y monitorización.
Si se asigna un valor 1 a este parámetro, los mensajes no se enviarán a los destinatarios y no se descontará ningún crédito. Los mensajes enviados en modo simulado se podrán consultar en el Histórico y otras herramientas.
Ejemplo: "test": 1
ackurl url
Url a la que se enviarán las notificaciones de confirmación de entrega y error de los mensajes enviados.
Se puede establecer una URL por defecto en la Configuración API de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: "ackurl":"https://clientserver.com/receive_ack"
clickurl url
Url a la que se enviarán las notificaciones de eventos de click en los enlaces de los mensajes enviados.
Se puede establecer una URL por defecto en la Configuración API de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: "clickurl":"https://clientserver.com/receive_click"
shortlink 0 | 1
Activación del reemplazo automático de enlaces.
Si su valor es 1 se reemplazarán todas las Urls del mensaje con un link corto (formato: foxsys.bi/XXXXXXX o dominio personalizado).
Se puede activar esta prestación de forma permanente para todos los mensajes en las Preferencias de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: "shortlink": 1
long 0 | 1
Activación de los SMS Concatenados en esta petición.
Si este campo tiene valor 1 el mensaje puede contener más de 160 caracteres. Más información sobre Cómo calcular el precio de un SMS.
Ejemplo: "long": 1
ucs2 0 | 1
Activación de los SMS Unicode en esta petición.
Si este campo tiene valor 1 el mensaje puede contener cualquier carácter, símbolo o emoji. La capacidad se reduce a 70 caracteres y se pueden enviar SMS concatenados y unicode. Más información sobre Cómo calcular el precio de un SMS.
Ejemplo: "ucs2": 1
crt email
Envío de un SMS Certificado en esta petición.
Se enviará a la dirección que contenga este parámetro un e-mail con el documento PDF de certificación.
Ejemplo: "crt":"info@client.es"
crt_name string
Nombre de la entidad o compañía que envía el SMS certificado. Sólo tiene efecto si se envía conjuntamente con el parámetro crt.
Ejemplo: "crt_name":"My Company SL"
crt_id string
Identificador fiscal de la entidad o compañía que envía el SMS certificado. Sólo tiene efecto si se envía conjuntamente con el parámetro crt.
Ejemplo: "crt_id":"ESB65213332"
crt_lang string
Idioma del certificado. Sólo tiene efecto si se envía conjuntamente con el parámetro crt.
Valores: ES, EN, CA, FR, DE, IT, NL, PT, NL, DA, SV, PL, RO, EL.
Ejemplo: "crt_lang":"EN"
nofilter 0 | 1
Si este campo tiene valor 1 no se aplicará el filtro de mensajes duplicados.
Se puede activar o desactivar esta prestación de forma permanente para todos los mensajes en las Preferencias de la cuenta y en ese caso no es necesario incluir este parámetro.
Ejemplo: "nofilter": 1
parameters json
Este campo contiene valores para reemplazar parámetros en el texto del mensaje. El mensaje puede contener uno o más parámetros (con el siguiente formato: %name%, %fieldn%, etc.). Es necesario especificar el valor de cada parámetro para cada uno de los destinatarios o establecer un valor por defecto.
Ejemplo: "parameters": [{"name": {"msisdn":"12015550123", "value":"John"}}, {"name": {"msisdn":"default", "value":"Client"}}]
RESULTADO
El resultado se obtiene en formato JSON con los siguientes elementos:
code integer
Código identificador que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: "code": "0"
message string
Descripción que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: "message": "Message has been successfully sent."
subid string
Identificador de la petición API.
Ejemplo: "subid": "6615686480e47"
Consulta de saldo
Consulta sobre el número de créditos disponibles de una cuenta.
ENDPOINT
GET https://api.foxsys.com/json/balance
Esta funcionalidad no tiene parámetros, basta con enviar unas credenciales correctas para identificar la cuenta al endpoint de consulta de saldo.
RESULTADO
El resultado de cualquier petición API SMS http/POST se obtiene en formato JSON con los siguientes elementos:
code integer
Código identificador que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: "code": "0"
message string
Descripción del error en la petición. Si la petición se ha procesado correctamente este campo no aparece.
Ejemplo: "message": "Unauthorized"
credits float
Número de créditos disponibles en el saldo de la cuenta.
Ejemplo: "credits": "1023.10"
Consulta de precios
Consulta sobre la tarifa (en créditos) de uno o varios países de destino.
ENDPOINT
GET https://api.foxsys.com/json/prices
PARÁMETROS
Los parámetros o datos se envían en el cuerpo de una llamada http/POST en formato JSON. A continuación se describen los valores y funcionalidad de todos los parámetros.
countries array
Lista de países para los que se quiere obtener la tarifa actualizada en créditos y otros detalles. Formato: códigos ISO de los países. Si este campo no se envía o es nulo, se devuelve la información de todos los países.
Ejemplo: "countries":["ES","FR","US","MX"]
format string
Formato deseado en el resultado de la petición. Valores: JSON (por defecto) XML CSV.
Ejemplo: "format":"CSV"
RESULTADO
El resultado se obtiene en formato JSON, XML o CSV con los siguientes elementos:
isocode float
Código ISO que identifica al país.
Ejemplo: "isocode": "FR"
prefix float
Prefijo telefónico del país.
Ejemplo: "prefix": "33"
name float
Nombre descriptivo del país en inglés.
Ejemplo: "name": "France"
credits float
Número de créditos disponibles en el saldo de la cuenta.
Ejemplo: "credits": 0.89
code integer
Código identificador que indica el error producido. Posibles valores en la el apartado Errores. Si la petición se ha procesado correctamente este campo no aparece.
Ejemplo: "code": "401"
message string
Descripción del error en la petición. Si la petición se ha procesado correctamente este campo no aparece.
Ejemplo: "message": "Unauthorized"
Gestión de envíos programados
Cancelación o ejecución de envíos programados pendientes.
ENDPOINT
POST https://api.foxsys.com/json/scheduled
PARÁMETROS
Los parámetros o datos se envían en el cuerpo de una llamada http/POST en formato JSON. A continuación se describen los valores y funcionalidad de todos los parámetros.
subid string obligatorio
Identificador de la solicitud de envío programado. Si este parámetro tiene como valor * afectará a todos los envíos programados pendientes de la cuenta.
Ejemplo: "subid":"5aa3ea8e5cdb6"
cmd string obligatorio
Comando a ejecutar. Valores posibles: cancel send, para eliminar o ejecutar en ese momento los envíos programados seleccionados.
Ejemplo: "cmd":"send"
RESULTADO
El resultado se obtiene en formato JSON con los siguientes elementos:
code integer
Código identificador que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: "code": "0"
message string
Descripción que indica si se ha podido procesar la petición de forma exitosa o si se ha producido un error. Posibles valores en la el apartado Errores.
Ejemplo: "message": "Scheduled messages successfully cancelled.
Recepción de estados
Obtención de los estados (entregado o error) de los mensajes enviados.
Con esta funcionalidad se recibe en una URL del cliente los eventos de confirmación de entrega o error de cada mensaje enviado.
Existen dos métodos para activar la recepción de estados en una URL:
-
Añadiendo una URL en el parámetro ackurl de la petición API de envío.
-
Introduciendo una URL en la Configuración API de la cuenta, en el campo URL de recepción de confirmaciones o errores de entrega.
En ambos casos cuando se produzca un estado de mensaje entregado o error se realizará una llamada http/GET a la URL proporcionada con los parámetros que se detallan a continuación.
PARÁMETROS
subid string
Identificador del mensaje. Este identificador es el que se obtiene como resultado en una petición API de envío SMS.
Ejemplo: &subid=5aa3ea8e5cdb6
acklevel string
Estado del mensaje.
Ejemplo: &acklevel=handset
desc string
Descripción del error en la entrega y comunicación del mensaje.
Ejemplo: &desc=REJECTD
status string
El valor de este campo indica si el mensaje sigue el proceso de entrega normal o si se ha producido un error.
Valores: ok koEjemplo: &status=ok
timestamp YYYY-MM-DD HH:MM:SS
Día y hora en uso horario GMT en el que se ha producido el evento y el mensaje ha llegado al estado comunicado.
Ejemplo: ×tamp=2024-05-12%2012%3A23%3A00
msisdn string
Número del destinatario del mensaje.
Ejemplo: &msisdn=5212221234567
Recepción de clics
Obtención de los clics en las URLs de los mensajes enviados.
Con esta funcionalidad se recibe en una URL del cliente los eventos de clic que se producen en los mensajes enviados.
Existen dos métodos para activar la recepción de clics en una URL:
-
Añadiendo una URL en el parámetro clickurl de la petición API de envío.
-
Introduciendo una URL en la Configuración API de la cuenta, en el campo URL de recepción de visitas o clics.
En ambos casos cuando se produzca un clic en una URL se realizará una llamada http/POST JSON a la URL proporcionada con los parámetros que se detallan a continuación.
PARÁMETROS
subid string
Identificador del mensaje. Este identificador es el que se obtiene como resultado en una petición API de envío SMS.
Ejemplo: "subid": "5aa3ea8e5cdb6"
msisdn string
Número del destinatario del mensaje en el que se ha producido un clic.
Ejemplo: "msisdn": "5212221234567"
ip string
Dirección IP del usuario que ha visitado la URL.
Ejemplo: "ip": "98.139.180.149"
useragent string
User agent con información del navegador y dispositivo que ha visitado la URL.
Ejemplo: "ip": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
timestamp YYYY-MM-DD HH:MM:SS
Día y hora en uso horario GMT en el que se ha producido el clic.
Ejemplo: "timestamp": "2024-05-12 12:23:00"
Reintentos
Si la llamada http/GET genera un error al llamar a la URL (estados HTTP 4xx o 5xx) se reintentará la entrega hasta 5 veces en los siguientes intervalos: 30s, 5m, 30m, 6h, 1d.
Importante
Para recibir mensajes SMS es necesario contratar números virtuales de envío y recepción SMS.
Errores
A continuación se describen los códigos de error HTTP que puede devolver una petición a la API SMS http/POST.
Esta es la lista completa de códigos de respuesta en el formato JSON:
