La plataforma permite realizar envíos masivos de mensajería a los clientes registrados en ella, para ello existen dos protocolos que pueden ser utilizados para realizar la conexión. A continuación, se detalla la función dichos servicios.
1.1. Conexión HTTP
El servicio web proporcionado atiende una solicitud POST del protocolo HTTP, el cual recibe cadenas JSON y devuelve un resultado en el mismo formato.
A continuación, se muestra la información necesaria para realizar la conexión del servicio.
DOMINIO: | |
URL: | |
METHOD: | POST |
HEADERS: | Content-Type: application/json Authorization: [token] |
BODY: | { "apiKey": [numeric][required], "carrier": [string][optional], "country": [string][required], "dial": [numeric][optional], "message": [String][required], "msisdns": [String[]][required], "tag": [String][required], "mask": [String][optional], "msgClass": [numeric][optional], "dataCoding":[String][optional], "schedule":[String][optional][format: ISO-8601], “dlr”:[Boolean][optional], “optionals”:[String][optional] } |
Parámetros | ||||||||||||||
dominio | Es la ruta en dónde se encontrará alojado el servicio, esta información será proporcionada por Concepto Móvil. | Obligatorio | ||||||||||||
Authorization | Es un “token” privado que será proporcionado por Concepto Móvil y será utilizado como llave para poder realizer la conexión. | Obligatorio | ||||||||||||
apiKey | Identificador del cliente proporcionado por Concepto Móvil. Es único para cada cliente. | Obligatorio | ||||||||||||
| carrier | Nombre del operador al que pertenece el MSISDN al que se le enviará el mensaje. Las posibles opciones a enviar son:
| Opcional | ||||||||||||
| country | Identificador del país (ISO2) dos caracteres en mayúsculas. | Obligatorio | ||||||||||||
| dial | Número de marcación que se utilizará para enviar el mensaje. | Obligatorio | ||||||||||||
| message | Texto a enviar (160 Caracteres). Si se envía un texto de más de 160 caracteres la plataforma concatenará estos mensajes en múltiplos de 153 caracteres. Debe utilizar caracteres soportados por la codificación GSM7 cualquier carácter que no corresponda a esta codificación puede ocasionar que el mensaje no se muestre de forma adecuada. | Obligatorio | ||||||||||||
| msisdns | Número con 10 dígitos más lada, al que se le enviará el mensaje, debe ser ingresado ente corchetes. | Obligatorio | ||||||||||||
| tag | Texto que sirve para identificar la petición. Abierta para que se envié la cadena deseada por el usuario, se sugiere enviar el nombre de la campaña. | Obligatorio | ||||||||||||
| mask | Texto de la máscara con la que se desea que llegue el mensaje. Para cuando se requiera enmascaramiento, se debe tener acordado previamente la posibilidad de usar esta funcionalidad. | Opcional | ||||||||||||
| msgClass | Valor que indica si será mensaje normal o mensaje flash Normal 0 y Flash 1). Si no se incluye este atributo se tomará como si fuera cero. | Opcional | ||||||||||||
| dataCoding |
| Opcional | ||||||||||||
| dlr | Valor que indica si es requerida la notificación DeliveryReceipt para entregarse hacia una url proporcionada por el cliente. Si se especifica como verdadero, se requiere el dato “registeredDelivery”. | Opcional | ||||||||||||
| optionals | Valor en el cual se asignan variables especificas según se requiera en formato json {“propiedad”:”valor”}
| Opcional | ||||||||||||
1.1.1. Códigos de respuesta
La respuesta entregada por el servicio es una cadena JSON la cual cambiará de acuerdo al tipo de respuesta, para una respuesta exitosa se mostrará cómo sigue:
Respuesta exitosa | ||
Ejemplo de cuerpo de la respuesta | { "code":0, "mailingId":5000384, "result":"Applied” } | |
code | Código de resultado, para el exitoso siempre será cero. | 0 |
mailingId | Número que indica la solicitud que fue registrada | 5000384 |
result | Indica el resultado de la solicitud, para el caso exitoso será siempre Applied. Con este dato se determina si la solicitud fue registrada correctamente y así estará en espera de ser atendida. | Applied |
Cuando existe algún problema al procesar la solicitud, la cadena JSON sufrirá algunos cambios, a continuación se muestra la cadena que se recibirá.
Respuesta errónea | ||
Ejemplo de cuerpo de la respuesta | { "code":-17, "hint":"The country abbreviation or the carrier does not exist", "message":"Validation error" } | |
code | Código de resultado, de acuerdo al valor indica el tipo de error ocurrido. | -17 |
hint | Describe el tipo de error ocurrido | The country abbreviation or the carrier does not exist |
message | Identifica, con un nombre, el error ocurrido. | Validation error |
1.1.2. Códigos de error
A continuación se muestra el catálogo de errores que puede regresar la plataforma.
| Código (errorCode) | Identificador de tipo (message) | Mensaje (hint) |
|---|---|---|
| -10 | Validation error | The message is too long, verify the length and try again |
| -11 | Validation error | The message cannot be empty and cannot contain invalid characters, verify the info and try again |
| -20 | Bad authentication | The client was not found in the system, verify the api key and authorization header and try again |
| -21 | Bad authentication | Access denied, verify your credentials and try again |
| -40 | Validation error | The carrier and/or country were not correct, verify the info and try again |
| -46 | Validation error | The dial is not asociated to your account, verify the info and try again |
| -55 | Validation error | The account has not profiling enabled, send the correct carrier and try again |
| -60 | Validation error | The account can not use mask, verify the info and try again |
| -62 | Validation error | The mask and dial are not associed to the account for this carrier, verify the info and try again |
| -71 | Validation error | Invalid Carrier, verify the info and try again |
| -73 | Validation error | Incorrect request, verify the info and try again |
| -75 | Validation error | Incorrect msisdn structure, verify the info and try again |
| -77 | Validation error | Data encoding not supported, verify the info and try again. |
| -79 | Validation error | Bad request, verify the info and try again |
| -80 | Validation error | Incorrect tag structure, verify the info and try again |
| -109 | Validation error | Balance limit reached |