Documentación de la API

Introducción

La API de EnvíaTuSMS permite a los desarrolladores el envío programático de mensajes de texto (SMS) de forma individual y masiva haciendo uso de su balance. Las peticiones pueden realizarse de forma secuencial o asíncrona según sea el requerimiento.

Las peticiones realizadas a la API podrán realizarse utilizando la librería cURL con el lenguaje de programación de su preferencia.
Las peticiones GET reciben los parametros en la URL.
Las peticiones POST reciben los parametos codificados en JSON con un header Content-Type: application/json.
Las respuestas retornadas por la API serán en formato JSON.

Una petición exitosa retornará un estatus HTTP de 200 OK.

API URL

URL principal para todas las peticiones.

https://www.enviatusms.com/api

Autenticación

Todas las peticiones deberán estar acompañadas de su api_key como parámetro GET en la URL, la cual puede verificar accediendo desde su cuenta aquí.

Ejemplo de petición con autenticación

https://www.enviatusms.com/api/balance?api_key=MI_API_KEY

Endpoints

Obtener su balance

El balance está expresado en Dólares, la cantidad de SMS que usted puede enviar está sujeta a las tarifas vigentes para el momento de su envío. Le recomendamos siempre consultar su balance antes de envíar una campaña de mensajería para ahorrarse peticiones fallidas.

HTTP Request
/balance

Ejemplo de request:

curl https://www.enviatusms.com/api/balance?api_key=MI_API_KEY

Parámetros retornados

Parámetro Tipo Descripción
status string ok al obtener una respuesta válida o error cuando haya un problema
sms array Cantidad de SMS que puede enviar por cada operadora con su balance actual
balance decimal Cantidad de dólares disponibles

Ejemplo de response JSON:

{ "status": "ok", "sms": { "movistar": 100, "digitel": 200, "movilnet": 50 }, "balance": 4.50 }

Enviar mensaje de texto (SMS)

Los mensajes de texto enviados a través de la API serán programados para su envío de forma inmediata y se descontarán automáticamente de su balance de usuario.

HTTP Request
/sms-multi

Parámetros disponibles

Parámetro Tipo Descripción
numeros array Un array de números en formato local o internacional hacia donde va dirigido el mensaje de texto.
Un formato de número valido puede ser con código de area: 584241234567 o sin dicho código: 4241234567
texto string|array Texto del mensaje a enviar. Máximo 160 caracteres. Caracteres con acentos serán convertidos a su equivalente sin acento. Estos caracteres pueden ser por ejemplo: á, é, í, ó, ú.

Puede ser un array de múltiples mensajes de texto, el cual debe ser de la misma cantidad que los números definidos. Esto es útil para enviar un mensaje único para cada número.

Ejemplo de request, enviando el mismo mensaje a todos los números:

curl -X POST -H "Content-Type: application/json" -d '{"numeros":["04265461179", "04244623824"], "texto":"Mensaje de prueba"}' https://www.enviatusms.com/api/sms-multi?api_key=MI_API_KEY

Ejemplo de request, enviando un mensaje personalizado a cada número:

curl -X POST -H "Content-Type: application/json" -d '{"numeros":["04265461179", "04244623824"], "texto":["Mensaje de prueba 0426", "Mensaje de prueba 0424"]}' https://www.enviatusms.com/api/sms-multi?api_key=MI_API_KEY

Parámetros retornados

Parámetro Tipo Descripción
status string ok al obtener una respuesta válida o error cuando haya un problema
campaign_id integer El ID de la campaña creada.
msg string Información adicional de la respuesta obtenida
ignored array Un array de números de celular que no cumplan con el formato de número de celular correcto. Los números ignorados no serán descontados de su balance.
sms_contenido string En caso de error relacionado a un SMS, esta variable contendrá el contenido del mensaje problemático.

Ejemplo de response JSON:

{ "status":"ok", "id": 1234, "msg":"Mensaje enviado con exito. Numeros invalidos ignorados.", "ignored": ["581234567896", "58123456789"] }

Consultar el estatus de una campaña

Puede consultar toda la información de una campaña, ya sea creada desde la API o desde nuestra interfaz.

HTTP Request
/campaign/{id}

Parámetros disponibles

Parámetro Tipo Descripción
id integer Parámetro de ruta, el ID de la campaña a consultar.

Ejemplo de request:

curl https://www.enviatusms.com/api/campaign/1?api_key=MI_API_KEY

Parámetros retornados

