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.

---

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

---

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

Ejemplo de request:

Parámetros retornados

Ejemplo de response JSON:

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

Parámetros disponibles

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

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

Parámetros retornados

Ejemplo de response JSON:

---

Ejemplo de Código PHP

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;