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

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 }

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. Máximo 160 caracteres. Caracteres con acentos serán convertidos a su equivalente sin acento. Excepto para la letra é o É.

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"] }

Puede realizar una cotización en tiempo real de sus campañas antes del envío, para verificar el monto que será descontado de su balance. Esto es especialmente útil si sus campañas contienen una combinación de números de distintas operadoras, las cuales pueden poseer distintos precios, haciendo el cálculo final más complejo. Esta ruta le facilita conocer la inversión a realizar, números válidos, números inválidos y SMS totales a enviar antes de proceder con el envío real de sus campañas.

HTTP Request
/sms-costo

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. Máximo 160 caracteres. Caracteres con acentos serán convertidos a su equivalente sin acento. Excepto para la letra é o É.

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, cotizando 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-costo?api_key=MI_API_KEY

Ejemplo de request, cotizando 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-costo?api_key=MI_API_KEY

Parámetros retornados

Parámetro Tipo Descripción
precio_usd float El monto total en USD de la campaña
numeros_validos integer La cantidad de números válidos
numeros_invalidos integer La cantidad de números inválidos (no son sumados al precio)
cantidad_mensajes integer La cantidad de mensajes de texto que serán enviados. Si la longitud del mensaje de texto es de 160 caracteres o menos, esta cantidad coincidirá con el total de números válidos, de lo contrario se hará el cálculo según la cantidad de partes que posea cada mensaje.

Ejemplo de response JSON:

{ "precio_usd":20.655, "numeros_validos": 200, "numeros_invalidos":0, "cantidad_mensajes": 200 }

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.
shortlink_stats.location_unique_clicks object La cantidad de clics únicos (por IP) en el link, agrupados por país, región y ciudad.

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 } }

Puede acortar cualquier enlace para ahorrar caracteres en sus mensajes y obtener métricas de las visualizaciones y clics en el mismo. Nuestro servicio etsms.me le permite acortar hasta 10 enlaces diarios.

HTTP Request
/acortar-url

Parámetros disponibles

Parámetro Tipo Descripción
link string Una URL correctamente formada (con su protocolo http o https): https://www.mi-url-a-acortar.com

Ejemplo de request:

curl -X POST -H "Content-Type: application/json" -d '{"link":"https://www.mi-url-a-acortar.com"}' https://www.enviatusms.com/api/acortar-url?api_key=MI_API_KEY

Parámetros retornados

Parámetro Tipo Descripción
success boolean true al obtener una respuesta válida o false cuando haya un problema
error string Información adicional de la respuesta obtenida en caso de error
orig_link string La URL original que fue acortada: https://www.mi-url-a-acortar.com
link string La URL acortada https://etsms.me/XYZ
link_no_protocol string La URL acortada sin su protocolo (http o https) etsms.me/XYZ
id string El identificador único de la URL acortada (los caracteres luego de etsms.me/): XYZ

Ejemplo de response JSON:

{ "success": true, "orig_link": "https://www.mi-url-a-acortar.com", "link": "https://etsms.me/XYZ", "link_no_protocol": "etsms.me/XYZ", "id": "XYZ", }

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;
}
                            

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;
                            

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-costo?api_key={$api_key}";

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

También es posible cotizar 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-costo?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->precio_usd;
                            

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;
                            

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;

                            
$link = "https://www.mi-enlace-a-acortar.com";
$api_key = 'MI_API_KEY';
$url = "https://www.enviatusms.com/api/acortar-url?api_key={$api_key}";

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

echo $respuesta->success;
echo $respuesta->link;

                            

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.

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'])
                                    

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)
                                    

Es posible cotizar 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-costo?api_key={API_KEY}', json = data)
j = json.loads(r.text)
print(j)
                                    

También se puede cotizar 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-costo?api_key={API_KEY}', json = data)
j = json.loads(r.text)
print(j)
                                    
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'])
                                    
import requests, json

API_KEY = 'mi_api_key'
link = 'https://www.mi-enlace-a-acortar.com'

data = {
	'url': link
}
r = requests.post(f'https://www.enviatusms.com/api/acortar-url?api_key={API_KEY}', json = data)
# Convertir respuesta JSON a diccionario
j = json.loads(r.text)

print(j)
print(j['success'])
print(j['link'])