Parámetro Tipo Descripción
status string ok al obtener una respuesta válida o error cuando haya un problema
message_text string El contenido del mensaje de texto
created_at string Fecha de creación de la campaña. En formato: YYYY-MM-DD H:m:s
send_at string Fecha de envío programado de la campaña. En formato: YYYY-MM-DD H:m:s
approved integer 1 o 0 Si la campaña fue aprobada o no (en caso de pasar por moderación)
cancelled integer 1 o 0 Si la campaña fue cancelada por el administrador.
from_api integer 1 o 0 Si la campaña fue creada desde la API o no.
stats object Estadísticas generales de la campaña. Ver descripción de los valores retornados abajo.
stats.total_numbers integer La cantidad total de números de teléfono en esta campaña.
stats.total_sms integer La cantidad total de mensajes de texto a enviar.
stats.pending integer La cantidad de mensajes de texto pendientes por enviar. 0 significa que todos los mensajes fueron enviados, por lo que la campaña se puede considerar "completa".
stats.delivered integer La cantidad de mensajes de texto entregados.
stats.failed integer La cantidad de mensajes de texto fallidos.
numbers_stats object Estadísticas individuales de cada número. Ver descripción de los valores retornados abajo.
numbers_stats.mobile_number integer El número de teléfono en formato internacional.
numbers_stats.status integer
  • 0 SMS pendiente por enviar.
  • 1 SMS entregado por la operadora.
  • 4 SMS eliminado, no será enviado.
  • 7 SMS rechazado por la operadora.
numbers_stats.processed integer 0 o 1 Si el mensaje ya fue procesado por nuestra plataforma.
shortlink_stats object|null Estadísticas individuales del link corto, en caso de haber usado uno. Ver descripción de los valores retornados abajo.
shortlink_stats.short_url string La URL acortada utilizada nuestro servicio etsms.me
shortlink_stats.orig_url string La URL original que fue acortada.
shortlink_stats.total_clicks integer La cantidad de clics totales en el link.
shortlink_stats.unique_clicks integer La cantidad de clics únicos (por IP) en el link.
shortlink_stats.total_views integer La cantidad de visualizaciones del link. Este valor está sujeto a la conexión a internet del usuario al momento de leer el SMS y si su dispositivo soporta dicha carácteristica.

Ejemplo de response JSON:

{ "status": "ok", "message_text": "Mi campaña de mensajeria", "created_at": "2023-04-28 12:05:17", "send_at": "2023-04-28 12:05:17", "approved": 1, "cancelled": 0, "from_api": 0, "stats": { "total_numbers": 2, "total_sms": 2, "pending": 2, "delivered": 0, "failed": 0 }, "numbers_stats": [ { "mobile_number": 584244623824, "status": 0, "processed": 0 }, { "mobile_number": 584123658866, "status": 0, "processed": 0 } ], "shortlink_stats": { "short_url": "https://etsms.me/001", "orig_url": "https://www.enviatusms.com", "total_clicks": 0, "unique_clicks": 0, "total_views": 0 } }

Ejemplos de Códigos

Versión de PHP recomendada: >= 7.0

La implementación con en lenguaje PHP se puede hacer de forma sencilla definiendo una función ayudante que haga la petición cURL de la siguiente forma:

function requestHelper($url, $post = false, $data = null, $headers = []) {
    $ch = curl_init();

    $opts = array(
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_TIMEOUT_MS => 0,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_URL => $url,
        CURLOPT_SSL_VERIFYPEER => 0,
        CURLOPT_POST => $post
    );

    if ($data != null) {
        $opts += [CURLOPT_POSTFIELDS => $data];
    }

    if (count($headers)) {
        $opts += [CURLOPT_HTTPHEADER => $headers];
    }

    curl_setopt_array($ch, $opts);

    $result = curl_exec($ch);
    curl_close($ch);

    return $result;
}
                            

Ejemplo de envío de un SMS

Una vez definida la función, solo queda llamarla haciendo uso de la URL de la API de EnvíaTuSMS con el texto, el número y la cabecera HTTP, usando el método POST. Nótese que el parámetro $data el cual contiene el número y el mensaje, es un array asociativo que debe estar codificado en JSON para su envío:

$mensaje = "hola mundo";
$numeros = ["04120000000"]; // Obligatoriamente debe ser un array
$api_key = 'MI_API_KEY';
$url = "https://www.enviatusms.com/api/sms-multi?api_key={$api_key}";

