NAV Navbar
cURL Ruby Python PHP Java

en es pt

Introduccion

Sean bienvenidos a nuestra documentación para desarrolladores. Aquí usted encontrara todo lo que necesita para integrar su empresa a nuestra plataforma de mensajes.

Es posible hacer la integración de las siguientes formas:

API HTTPS Permite el envió y recibimiento de mensajes y status a través del protocolo HTTPS utilizando los métodos GET o POST
API SMPP Protocolo especifico para intercambio de mensajes SMS, permite mantener una conexión activa constante con nuestro servidor SMPP. Es indicado para clientes con trafico superior a 5 millones de mensajes por mes.
API SFTP Protocolo utilizado para transferencia de archivos, es indicado para envíos de mensajes en masa (Lote). Los archivos son transferidos por el cliente para nuestros servidores y son inmediatamente procesados.
Websphere MQ Utilizado para transferencia de mensajes entre servidores Websphere MQ, es indicado para clientes con trafico superior a 30 millones de mensajes por mes. Principalmente para bancos financieros donde el cliente ya posee este sistema funcionando para mensajes internos. Esta opción de integración posee un valor de configuración y mantenimiento de ambiente fijado en R$50.000,00 y R$20.000,00 respectivamente.

Conozca también nuestro portal Web, por el su empresa puede administrar usuarios, proyectos y configuraciones. Enviar y recibir mensajes y obtener informes sin la necesidad de desarrollo o integracion

Términos importantes

MT Mobile Terminated Es un termino utilizado para mensajes que poseen el usuario (Aparato) como destino. O sea, mensajes que fueron originados por su empresa con destino al usuario (Aparato).
Response Respuesta sincronica de Movile Es una respuesta inmediata de una solicitud hecha en nuestra API, donde informamos si el mensaje fue aceptado o no por nuestra plataforma
Callback Sent status o Estatus de envió Es el primer status de envió que retornamos, en el informamos si fue posible, o no, hacer la entrega del mensaje. para la operadora.
DR ou DLR Delivery Receipt Es el segundo status de envió que retornamos, donde informamos si fue posible, o no, hacer la entrega para el aparato. Las operadoras envían para Movile esta información y nosotros la entregamos al cliente. El tiempo de entrega es variable, por ejemplo si el aparato estaba apagado en el momento del envió y el usuario lo encendió 2 horas después este status DLR sera entregado al cliente con 2 horas de atraso.
Obs1: Esta confirmación de entrega en el aparato, existirá solamente para casos en que el mensaje fue entregado con éxito en la operadora. O sea, el primer status (Callback) fue de exito.
Obs2: Es muy importante resaltar que infelizmente las operadoras OI y Sercomtel no poseen esta funcionalidad, o sea, no nos retornan la información de entrega en el aparato. Los envíos realizados para números de estas operadoras tendrán solamente la informacion de entrega en la operadora (callback)
MO Mobile Originated Es el termino utilizado para mensajes que poseen su empresa como destino. O sea, mensajes que fueron originados por el usuario (Aparato). Y utilizado por ejemplo en flujos de preguntas y respuestas vía SMS, cuando es necesario una confirmación por parte del usuario.
LA Short Code Numero corto de 5 o 6 digitos, utilizados para envio y recibimiento de mensajes SMS. Son designados por las operadoras para integradores homologados (Movile), y poseen reglas anti-fraude y anti-spam.

Flujo de Mensajes

Flujo simplificado - MT, Callback, DLR, e MO.

alt text

API HTTPS

Esta API permite que usted automatice las solicitudes de envíos de mensajes únicas o en lotes, y la recuperación de los estatus de envíos a travez de consultas. Ella utiliza el protocolo HTTP con TLS y acepta los métodos GET con parámetros query string o POST con parámetros en JSON.

Autenticacion

Para efectuar envíos y consultas en nuestra API es necesaria una autenticacion por medio de usuario o e-mail, en conjunto con un token.

Campo Detalles Data Type
UserName Su usuário o email String
AuthenticationToken Su token de autenticacion. Verifique aqui y lea las siguientes descripciones de usuarios. String
Tipo Detalles
Administrador Usuario administrador de su empresa, es utilizado para crear/editar/desactivar sub cuentas y otros usuarios y visualizar informes de toda la empresa.
Este usuario no hace envíos de mensajes ni por el portal ni vía integración API.
Usuario Usuario utilizado para envió de mensajes via API y portal, puede visualizar informes especificos de su sub cuenta.
Un usuario es siempre relacionado a una única sub cuenta.
Una sub cuenta puede contener multipes usuarios.
Cada sub cuenta es un centro de costo en nuestra plataforma, los mensajes son discriminados en informes y financieramente por sub cuenta y no por usuario.

Detalles de conexión

Hostname api-messaging.movile.com
APIs Envíos individuales /v1/send-sms
Envíos en lote /v1/send-bulk-sms
Puerta 443 (https)
Protocolo HTTPS (encriptacion TLS)
Autenticacion username + token
Portal messaging.movile.com

Codificación (encoding)

El estándar de codificación utilizado es UTF-8, todo el contenido de los mensajes deben seguir ese estándar.

Es posible escapar los caracteres caso desee codificar utilizando el formato HTTP

A seguir algunos ejemplos de codificación

“messageText”:“La combinación fue perfecta :)”

O usted puede escapar los caracteres en el caso que quiera:

“messageText”:“La combina\u00e7\u00e3o fue perfecta :)”

Envió de mensajes (MT)

Envio por método GET - Individual

require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/send-sms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = "{\"destination\": \"5511900000000\" ,  \"messageText\": \"linha\\nquebrada\"}"

response = http.request(request)
puts response.read_body
import requests

url = "https://api-messaging.movile.com/v1/send-sms"

