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
.
URL principal para todas las peticiones.
https://www.enviatusms.com/api
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í.
https://www.enviatusms.com/api/balance?api_key=MI_API_KEY
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.
/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.
/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.
/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.
/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 |
|
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.
/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",
}
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'])