$respuesta = requestHelper($url, true, json_encode(['numeros' => $numeros, 'texto' => $mensaje]), ['Content-Type' => 'application/json']);
                            

También es posible enviar un mensaje personalizado para cada número, cambiando la variable $mensajes por un array de mensajes. Nótese que la cantidad de mensajes debe coincidir con la cantidad de números, de lo contrario arrojará un error:

$mensajes = ["hola mundo 0412", "hola mundo 0414"];
$numeros = ["04120000000", "04140000000"]; // Obligatoriamente debe ser un array
$api_key = 'MI_API_KEY';
$url = "https://www.enviatusms.com/api/sms-multi?api_key={$api_key}";

$respuesta = requestHelper($url, true, json_encode(['numeros' => $numeros, 'texto' => $mensajes]), ['Content-Type' => 'application/json']);
                        

Lo cual arrojará una respuesta acorde a lo mencionado anteriormente.

Por último, la respuesta es un string codificado en JSON, por lo que hay que decodificarlo y hacer uso de él como un objeto:

$respuesta = json_decode($respuesta);

echo $respuesta->status;
echo $respuesta->msg;
                            

Ejemplo de consulta de balance

Haciendo uso de la misma función, podemos consultar el balance. La diferencia radica en los parámetros que le pasaremos a la llamada de la función.

La consulta de balance se hace con el método GET y no se necesita pasar datos o cabeceras adicionales. Nótese que el endpoint cambia en la URL:

$api_key = 'MI_API_KEY';
$url = "https://www.enviatusms.com/api/balance?api_key={$api_key}";
$respuesta = requestHelper($url);

$respuesta = json_decode($respuesta);

echo $respuesta->status;
echo $respuesta->creditos;
echo $respuesta->balance;
                            

Ejemplo de consulta de campaña

Haciendo uso de la misma función, podemos consultar los datos de una campaña. La diferencia radica en los parámetros que le pasaremos a la llamada de la función.

La consulta de campaña se hace con el método GET y solo se envía el id de la misma en la URL. Nótese que el endpoint cambia en la URL:

$api_key = 'MI_API_KEY';
$id_camp = 1;
$url = "https://www.enviatusms.com/api/campaign/{$id_camp}?api_key={$api_key}";
$respuesta = requestHelper($url);

$respuesta = json_decode($respuesta);

echo $respuesta->status;
echo $respuesta->message_text;

                            

Versión de Python recomendada: >= 3.6

La implementación en Python requiere la inclusión de dos librerías requests y json, la llamada a nuestra API y la conversión de la respuesta de JSON a un diccionario.

Ejemplo de consulta de balance

import requests, json

API_KEY = 'mi_api_key'

# Obtener balance de la cuenta
r = requests.get(f'https://www.enviatusms.com/api/balance?api_key={API_KEY}')
# Convertir respuesta JSON a diccionario
j = json.loads(r.text)

print(j)
print(j['status'])
print(j['creditos'])
print(j['balance'])
                                    

Ejemplo de envío de un SMS

Es posible enviar un único mensaje de texto a múltiples números de la siguiente forma:

import requests, json

API_KEY = 'mi_api_key'

# Enviar 1 SMS a Multiples numeros
data = {
	'numeros': [
		'04241234567',
		'04261234567'
	],
	'texto': 'Mensaje de prueba python'
}
r = requests.post(f'https://www.enviatusms.com/api/sms-multi?api_key={API_KEY}', json = data)
j = json.loads(r.text)
print(j)
                                    

También se puede enviar un mensaje de texto diferente para cada número. Tomando en cuenta que la cantidad de números y de mensajes en los arreglos, deben coincidir:

import requests, json

API_KEY = 'mi_api_key'

# Enviar multiples SMS a Multiples numeros
data = {
	'numeros': [
		'04241234567',
		'04261234567'
	],
	'texto': [
		'Mensaje de prueba python para 04241234567',
		'Mensaje de prueba python para 04261234567',
	]
}
r = requests.post(f'https://www.enviatusms.com/api/sms-multi?api_key={API_KEY}', json = data)
j = json.loads(r.text)
print(j)
                                    

Ejemplo de consulta de campaña

import requests, json

API_KEY = 'mi_api_key'
id_camp = 1

# Obtener datos de la campaña
r = requests.get(f'https://www.enviatusms.com/api/campaign/{id_camp}?api_key={API_KEY}')
# Convertir respuesta JSON a diccionario
j = json.loads(r.text)

print(j)
print(j['status'])
print(j['message_text'])