payload = "{\"destination\": \"5511900000000\" ,  \"messageText\": \"linha\\nquebrada\"}"
headers = {
    'username': "<username>",
    'authenticationtoken': "<authenticationtoken>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl -X POST \
  https://api-messaging.movile.com/v1/send-sms \
  -H 'authenticationtoken: <authenticationtoken>' \
  -H 'username: <username>' \
  -H 'content-type: application/json' \
  -d '{"destination": "5511900000000" , "messageText": "linha\nquebrada"}'

Mod curl:
sudo apt-get/yum install php5-curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/send-sms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"destination\": \"5511900000000\" ,  \"messageText\": \"linha\\nquebrada\"}",
  CURLOPT_HTTPHEADER => array(
    "authenticationtoken: <authenticationtoken>",
    "username: <username>",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;

public class SendSms {

    public static void main(String[] args) {
        String url = "https://api-messaging.movile.com/v1/send-sms";

        String userName = "<username>";
        String authenticationToken = "<authenticationtoken>";

        String body = "{\"destination\": \"5511900000000\" ,  \"messageText\": \"linha\\nquebrada\"}";

        String response = doPost(url, body, userName, authenticationToken);
        System.out.println(response);
    }

    public static String doPost(String strUrl, String request, String userName, String authenticationToken) {
        HttpURLConnection conn = null;
        OutputStreamWriter wr = null;
        BufferedReader br = null;
        try {
            URL url = new URL(strUrl);

            conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setUseCaches(false);
            conn.setInstanceFollowRedirects(true);
            conn.setConnectTimeout(30000);
            conn.setReadTimeout(30000);

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("UserName", userName);
            conn.setRequestProperty("AuthenticationToken", authenticationToken);

            // write the request
            wr = new OutputStreamWriter(conn.getOutputStream());
            wr.write(request);
            wr.close();

            // read the response
            br = new BufferedReader(new InputStreamReader(conn.getInputStream()));

            StringBuilder resp = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) {
                resp.append(line).append("\n");
            }
            return resp.toString();

        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            try {
                if (wr != null) {
                    wr.close();
                }
                if (br != null) {
                    br.close();
                }
                if (conn != null) {
                    conn.disconnect();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return null;
    }
}

Al hacer el envió usted recibirá un JSON informando el id que fue generado para este mensaje (Response o Respuesta sincrona de Movile):

[
  {
  "id":"9cb87d36-79af-11e5-89f3-1b0591cdf807",
  "correlationId":"myId"
  }
]

Vía método GET, es posible realizar el envió de un mensaje pasando todos los parámetros como query string

URL para envíos unitarios

GET https://api-messaging.movile.com/v1/send-sms

Parametros Query String

* Campo obligatorio

Campo Detalles Tipo
destination* Teléfono para el cual sera enviado el mensaje (incluido código de país). Ejemplo: 5511900000000 String
messageText* Texto del mensaje que sera enviado (max 1280 chars). String
correlationId Un ID único definido por usted para coincidencia con los estatus de envió (Callback y DLR). Este parámetro es opcional y usted puede utilizar el ID generado por Movile para coincidencia (max 64 chars). String
extraInfo Cualquier información extra que usted desee adicionar al mensaje (max 255 chars). String
timeWindow Mensajes serán enviados apenas en horarios específicos. Por ejemplo, si usted configura la ventana [11, 12, 18], los mensajes seran enviados entre 11:00 y 11:59, 12:00 y 12:59, 18:00 y 18:59, este parámetro se debe definir en la raíz del objeto JSON Integer[]
expiresAt Los mensajes no serán enviados después de esta fecha. El formato utilizado es Unix time . Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
expiresInMinutes El mensaje sera expirado después del tiempo informado en este campo. El tiempo pasa a ser contabilizado en el momento que el mensaje es recibido por Movile. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
expiresDate El mensaje no sera enviado después de esta fecha. El campo acepta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) String
scheduledAt El mensaje no sera enviado después de esta fecha. El formato utilizado es Unix time. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
delayedInMinutes Minutos después que la solicitud es realizada el mensaje sea enviado. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
scheduledDate El mensaje no sera enviado antes de este fecha. El campo soporta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) String
timeZone Especifica el timezone que sera utilizado directamente en los campos: expiresDate, scheduledDate y timeWindow (que sera modificado en caso que sean utilizados timezones dinámicos como los horarios de verano). Si el timezone no estuviese presente en la solicitud el sistema verificara el timezone del usuario - si estuviera presente - o el timezone del país del usuario en el ultimo caso. Si ninguna de las opciones estuvieran presentes, el sistema utilizara el horario UTC String
campaignAlias Identificación de campaña creada previamente. Clique aqui para registar una nueva campaña, este parámetro se debe definir en la raíz del objeto JSON String
flashSMS Flash SMS,use esta opción para enviar un mensaje pop-up al teléfono del usuario. Para enviar un mensaje Flash pase el parámetro true. Boolean

Envio por método POST - Individual o e lote

require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/send-bulk-sms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = '{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}'

response = http.request(request)
puts response.read_body
import requests

url = "https://api-messaging.movile.com/v1/send-bulk-sms"

payload = '{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}'
headers = {
    'username': "<username>",
    'authenticationtoken': "<authenticationtoken>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
curl --request POST \
  --url https://api-messaging.movile.com/v1/send-bulk-sms \
  --header 'authenticationtoken: <Token de autenticação>' \
  --header 'username:<Usuário Movile Messaging>' \
  --header 'content-type: application/json' \
  --data "{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}"

Mod: curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/send-bulk-sms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{ \"messages\":[{ \"destination\":\"5519999999999\", \"messageText\":\"First message\" }, { \"destination\":\"5519999999999\" }, { \"destination\":\"5519999999999\" }], \"defaultValues\":{\"messageText\":\"Default message\" }}",
  CURLOPT_HTTPHEADER => array(
    "authenticationtoken: <authenticationtoken>",
    "content-type: application/json",
    "username: <username>"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;

public class SendSms {

    public static void main(String[] args) {
        String url = "https://api-messaging.movile.com/v1/send-bulk-sms";

        String userName = "<username>";
        String authenticationToken = "<authenticationtoken>";

        String body = "{ \"messages\":[{ \"destination\":\"5519999999999\", \"messageText\":\"First message\" }," +
                " { \"destination\":\"5519999999999\" }, { \"destination\":\"5519999999999\" }]," +
                " \"defaultValues\":{\"messageText\":\"Default message\" }}";

        String response = doPost(url, body, userName, authenticationToken);
        System.out.println(response);
    }

    public static String doPost(String strUrl, String request, String userName, String authenticationToken) {
        HttpURLConnection conn = null;
        OutputStreamWriter wr = null;
        BufferedReader br = null;
        try {
            URL url = new URL(strUrl);

            conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setUseCaches(false);
            conn.setInstanceFollowRedirects(true);
            conn.setConnectTimeout(30000);
            conn.setReadTimeout(30000);

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("UserName", userName);
            conn.setRequestProperty("AuthenticationToken", authenticationToken);

            // write the request
            wr = new OutputStreamWriter(conn.getOutputStream());
            wr.write(request);
            wr.close();

            // read the response
            br = new BufferedReader(new InputStreamReader(conn.getInputStream()));

            StringBuilder resp = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) {
                resp.append(line).append("\n");
            }
            return resp.toString();

        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            try {
                if (wr != null) {
                    wr.close();
                }
                if (br != null) {
                    br.close();
                }
                if (conn != null) {
                    conn.disconnect();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return null;
    }
}

Al hacer el envió, retornara un objeto JSON con un UUID del lote e de los mensajes individuales :


  {
  "id": "ce528d70-013b-11e7-98f2-e27c463c8809",
  "messages": [
    {
      "id": "ce528d71-013b-11e7-98f2-e27c463c8809"
    },
    {
      "id": "ce528d72-013b-11e7-98f2-e27c463c8809"
    }
  ]
}

Permite el envió de mensajes en lote o individuales pasando los parámetros de un objeto JSON

Solicitud HTTP Method POST

Ejemplo de JSON para envio em Lote:

Exemplo 1:

{
  "messages":[
    {
      "destination":"5519900001111",
      "messageText":"First message"
    },
    {
      "destination":"5519900002222"
    },
    {
      "destination":"5519900003333"
    }
  ],
  "defaultValues":{
    "messageText":"Default message"
  }
}

Exemplo 2:

{
  "messages":[
    {
      "destination":"5519900001111",
      "messageText":"First message"
    },
    {
      "destination":"5519900002222"
    }
  ],
  "timeZone":"America/Sao_Paulo",
  "scheduleDate": "2017-01-28T02:30:43",
  "timeWindow": [12, 15, 20],
  "defaultValues":{
    "messageText":"Default message"
  }
}

Exemplo 3:

`
{
  "messages":[
    {
      "destination":"5519900001111",
    },
    {
      "destination":"5519900002222"
    }
  ],
  "defaultValues":{
    "messageText":"Default message",
    "flashSMS":"true"
  }
}

Observe que en los ejemplos de arriba, algunos campos “destination” no tienen un “messageText” atribuido directamente para ellos, en este caso, el texto del mensaje sera el “messageText” dentro de “defaultValues”. Esa función es útil cuando es necesario el envió del mismo mensaje para varios números diferentes.

POST https://api-messaging.movile.com/v1/send-bulk-sms Content-Type: application/json

El cuerpo de la solicitud necesita contener el objeto JSON con las informaciones conforme los campos abajo:

* Campo obligatorio

Campo Detalles Tipo
destination* Teléfono para el cual sera enviado el mensaje (incluido código de país). Ejemplo: 5511900000000 String
messageText* Texto del mensaje que sera enviado (max 1280 chars). String
correlationId Un ID único definido por usted para coincidencia con los estatus de envió (Callback y DLR). Este parámetro es opcional y usted puede utilizar el ID generado por Movile para coincidencia (max 64 chars). String
extraInfo Cualquier información extra que usted desee adicionar al mensaje (max 255 chars). String
timeWindow Mensajes serán enviados apenas en horarios específicos. Por ejemplo, si usted configura la ventana [11, 12, 18], los mensajes seran enviados entre 11:00 y 11:59, 12:00 y 12:59, 18:00 y 18:59 Integer[]
expiresAt Los mensajes no serán enviados después de esta fecha. El formato utilizado es Unix time . Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
expiresInMinutes El mensaje sera expirado después del tiempo informado en este campo. El tiempo pasa a ser contabilizado en el momento que el mensaje es recibido por Movile. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
expiresDate El mensaje no sera enviado después de esta fecha. El campo acepta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) String
scheduledAt El mensaje no sera enviado después de esta fecha. El formato utilizado es Unix time. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
delayedInMinutes Minutos después que la solicitud es realizada el mensaje sea enviado. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) Long
scheduledDate El mensaje no sera enviado antes de este fecha. El campo soporta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) String
timeZone Especifica el timezone que sera utilizado directamente en los campos: expiresDate, scheduledDate y timeWindow (que sera modificado en caso que sean utilizados timezones dinámicos como los horarios de verano). Si el timezone no estuviese presente en la solicitud el sistema verificara el timezone del usuario - si estuviera presente - o el timezone del país del usuario en el ultimo caso. Si ninguna de las opciones estuvieran presentes, el sistema utilizara el horario UTC String
campaignAlias Identificación de campaña creada previamente. Clique aqui para registar una nueva campaña String
flashSMS Flash SMS,use esta opción para enviar un mensaje pop-up al teléfono del usuario. Para enviar un mensaje Flash pase el parámetro true. Boolean

Respuestas de mensajes en lote

La respuesta de envíos en lote contendrá un archivo JSON con las informaciones necesarias para su rastreamiento, sera generado un id para todo el lote y un id y correlationid individual para cada mensaje:

Campo Detalles Tipo
id UUID generado para este lote String
messages Este campo es un array con las respuestas de los mensajes individuales del lote, contiene el id y el correlationid de cada mensaje enviado. SingleSMSResponse[]

Estatus de envio (Callback e DLR)

Existen dos maneras de obtener los estatus de envíos de los mensajes, son ellas:

Cuando entregamos el mensaje en la operadora, o en el momento que la operadora nos informa que se entrego el mensaje en el aparato, la información es pasada instantáneamente para usted.

Los estatus quedan disponibles por 3 días, e pueden ser consultados por el UUID que Movile retorno al recibir el mensaje de su empresa, o por el ID que su empresa paso al entregar el mensaje para Movile.
La desventaja de esta opción de consulta al revés de webhook, es que usted hará solicitudes de consulta de un ID que puede todavía no haber sido entregado en la operadora o en el aparato, en este caso, una serie de solicitudes innecesarias serán realizadas. Por ejemplo, si un usuario estaba con el aparato apagado cuando envio un mensaje para el y lo encendió dos horas después, usted consultara este ID innumerables veces por dos horas. En el caso de la utilización de webhook, esta información seria enviada para usted en el momento que el mensaje fuese entregado en el aparato, sin solicitudes vaciás.

Estatus via webhook (entrega en su webservice)

Para configurar el envió de los Callbacks y DRs (dudas sobre los términos consulte la pestaña Términos Importantes) primeramente es necesario loguear en Movile messaging las configuraciones de la API, en el formulario de configuración usted podrá proveer las URLs para donde serán enviados los estatus de envió (Callbacks) y los estatus de confirmación de entrega en el aparato (DRs)

Después de la inclusión de su webhook en el portal arriba, las configuraciones serán replicadas para nuestra plataforma en hasta 10 minutos, y llamaremos su URL cuando las siguientes acciones ocurran:

Accion Estatus de retorno enviado
Después que un mensaje fue entregado o no, en la operadora API de estatus de envió (callback)
Cuando un mensaje fue entregado o no, en el aparato del cliente API de Delivery Report (DRs)

Ejemplo JSON Estatus de Envio (callback - entrega en la operadora)

POST https://example.com/callback/
Content-Type: application/json

{
  "id":"f9c100ff-aed0-4456-898c-e57d754c439c",
  "correlationId":"client-id",
  "carrierId":1,
  "carrierName":"VIVO",
  "destination":"5511900009999",
  "sentStatusCode":2,
  "sentStatus":"SENT_SUCCESS",
  "sentAt":1266660300000,
  "sentDate":"2010-02-20T10:05:00Z",
  "campaignId":"64",
  "extraInfo":"",
}

Campos JSON respuesta Callbacks (sent status)

Campo Descripción
id UUID generado del mensaje
correlationId Su identificación de este mensaje
carrierId Identificador de la operadora
carrierName Nombre de la operadora
destination Número de telefone da mensagem enviada
sentStatusCode Códigos de estatus generado por Movile para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones.
sentStatus descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones.
sentAt Hora do envió, el formato utilizado es Unix_time.
sentDate Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ
campaignId Identificador de campaña en el caso que exista.
extraInfo Cualquier información extra adicionada por el cliente en el envió del mensaje

Campos JSON respuesta Delivery Reports (DRs)

Campo Descripción
id UUID generado del mensaje
correlationId Su identificación de este mensaje
carrierId Identificador de la operadora
carrierName Nombre de la operadora
destination Número de telefone da mensagem enviada
sentStatusCode Códigos de estatus generado por Movile para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones.
sentStatus descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones.
sentAt Hora do envió, el formato utilizado es Unix_time.
sentDate Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ
deliveredStatusCode Código de estatus generado por Movile para un mensaje indicando el estatus de envió. Verifique en el código de estatus para mas informaciones
deliveredStatus descripción de estatus de envió. Verifique en código de estatus para mas informaciones.
deliveredAt Hora do envió, el formato utilizado es Unix_time.
deliveredDate Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ
campaignId Identificador de campaña en el caso que exista.
extraInfo Cualquier información extra adicionada por el cliente en el envió del mensaje

Consulta Estatus via solicitud HTTP

Para consultar el estatus del ultimos mensaje enviado es necesario hacer una solicitud GET en la URL abajo pasando como parámetro el UUID(s) o el correlationId(s) obtenido en la respuesta del envió.

GET https://api-messaging.movile.com/v1/sms/status/search

{ "ids": ["918F3591-9AD6-11E7-9C9B-E255B01A8B1A","234F3591-6AD6-11E7-9C9B-E255B01A8B1A"], "correlationIds": ["2468"] }

También es posible obtener sólo el estado aún no consultado:

GET https://api-messaging.movile.com/v1/sms/status/list

Observe que este endpoint devuelve sólo el estado que no se devuelve por este punto final.

Respuesta

Campos JSON de respuesta:

Campo Detalles Tipo
id UUID generado en la solicitud para el mensaje String
correlationId Mismo correlationId de la solicitud String
carrierId ID de la operadora, para mas informaciones consulte el código de error Long
carrierName Nombre da la operadora String
destination Número de telefono del mensaje enviado String
sentStatusCode sentStatusCode Códigos de estatus generado por Movile para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones.
sentStatus Descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones. String
sentStatusAt Cuando el mensaje fue enviado. Es un Epoch Date Long
sentStatusDate Cuando el mensaje fue enviado. Formato yyyy-MM-dd’T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601) String
deliveredStatusCode Código de estatus indicando el estatus de envió. Verifique en el código de estatus para mas informaciones. Long
deliveredStatus Descripción de estatus de envió. Verifique en código de estatus para mas informaciones. String
deliveredAt Cuando el mensaje fue enviado. Es un Epoch Date Long
deliveredDate Cuando el mensaje fue enviado. Formato yyyy-MM-dd’T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601) String
campaignId Identificador de campaña Long
extraInfo Cualquier información extra adicionada por el cliente en el envió del mensaje String

Ejemplo JSON Delivery Report (DR ou DLR - Entrega en el aparato del usuario)

{
  "id":"8f5af680-973e-11e4-ad43-4ee58e9a13a6",
  "correlationId":"myId",
  "carrierId":5,
  "carrierName":"TIM",
  "destination":"5519900001111",
  "sentStatusCode":2,
  "sentStatus":"SENT_SUCCESS",
  "sentStatusAt":1420732929252,
  "sentStatusDate":"2015-01-08T16:02:09Z",
  "deliveredStatusCode":4,
  "deliveredStatus":"DELIVERED_SUCCESS",
  "deliveredAt":1420732954000,
  "deliveredDate":"2015-01-08T16:02:34Z",
  "campaignId":1234
}

Respuesta del usuario (MO)

La API de MO permite la automatización del proceso de recuperación de respuestas enviadas por los clientes a los mensajes que usted le envió a ellos. Todas las solicitudes usan el método GET y las respuestas son enviadas en formato JSON

Es posible también la configuración para que los MOs sean encaminados conforme llegan, para una API del cliente. Esa es la forma mas eficiente ya que no es necesario realizar ninguna llamada, solo se tratan los envíos conforme van llegando. Para que esta configuración sea realizada es necesario abrir un ticket con nuestro equipo de soporte técnico a través del e-mail support.messaging@movile.com pasando la URL que recibirán los MOs

Ejemplo JSON enviado a su API (método POST)

{
     "id": "25950050-7362-11e6-be62-001b7843e7d4",
     "subAccount": "iFoodMarketing",
     "campaignAlias": "iFoodPromo",
     "carrierId": 1,
     "carrierName": "VIVO",
     "source": "5516981562820",
     "shortCode": "28128",
     "messageText": "Eu quero pizza",
     "receivedAt": 1473088405588,
     "receivedDate": "2016-09-05T12:13:25Z",
     "mt": {
       "id": "8be584fd-2554-439b-9ba9-aab507278992",
       "correlationId": "1876",
       "username": "iFoodCS",
       "email": "customer.support@ifood.com"
     }
   }

Cada solicitud realizada retornara los MOs de los últimos 5 días, hasta un limite de 10.000 MOs. Para las fechas anteriores o cantidades mayores por favor entrar en contacto con nuestro equipo de soporte a través del e-mail support.messaging@movile.com

El comportamiento de Query List MO sera diferente para cada usuario autenticado debido al nivel de permisos de cada usuario.

Recomendamos el metodo de envio de los MOs para la API, todo MO enviado será automaticamente enviada para la API ya que de esta forma las respuestas pueden ser tratadas inmediatamente despues de recibidas

Perfil Permisos
Regular Cada solicitud realizada en la MO API solo retornara los MOs correspondientes a la subcuenta a la que el usuario pertenece. No es posible para un usuario regular recuperar los MOs de otras subcuentas.
Administrador El comportamiento estándar para el usuario administrador es recuperar todos los MOs de todas las subcuentas. Si un admin desea recuperar los MOs de apenas una de las subcuentas es necesario especificar la subcuenta en el parámetro subAccount con el id de la subcuenta deseada.

Fomato de respuesta estandar de MO

Ejemplo JSON de respuesta:

{
  "total": 1,
  "start": "2016-09-04T11:12:41Z",
  "end": "2016-09-08T11:17:39.113Z",
  "messages": [
    {
      "id": "25950050-7362-11e6-be62-001b7843e7d4",
      "subAccount": "iFoodMarketing",
      "campaignAlias": "iFoodPromo",
      "carrierId": 1,
      "carrierName": "VIVO",
      "source": "5516981562820",
      "shortCode": "28128",
      "messageText": "Eu quero pizza",
      "receivedAt": 1473088405588,
      "receivedDate": "2016-09-05T12:13:25Z",
      "mt": {
        "id": "8be584fd-2554-439b-9ba9-aab507278992",
        "correlationId": "1876",
        "username": "iFoodCS",
        "email": "customer.support@ifood.com"
      }
    },
    {
      "id": "d3afc42a-1fd9-49ff-8b8b-34299c070ef3",
      "subAccount": "iFoodMarketing",
      "campaignAlias": "iFoodPromo",
      "carrierId": 5,
      "carrierName": "TIM",
      "source": "5519987565020",
      "shortCode": "28128",
      "messageText": "Meu hamburguer está chegando?",
      "receivedAt": 1473088405588,
      "receivedDate": "2016-09-05T12:13:25Z",
      "mt": {
        "id": "302db832-3527-4e3c-b57b-6a481644d88b",
        "correlationId": "1893",
        "username": "iFoodCS",
        "email": "customer.support@ifood.com"
      }
    }
  ]
}

Tanto las solicitudes de listado (list) como la funcion de busqueda (search) retornan un objeto JSON con los campos abajo:

Campo Detalles Tipo
total Numero total de MOs retornados por la solicitud Integer
start Limite minimo de la query String
end Limite máximo de la query String
messages Listado de los objetos List

Cada mensaje del campo messages posee la siguiente estructura:

Campo Detalles Tipo
id Id del mensaje String
subAccount subcuenta responsable por enviar el mensaje que genero la respuesta String
carrierId Id de la operadora Integer
carrierName Nombre de la operadora String
source Numero de telefono que envio el mensaje de respuesta String
shortCode O shortcode del mensaje que origino la respuesta y por el cual la respuesta fue enviada. String
messageText Texto del mensaje de respuesta. String
receivedAt hora de recebido Long
receivedDate Fecha y hora de recibimiento en formato UTC String
campaignAlias Alias da campaña que origino la respuesta String
mt MT original que genero la respuesta MT

MTs tienen la siguinte estructura

Campo Detalles Tipo
id Id del MT String
correlationId CorrelationID enviado en el MT String
username Username del usuário responsable por enviar el MT String
email Email del responsable por enviar el MT String

Solicitud listar MO (list)

El listado ira a retornar todos los MOs recibidos desde la ultima llamada de acuerdo con la respuesta estándar descripta encima. Una vez que esta llamada es realizada sera consumida y no retornara las llamadas siguientes.

Como un usuario regular, para recuperar todos los MOs de una subcuenta use:

GET https://api-messaging.movile.com/v1/sms/receive/list

Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:

GET https://api-messaging.movile.com/v1/sms/receive/list

Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:

GET https://api-messaging.movile.com/v1/sms/receive/list?subAccount=referencia_subconta

La solicitud de búsqueda (search request) retornara cada MO recibido en un determinado periodo de tiempo. Usted necesita definir los parámetros START y END para especificar un periodo de tiempo, deberá ser utilizado el formato ISO-8601. START es definido 5 días antes de la fecha actual y END es definido en la fecha actual. No es posible recuperar MOs anteriores a 5 días.

Como um usuario regular, para recuperar todos los MOs de una subcuenta use:

GET https://api-messaging.movile.com/v1/sms/receive/search

Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:

GET https://api-messaging.movile.com/v1/sms/receive/search

Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:

GET https://api-messaging.movile.com/v1/sms/receive/search?subAccount=referencia_subconta

Busqueda com START e END definidos:

GET https://api-messaging.movile.com/v1/sms/receive/search?start=2016-09-12T00:00:00&end=2016-09-15T00:00:00

Solamente con START especificado (utilizando END estandar, fecha actual)

GET https://api-messaging.movile.com/v1/sms/receive/search?start=2016-09-12T00:00:00

Solamente con END especificado (utilizando START standar, 5 dias antes de la fecha atual)

GET https://api-messaging.movile.com/v1/sms/receive/search?end=2016-09-15T00:00:00

Usado valores estandar para START y END especificando subconta

GET https://api-messaging.movile.com/v1/sms/receive/search?subAccount=iFoodMarketing

Códigos de Estatus de Envió

Existen dos niveles de estatus, que son enviados independientemente.

1 - Primer estatus (sent_status - Estatus de envió = Callback)

Estatus de entrega en la operadora, este es el primer estatus que retornamos, y todas las operadoras poseen.

Código Mensaje Significado
2 SENT_SUCCESS Entregado en la operadora con éxito (Este es un estatus que debe ser considerado para efecto de cobro.)
101 EXPIRED Expirado antes de ser entregado al aparato.
102 CARRIER_COMMUNICATION_ERROR Error de comunicación con la operadora.
103 REJECTED_BY_CARRIER Operadora rechazo el mensaje.
201 NO_CREDIT El limite de mensajes configurado por el administrador de su empresa, para su cuenta o sub cuenta fue exedido. O, en el caso que su empresa utilice el modelo pre-pago de creditos, este credito acabo.
202 INVALID_DESTINATION_NUMBER El numero de destino es invalido (No es un numero de celular valido).
203 BLACKLISTED El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa.
204 DESTINATION_BLOCKED_BY_OPTOUT El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing).
205 DESTINATION_MESSAGE_LIMIT_REACHED El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras.
207 INVALID_MESSAGE_TEXT El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas.
301 INTERNAL_ERROR Ocurrio un error en la plataforma de Movile.

2 - Segundo estatus (delivered_status - Delivery Report Callback)

Estatus de entrega en el aparato, este es el segundo estatus que retornamos y solo existe para los casos en que el primer estatus de arriba fue de éxito, o sea, el mensaje fue entregado en la operadora con éxito. En este estatus informamos si el mensaje fue o no entregado en el aparato. Algunas operadoras no poseen este segundo nivel de estatus, para estas operadoras, lo máximo de información que existe es el primer estatus o sea, si la operadora acepto el mensaje o no.

Código Mensaje Significado
4 DELIVERED_SUCCESS Entregado en el aparato con éxito.
104 NOT_DELIVERED La operadora acepto el mensaje, pero no consiguió entregarlo en el aparato. Posibles causas:
Aparato apagado o fuera del área de servicio por tiempo determinado (normalmente 24 horas, pero para algunas operadoras, este tiempo de tentativa es de 8 horas).
Número válido, pero inactivo (algunas operadoras retornan este tipo de error solamente en este segundo nivel de estatus).

API SMPP

Todos los servicios provistos por el Grupo Movile deben obligatoriamente ser encriptados, y el protocolo SMPP no posee encriptacion nativa. En este caso disponibilizamos dos alternativas para integración

Opción 1 - SMPP over TLS + IP whitelist (Opción recomendada)

Esta es la opción que recomendamos. En el caso que su sistema no tenga esta funcionalidad, clique AQUI para obtener ayuda en la configuracion de un proxy TLS.

Mas allá de la encriptacion que será realizada por TLS, el acceso será autorizado solamente para la IP publica de su servidor. (Aceptamos múltiples IPs e rangos) Esta información debe ser enviada para el e-mail support.messaging@movile.com.

En el caso que sea necesaria la liberación de salida de trafico en su firewall, recomendamos que sea liberado cualquier IP de destino en la puerta 2444. Si esto no es posible, se deberán incluir las siguientes reglas de liberación:


200.219.220.8:2444
200.219.220.193:2444
200.189.169.8:2444
189.36.59.86:2444

Opcion 2 - SMPP over VPN

La encriptacion y la liberación de acceso sera realizada vía VPN.

En el caso que elija esta opción, configure las VPNs utilizando los siguientes peers y hosts con las propuestas de fase 1 y 2 que desea. Llene y envié el formulario de VPN de su empresa para support.messaging@movile.com.

peer 200.155.0.250
hosts 200.219.220.8 and 200.219.220.193
port 2443

peer 200.143.57.150
hosts 200.189.169.8 and 189.36.59.86
port 2443

Obs: Por razones de alta disponibilidad y balanceamiento de carga, es obligatorio el establecimiento de las 2 VPNs definidas arriba.

Detalles de conexión

Información Detalles
Hostname / IP Address smpp-messaging.movile.com
Al configurar su sistema SMPP, es obligatorio utilizar el dominio como destino, y no las IPs.
Este dominio posee 4 proxys de entrada con round robin DNS y health check, y múltiples servidores backend. Basado en el volumen de mensajes que su empresa traficara, vamos a aumentar el numero de binds (conexiones) permitidas simultáneamente.
Puerta 2444 (SMPP over TLS) o 2443 (VPN)
Version SMPP 3.4
Numero de binds Mínimo 4. Establecer por lo menos 4 binds es mandatario para obtener alta-disponibilidad y balanceamiento de carga.
Codificación de los caracteres GSM7 - Default (data_coding = 0) (GSM3.38 extended table is not supported by carriers.)
LATIN1 (data_coding = 1)
UCS2 (data_coding=8).
Atención: Verifique AQUI detalles de caracteres y cobranzas.
Flash SMS Soporta
data_coding=0x10 para GSM7 y data_coding 0x18 para UCS2
Cuando recibamos un flashSMS de nuestro cliente, el mismo sera enviado a la operadora como flashSMS, en el caso que la operadora no acepte flashSMS, este será entregado como un SMS regular.
Enquire-link Minimo: 30 segundos / Máximo: 59 segundos.
Concatenación UDH de 8 bits y 16 bits son compatibles / UDH Headers
Default addr_ton 1
Default addr_npi 1
window size 10
System IDs SystemIDs can NOT contain the underscore _ character
Passwords De acuerdo con la especificación del protocolo versión 3.4, no puede contener mas que 8 caracteres.
2way Soportado
SMPP bind type Transceiver(Recomendado). Binds transmit/receiver separados también son aceptados.
SMPP system_type MovileSMSC
SMPP source addr (senderID) Cuando su servicio necesite respuestas de usuarios (MO), el source addres debe ser igual al system_id, o sea, el nombre de usuario. Cuando el servicio no necesita de MOs usted puede utilizar cualquier cosa en este campo.
Max flujo de MO 80 por bind
Max flujo de MT 80 por bind
Server Timezone UTC
Formato de ID UUID
Default validity_period 24 hours

Estatus de envio (Callback e DLR)

1 - Primer estatus (sent_status - Estatus de envio = Callback)

Estatus de entrega en la operadora, este es el primeir estatus que retornamos, y todas las operadoras poseen.

stat err TLV (0x1403) TLV (0x1404) Significado
ACCEPTD 000 2 SENT_SUCCESS Entregado en la operadora con éxito. (Este es un estatus que debe ser considerado para efecto de cobro.)
EXPIRED 101 101 EXPIRED Expirado antes de ser entregado al aparato.
REJECTD 102 102 CARRIER_COMMUNICATION_ERROR Error de comunicación con la operadora.
REJECTD 103 103 REJECTED_BY_CARRIER Operadora rechazo el mensaje.
REJECTD 201 201 NO_CREDIT El limite de mensajes configurado por el administrador de su empresa, para su cuenta o sub cuenta fue exedido. O, en el caso que su empresa utilice el modelo pre-pago de creditos, este credito acabo.
REJECTD 202 202 INVALID_DESTINATION_NUMBER El numero de destino es invalido (No es un numero de celular valido).
REJECTD 203 203 BLACKLISTED El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa.
REJECTD 204 204 DESTINATION_BLOCKED_BY_OPTOUT El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing).
REJECTD 205 205 DESTINATION_MESSAGE_LIMIT_REACHED El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras.
REJECTD 207 207 INVALID_MESSAGE_TEXT El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas.
REJECTD 301 301 INTERNAL_ERROR Ocurrio un error en la plataforma de Movile.
UNKNOWN 301 301 INTERNAL_ERROR Ocurrio un error en la plataforma de Movile.

2 - Segundo estatus (delivered_status - Delivery Report Callback)

Estatus de entrega en el aparato, este es el segundo estatus que retornamos y solo existe para los casos en que el primer estatus de arriba fue de éxito, o sea, el mensaje fue entregado en la operadora con éxito. En este estatus informamos si el mensaje fue o no entregado en el aparato. Algunas operadoras no poseen este segundo nivel de estatus, para estas operadoras, lo máximo de información que existe es el primer estatus o sea, si la operadora acepto el mensaje o no.

stat err TLV (0x1403) TLV (0x1404) TLV (0x1405) TLV (0x1406) Significado
DELIVRD 000 2 SENT_SUCCESS 4 DELIVERED_SUCCESS Entregado en el aparato con éxito.
UNDELIV 104 2 SENT_SUCCESS 104 NOT_DELIVERED La operadora acepto el mensaje, pero no consiguió entregarlo en el aparato. Posibles causas:
Aparato apagado o fuera del área de servicio por tiempo determinado (normalmente 24 horas, pero para algunas operadoras, este tiempo de tentativa es de 8 horas).
Número válido, pero inactivo (algunas operadoras retornan este tipo de error solamente en este segundo nivel de estatus).

Proxy TLS - Linux

El proxy es necesario en el caso que la conexión no sea vía VPN. Como fue explicado anteriormente, el protocolo SMPP no posee encriptacion TLS nativa, en este caso indicamos el siguiente proxy:

HAProxy

Configuración haproxy

global
    #    local2.*                       /var/log/haproxy.log
    log         127.0.0.1 local2

    chroot      /var/lib/haproxy
    pidfile     /var/run/haproxy.pid
    ssl-server-verify       none
    maxconn     4000
    user        haproxy
    group       haproxy
    daemon
    # turn on stats unix socket
    stats socket /var/lib/haproxy/stats

resolvers dns
    nameserver google 8.8.8.8:53
    hold valid 1s

defaults
    log                     global
    option                  redispatch
    retries                 3
    timeout http-request    10s
    timeout queue           1m
    timeout connect         10s
    timeout client          1m
    timeout server          1m
    timeout http-keep-alive 10s
    timeout check           10s
    maxconn                 3000

frontend movile
  bind *:2444
  mode tcp
  option tcplog
  use_backend movile

backend movile
    mode tcp
    server smpp-messaging.movile.com smpp-messaging.movile.com:2444 ssl resolvers dns check inter 15000

$sudo yum install -y openssl-devel haproxy

$sudo apt-get install -y openssl-devel haproxy

IMPORTANTE: Configure su sistema (cliente SMPP) para utilizar como direccion de destino 127.0.0.1:2444

Proxy TLS - Windows

configuracion nginx

worker_processes  2;

events {
    worker_connections  1024;
}

stream {
  resolver 8.8.8.8 valid=1s;
  map $remote_addr $backend {
    default smpp-messaging.movile.com;
  }
  server {
    listen 2444;
    proxy_pass $backend:2444;
    proxy_ssl  on;
  }
}

Es posible utilizar nginx como proxy TLS en servidores windows para realizar la encriptacion de los dados

Descargue la versión abajo (importante utilizar esta versión porque las versiones antiguas resuelven el nombre apenas en el primer request)

http://nginx.org/download/nginx-1.12.1.zip

Extraiga el archivo .zip en la carpeta deseada y sustituya el contenido del archivo conf/nginx.conf con los datos al lado.

API SFTP

Detalles de conexión

Hostname ftp-messaging.movile.com
Puerta 2222
Protocolo SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor)
Autenticación username + senha (provisto por soporte)
Portal messaging.movile.com

Envio de mensajes via SFTP

Para realizar el disparo de mensajes vía SFTP es necesario generar un archivo en formato TXT, el formato debe seguir el siguiente ejemplo:

numero;texto;correlationId(opcional);
5511900000000;mensaje 1;;
5519900000000;mensaje 2;;
5521900000000;mensaje 3;;
EOF

El nombre del archivo a ser enviado debe seguir el siguiente formato:

<ID_SUBCONTA>.<DATA(YYYYMMDD)>.<SEQUENCIA> ou <NOME_DE_REFERÊNCIA_SUBCONTA>.<DATA(YYYYMMDD)>.<SEQUENCIA>

Las sub cuentas (projectos) pueden ser creadas por el propio cliente en el portal. En el caso que no sea seguida la nomenclatura arriba, el envío será realizado por la sub cuenta default del cliente.

Ejemplo:

3486.20170101.01.txt ou PROJETO1.20170101.01.txt

Después deberá ser realizado el envió del archivo para el servidor sftp en el directorio upload. El archivo será movido para el directorio success después de procesado, en el caso que aparezca un error el archivo será movido para el directorio error.

API Validación de números

Esta API permite realizar consultas en lote de números retornando la operadora a la que esos números pertenecen y consecuentemente los números inválidos (si un número no pertenece a ninguna operadora por lo tanto es inválido). Ella utiliza el protocolo HTTP con TLS y el metodo POST con parámetros en JSON. La consulta permite saber si determinado número pertenece a la operadora pero no es posible verificar si este número se encuentra activo.

Autenticacion

Para efectuar envíos y consultas en nuestra API es necesaria la autenticacion por medio de usuario o e-mail, en conjunto con un token.

Campo Detalles Data Type
UserName Su usuario o email String
AuthenticationToken Su token de autenticacion. Verifique aqui y lea las descripciones de usuarios abajo. String

Detalles de conexión

Hostname api-messaging.movile.com
APIs Consulta en lote /v1/carrier/lookup
Puerta 443 (https)
Protocolo HTTPS (encriptacion TLS)
Autenticacion username + token
Portal messaging.movile.com

Requisicion HTTP Method POST

curl --request POST \
  --url https://api-messaging.movile.com/v1/carrier/lookup \
  --header 'authenticationtoken: <authenticationtoken>' \
  --header 'username: <username>' \
  --header 'Content-Type: application/json' \
  --data '{
    "destinations": ["+55(19)997712322", "5519997712322", "2312312"]
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/carrier/lookup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n\t\"destinations\": [\"+55(19)997712322\", \"5519997712322\", \"2312312\"]\n}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "authenticationtoken: <authenticationtoken>",
    "username: <username>"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/carrier/lookup")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["authenticationtoken"] = '<authenticationtoken>'
request["username"] = '<username>'
request["Content-Type"] = 'application/json',
request.body = "{\n\t\"destinations\": [\"+55(19)997712322\", \"5519997712322\", \"2312312\"]\n}"

response = http.request(request)
puts response.read_body


import requests

url = "https://api-messaging.movile.com/v1/carrier/lookup"

payload = "{\n\t\"destinations\": [\"+55(19)997712322\", \"5519997712322\", \"2312312\"]\n}"
headers = {
    'Content-Type: application/json',
    'authenticationtoken': "<authenticationtoken>",
    'username': "<username>"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)


POST https://api-messaging.movile.com/v1/carrier/lookup Content-Type: application/json

Para realizar la consulta basta adicionar en el body de la requisicion un json con el array de números. Es posible hacer la consulta utilizando los formatos +55(19)999999999 y 5519999999999

Respuesta a la consulta

Respuesta a la llamada en formato JSON

{
    "id": "aadb5130-7dd7-11e7-baac-a6aabe61edb5",
    "destinations": [
        {
            "destination": "5519997712322",
            "active": true,
            "carrier": {
                "name": "VIVO",
                "countryCode": "BR"
            }
        },
        {
            "destination": "5519997712322",
            "active": true,
            "carrier": {
                "name": "VIVO",
                "countryCode": "BR"
            }
        },
        {
            "destination": "2312312",
            "active": false,
            "carrier": {
                "name": "UNKNOWN"
            }
        }
    ]
}

El ultimo numero de ejemplo se trata de un numero invalido para demostrar como la consulta retorna el JSON en este caso.

La respuesta de la consulta en lote contendrá un archivo JSON con las informaciones individuales sobre cada número consultado:

Campo Detalles Tipo
id UUID generado para este lote String
destinations Este campo es un array con las respuestas de las consultas individuales del lote, contiene el id y el correlationId de cada número consultado IndividualResponse[]
destination Número de telefono consultado Long
active status del numero en la operadora (actualmente verifica apenas si el número pertenece a la operadora, no activo / en uso) Boolean
carrier Operadora y país a la cual pertenece el número consultado array[]
name Nombre de la operadora String
countryCode Codigo de País String

Acentos y caracteres especiales

Mensajes que poseen solamente caracteres que están en la siguiente tabla, son cobrados cada 160 caracteres. En el caso que el mensaje tenga uno o mas caracteres que no están en la tabla el cobro sera realizado cada 70 caracteres, conforme la especificación del protocolo en la red de las operadoras.

Space ( 0 8 @ H P X ` h p x
! ) 1 9 A I Q Y a i q y
* 2 : B J R Z b j r z
# + 3 ; C K S [ c k s {
$ , 4 < D L T \ d l t
% - 5 = E M U ] e m u }
& . 6 > F N V ^ f n v ~
/ 7 ? G O W _ g o w

Observaciones:

1 - La habilitación del uso de acentos y caracteres especiales debe ser solicitada al suporte.

2 - En el caso que la operadora destino no acepte acentos y caracteres, nuestra plataforma realiza automáticamente para nuestros clientes, la substitución de los mismos, por ejemplo: á para a, é para e, etc.

Textos grandes (concatenación)

A pesar que el protocolo utilizado en la red de las operadoras tenga limite de 70 o 160 caracteres, para mensajes con o sin caracteres especiales respectivamente, es posible enviar mensajes grandes con la utilización de concatenación, donde los mensajes son reagrupados por los aparatos al recibirlos.

Clientes integrados vía HTTPS, SFTP, o MQ, no existe ningún indicador adicional para activar la concatenación, basta solo enviar el texto del mensaje grande entero de una sola vez.

Clientes integrados vía SMPP, deben utilizar la funcionalidad de concatenación con indicadores en el header (UDH), LINK

Es importante notar que, a pesar de aparecer en el aparato como un único mensaje grande, los mensajes continúan traficando en la red de operadora individualmente, en este caso, continúan siendo cobrados individualmente cada 70 o 160 (dependiendo de los caracteres utilizados). Recordando que al utilizar concatenación parte de los caracteres (70 o 160) son utilizados por el encabezado.

Observación: En los casos de operadoras que no soportan la funcionalidad de concatenación, Movile enviá los mensajes separadamente, sin concatenar incluyendo automáticamente para nuestros clientes, indicadores de orden,

Ex:

Inicio do texto…. (½)

……fin do texto (2/2)

Soporte

Apertura de llamados Enviar un email para support.messaging@movile.com
Telefono +55 (11) 3230-3260