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
|
creditos |
integer | Cantidad de SMS que puede enviar con su balance actual |
balance |
decimal | Cantidad de dólares disponibles |
Ejemplo de response JSON:
{
"status":"ok",
"creditos":250,
"balance":4.009
}
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 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
|
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",
"msg":"Mensaje enviado con exito. Numeros invalidos ignorados.",
"ignored": ["581234567896", "58123456789"]
}
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;
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;
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)