HTTPS API

Resumen

Esta página describe los recursos que conforman el API HTTPS v2 de Mobile Gateway, para los desarrolladores que desean integrar un Gateway SMS en su aplicación.

El API HTTPS de Mobile Gateway brinda acceso para enviar mensajes a los teléfonos. Para usar el API de HTTPS, su aplicación realizará una solicitud de HTTPS y analizará la respuesta. El formato de respuesta es en texto plano. Utilizará las solicitudes HTTP GET a través de TLS (https).

Autenticación

Toda la autenticación se realiza utilizando parámetros dentro de la solicitud GET de HTTPS. Si no proporciona las credenciales correctas en el URI al acceder a el API, obtendrá una respuesta HTTP 401 (HTTP 500 en la versión 1) con el texto " ERROR Invalid authentication information" in the body.

Puede cambiar su contraseña y buscar los valores de autenticación en https://omni.modicagroup.com/gateway/api_config/http. Si no puede acceder a este o tiene otros problemas, póngase en contacto con support@modicagroup.com.

Configuración de URI Base y Firewall

Todo el acceso al API es via HTTPS y se puede accede desde:

https://api.modicagroup.com/message

Si necesita agregar filtros de firewall, le recomendamos que permita la subred IP completa 202.160.117.0/28. No use 202.160.112.0/21 ya que usamos esta subred para una amplia gama de tráfico.

Versiones

La versión del API HTTPS es actualmente v2. La única diferencia entre v1 y v2 es que v2 proporciona nuevos códigos de respuesta HTTP. Recomendamos que los clientes utilicen el API REST si necesita una API más avanzada.

Códigos de Error

La respuesta HTTP con errores que el gateway devuelve, dependerá de la versión de API que solicite. Pueden ocurrir los siguientes errores:

Code	Descripcion	v1 Response code	v2 Response code
`Invalid authentication information`	Los parámetros de aplicación o contraseña faltan o son incorrectos	500	401
`Missing <parameter name> parameter`	Falta el parámetro nombrado o el gateway no puede identificarlo	500	400
`Failed to queue message`	El gateway no pudo crear el mensaje. La causa más probable de esto es que el número de destino no era válido o la red móvil para ese número no se ha configurado en su cuenta.	500	400
`<message id>`	El mensaje fue enviado exitosamente.	200	200

Enviando un Mensaje SMS

Para enviar un mensaje de MT a un teléfono móvil, envíe una solicitud GET:

GET /message?application=exampleapplication&password=examplepassword&customer=examplecustomer&class=exampleclass&content=example+content&destination=%2b642100000
Host: api.modicagroup.com

Los parámetros en negrita son obligatorios, los parámetros en cursiva son opcionales.

