REST v1

Resumen

El API REST de Modica le permite programar y / o enviar inmediatamente mensajes a un solo teléfono, o transmitir a múltiples teléfonos.

El uso de HTTPS es obligatorio, todos los intentos de usar HTTP de texto sin formato se redirigirán a HTTPS. Los datos de solicitud y respuesta requieren codificación JSON. Solo se utilizan los métodos HTTP GET y POST.

Autenticación

La autenticación básica HTTP se utiliza para todas las solicitudes. Si accede a la API sin tener las credenciales correctas O permiso para acceder a la API, obtendrá una respuesta HTTP 401.

Las credenciales de su aplicación de gateway (’nombre de aplicación’ y contraseña) están disponibles en Omni: https://omni.modicagroup.com/gateway/api_config/rest.

Necesitará un nombre de usuario y contraseña de OMNI para recuperarlos.

Si no tiene estos detalles, por favor contacte a support@modicagroup.com.

URI Base

Todo el acceso al API es a través de HTTPS, y se accede desde: <https://api.modicagroup.com/rest/gateway

Versiones

La versión de la API REST es actualmente v1. Se utiliza un tipo de medio personalizado para que los consumidores elijan el formato de datos que desean recibir:

Accept: application/vnd.modica.gateway.v1+json

Especificación OpenAPI

La especificación OpenAPI (Swagger) se puede encontrar aquí: aquí.

Puedes ver ejemplos de código y más información. aquí.

Códigos de Error

Pueden ocurrir los siguientes errores:

Enviando Mensajes

Es posible enviar a un solo destino o transmitir un conjunto de contenido a múltiples destinos:

Enviando a un solo destino

Para enviar un mensaje MT (saliente) a un solo destino, envíe una solicitud POST:

POST /messages

{
  "destination": str:mobile-number,
  "content": str:text-message
}

Atributos opcionales:

{
  "scheduled": str: 2017-05-05T10:00:00+12:00,
  "source": str:short-code,
  "reference": str:alt-reference,
  "class": str:application-class,
  "mask": str:source-mask,
  "sms_class": int:0-3
}

Cuando se envía correctamente:

HTTP/1.1 201 Created
Location: https://api.modicagroup.com/rest/gateway/messages/int:message-id

[int64:message-id]

Cuando hay error de validación:

HTTP/1.1 400 Bad Request

{
  "error": str:error-code,
  "error-desc": [str:error-desc]
}

Envío a Múltiples Destinos

Para transmitir un mensaje común a varios dispositivos, envíe la siguiente solicitud POST:

POST /messages/broadcast

{
  "destination": [str:mobile-number-1, str:mobile-number-2],
  "content": str:text-message
}

Optional attributes:

{
  "scheduled": str: 2017-05-05T10:00:00+12:00,
  "source": str:short-code,
  "reference": str:alt-reference,
  "class": str:application-class,
  "mask": str:source-mask,
  "sms_class": int:0-3
}

Cuando el mensaje se envía correctamente:

HTTP/1.1 201 Created
Content-Type: application/json

[
  {
    "status": "success",
    "message": null,
    "destination": str:mobile-number,
    "id": int64:message-id
  }
]

Cuando existe un error de validación:

HTTP/1.1 400 Bad Request

{
  "error": str:error-code
  "error-desc": [str:error-desc]
}

{
  "error-desc": "Invalid scheduled timestamp (must be less than 60 days)",
  "error": "invalid_attrib"
}

Ejemplo que muestra una respuesta mixta de destinos exitosos y fallidos:

HTTP/1.1 201 Created
Content-Type: application/json
[
 {
   "status": "success",
   "message": null,
   "destination": str:mobile-number,
   "id": int64:message-id
 },
 {
   "status": "failure",
   "message": "Invalid destination (X)",
   "destination": "X",
   "id": null
 },
 {
   "status": "failure",
   "message": str:failure-reason,
   "destination": str:mobile-number,
   "id": null
 }
]

Buscar un Mensaje SMS

Para buscar un mensaje envíe una solicitud GET :

GET /messages/id

Si se encuentra una coincidencia:

HTTP/1.1 200 OK
Location: https://api.modicagroup.com/rest/gateway/messages/int:message-id

{
  "id": str:message-id,
  "source": str:mobile-number|short-code,
  "destination": str:mobile-number|short-code,
  "content": str:text-message
}

Se agregan atributos adicionales si están disponibles:

{
  "reference": str:alt-reference,
  "reply-to": str:message-id,
  "operator": str:operator-name
}

Si no se encuentra:

HTTP/1.1 404 Not Found

Respuestas MO

Solo recibirá mensajes de MO si ha proporcionado una URL de respuesta MO en Omni. Puede establecer la URL de respuesta en la página de la aplicación / gateway móvil (API) en omni.modicagroup.com .

Recomendamos el uso de https: // para sus URL de respuesta.

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

Cuando se recibe un mensaje MO, se realiza una solicitud POST a la URL de respuesta MO, esta respuesta incluirá el detalle del mensaje MO como un objeto JSON en el cuerpo de la solicitud POST.

POST callback-url
Location: https://api.modicagroup.com/rest/gateway/messages/int:message-id
{
  "id": int:message-id,
  "source": str:mobile-number,
  "destination": str:short-code,
  "content": str:text-message,
  "operator": str:operator-name
}

En el caso de que el mensaje sea una respuesta a un mensaje MT, se agrega un atributo “responder a” adicional (solo cuando se usa una secuencia de números, y el MO es en respuesta a un mensaje MT):

{
  "reply-to": str:message-id
}

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

{
  "encoding": str:encoding-type
}

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 normales con GSM de 7 bits o contenido Unicode no suministrarán este parámetro.

Mensajes DLR

Solo recibirá mensajes de estado de DLR si ha proporcionado una URL de estado de DLR en Omni. Puede establecer la URL de respuesta en la página de la aplicación / gateway móvil (API) en omni.modicagroup.com .

Recomendamos el uso de https: // para sus URL de respuestas.

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

Cuando se recibe un mensaje DLR en sus servicios, se realiza una solicitud POST a la URL de respuesta DLR, esta respuesta incluirá en detalle el estado DLR como un objeto JSON en el cuerpo de la solicitud POST.

POST callback-url

{
  "message_id": str:message-id,
  "status": str:dlr-status
}

En el caso de que el mensaje MT contenga una referencia, se agrega un atributo de “referencia” adicional:

{
  "reference": str:alt-reference
}

Estado del mensaje DLR

Los siguientes son los códigos de estado devueltos en los DLR que admite nuestra puerta de enlace de mensajes.

Estado del mensaje Omni

Los siguientes son los códigos de estado visibles en los informes Omni que admite nuestro portal de mensajes; no todos los operadores los admitirán todos.

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.