Parametro	Descripcion
application	El nombre de la aplicación provisto por Modica.
password	La contraseña para la aplicación nombrada provista por Modica.
class	Le permite definir el tipo de mensaje. Las clases se utilizan para determinar cómo enrutar y facturar el mensaje, así como para proporcionar información útil para la presentación de informes. Modica le proporcionará un conjunto de clases válidas disponibles para su cuenta. En la mayoría de los casos, esto debería ser mt_message. Si se usa el parámetro source, la clase no debe ser incluida.
content	El texto que se enviará textualmente al teléfono móvil.
destination	El número de teléfono móvil al que se enviará el mensaje. El formato del número debe ser internacional, por ejemplo. +180912348567 / +19541234567 / +18123456789. El formato internacional generalmente significa eliminar el cero inicial (de los números locales) y reemplazarlo con el código del país precedido por un signo más (+). El signo más + deberá codificarse correctamente en la llamada a la API: por ejemplo, source =% 2B18092345678
source	Le permite seleccionar el código corto o el número de teléfono móvil por el que envía, y en el que tiene múltiples disponibles. Este parámetro es opcional, pero cuando se usa debe usarse en lugar del parámetro de clase.
version	Si se establece en 2, el gateway proporcionará mejores códigos de respuesta HTTP. El valor predeterminado es 1.
reference	Campo de texto de forma libre para su referencia que puede ayudar en la presentación de informes. Este campo es opcional y puede contener hasta 50 caracteres. Si se proporcionaron, los mensajes de respuesta de estado posteriores para su mensaje incluirán estos datos.
mask	Si tiene el requisito de que su mensaje SMS parezca provenir de algo distinto al MSISDN o el código corto con el que ha sido definido, puede usar el parámetro de máscara para configurar esto. Una máscara puede contener hasta 11 caracteres GSM 3.38. La máscara debe haberse configurado previamente en [https://omni.modicagroup.com/gateway/api_config/http](https://[{< domainName >}}/gateway/api_config/http) . Si usa una máscara que no está configurada en la lista de máscaras disponibles, la máscara se ignorará y el mensaje llegará desde la dirección de origen de la aplicación. Las máscaras distinguen entre mayúsculas y minúsculas.

infoNota Importante: Asegúrese de que todos los valores de los parámetros estén codificados correctamente en la URL. Para obtener más información, visite https://www.w3schools.com/tags/ref_urlencode.asp

Cuando funciona correctamente:

HTTP/1.1 200 OK

<message-id>

Todos los ID de mensajes se devolverán como enteros firmados de 64 bits.

Cuando existe un error:

HTTP/1.1 500

ERROR <error description>

Respuesta MO

Si se ha proporcionado una URL de respuestas MO en: https://omni.modicagroup.com/gateway/api_config/http, los mensajes recibidos a su código corto se enviarán a su URL.

Recomendamos utilizar https:// para sus URL dónde se enviará la respuesta.

NOTA: El certificado de seguridad debe coincidir con el nombre de dominio que se está utilizando, los certificados auto firmados no se verificarán y generarán errores.

Si proporcionó una URL de devolución de llamada de MO de: https://your-server.example.com/receiveMessage , recibirá una solicitud GET como:

GET https://yourserver.com/receiveMessage?id=12345&source=%2B642741234567&destination=4433&content=160+character+sms+message+content+here&operator=Telecom_NZ HTTP/1.1
Host: your-server.example.com

La solicitud contendrá los siguientes parámetros GET:

Parámetro	Descripción
id	El ID del mensaje
source	El número de teléfono o código corto del remitente (incluidos el código inicial y el código de país)
destination	El código corto o MSISDN
content	El contenido del mensaje
reply_to	El ID del mensaje al que responde este mensaje (solo cuando se usa una secuencia de números, y el MO responde a un mensaje MT)
operator	El nombre del operador (operador de telefonía móvil) desde el que se envió el mensaje

Si el mensaje del teléfono contiene contenido binario, se proporcionará un parámetro adicional:

Parámetro	Descripción
encoding	El valor “base64” se suministrará para mensajes que contengan datos binarios. El contenido se suministrará codificado con base64, se necesita descifrar el contenido para obtener los datos originales. NOTA: los mensajes SMS regulares con GSM de 7 bits o contenido Unicode no suministrarán este parámetro.

infoLos parámetros de query-string que se muestran se adjuntan automáticamente a su URL suministrada. No es necesario proporcionar ningún parámetro de cadena de consulta.

Mensajes DLR

Si se ha proporcionado una URL para los DLR en: https://omni.modicagroup.com/gateway/api_config/http, se enviarán DLR o recibos de entrega a su URL. Recomendamos usar https:// como URL para los DLR.

NOTA: El certificado de seguridad debe coincidir con el nombre de dominio *que se está utilizando, los certificados auto firmados no se verificarán y *generarán errores.

Si proporcionó una URL de devolución de llamada de MO de: https://your-server.example.com/receiveStatus, recibirá una solicitud GET como:

GET /receiveStatus?id=54321&status=received HTTP/1.1
Host: your-server.example.com

Parámetro	Descripción
id	El ID del mensaje
status	El texto de estado del mensaje

Si se proporcionó un campo de referencia al crear el mensaje, aparecerá un parámetro adicional:

Parámetro	Descripción
reference	El campo de texto que se proporciona al crear el mensaje, máximo de 50 caracteres.

infoLos parámetros de query-string que se muestran se adjuntan automáticamente a su URL suministrada. No es necesario proporcionar ningún parámetro de query-string.

Los estados posibles varían entre los operadores, por ejemplo, algunos operadores marcarán un mensaje como “rechazado” cuando el número de teléfono móvil no es válido, el teléfono no tiene crédito suficiente o el mensaje ha caducado. Otros operadores diferenciarán entre cada uno de estos eventos.

Se mostrarán los siguientes estados :

Estado	Descripción
failed	La entrega del mensaje ha fallado debido a un problema de conectividad del operador
sent	Mensaje fue enviado al operador
frozen	Un error en el operador ha congelado el mensaje
dead	Eliminado por el administrador
received	El mensaje ha sido recibido por el teléfono
submitted	Mensaje enviado con éxito al operador para su entrega
rejected	El operador rechazó el mensaje

Ayuda

¿Tienes problemas para integrarte con alguno de nuestros servicios? Visite nuestro servicio de asistencia técnica en https://omni.modicagroup.com/docs/es/ o póngase en contacto con support@modicagroup.com y le ayudaremos a resolverlo.