Documentación Técnica

Transcripción

1 Especificación de HTTP(s) API Documentación Técnica Interfaz de Programación de Aplicaciones HTTP(s) Última modificación: v3.3.2 Página 1

2 Contenidos 1. Introducción Interfaz de Programación de Aplicaciones HTTP Introducción Envío de mensajes La Codificación GSM HTTP y HTTPS XML POST Formato XML para envíos masivos Formato XML para envíos masivos múltiples Respuestas del servidor a peticiones POST XML Ejemplo de petición POST XML sobre PHP HTTP y HTTPS GET Comandos adicionales de HTTP(S) GET Recolección de informes de entrega Método Pull Valores de respuestas a peticiones de envíos SMS Control de versiones Página 2

3 1. Introducción Este documento provee instrucciones a desarrolladores para integrar los servicios de mensajería SMS a varias soluciones utilizando la interfaz de programación de aplicaciones HTTP (HTTP API, por sus siglas en inglés). La HTTP API de BulkGestMailing puede ser usada para enviar mensajes SMS, recolectar informes de entrega, hacer consultas de créditos así como los países de envío. El segundo capítulo describe completamente los métodos de la HTTP API de BulkGestMailing, describe los métodos, URLs y los parámetros necesarios así como también provee ejemplos prácticos. Esta nueva versión del documento ha sido simplificada y se ha reducido a los valores más usados por los clientes, simplicando mucho a la hora de programar el software de cliente. Para recibir asistencia, escriba a soporte@gestmailing.com, soporte@bulkgm.com, o diríjase a los contactos de la web o Los siguientes métodos API están disponibles: Enviar mensajes usando HTTP(s) POST XML Enviar mensajes usando HTTP(s) GET Recolectar informes de entrega, DLR recolecta por cada SMS enviado Página 3

4 2. Interfaz de Programación de Aplicaciones HTTP 2.1. Introducción El sistema de BulkGestMailing ofrece el método POST XML o GET para enviar mensajes SMS y recoger reportes de entregas DLR vía GET. Este capítulo contiene especificaciones para los siguientes métodos: Envío de mensajes utilizando HTTP POST XML enviando un fichero al servidor. El servidor devolverá otro fichero con los datos de DLR. Muy útil cuando se requiere enviar muchos SMS de una sola vez. Enviar mensajes utilizando HTTP GET este método, similar a POST en cuanto a parámetros, permite enviar mensajes SMS poniendo parámetros directamente como una línea de variables en el navegador. Recolectar informes de entrega este método permite recolectar informes de entrega de mensajes SMS enviados utilizando tanto el método PUSH (HTTP POST a una URL de destino predefinida) o PULL (haciendo una solicitud HTTP GET a una correspondiente URL) Envío de mensajes El servicio de envío SMS, Push SMS, es un servicio mundial que engloba a más de 800 operadoras de todo el mundo. Para asegurarse que su envío de SMS llega satisfactoriamente, es decir el usuario final lo pueda leer, recuerde algunas características: Tenga en cuenta que el SMS sólo se entregará en el dispositivo principal, es decir en la tarjeta SIM principal, nunca en las secundarias, aunque posean ese mismo número La Codificación GSM La codificación que usa GSM, es un juego de caracteres reducido. En este formato, GSM 03.38, la cadena enviada puede llegar a tener 160 caracteres como máximo. Si se envían códigos diferentes, estos es, acentos, caracteres extraños etc. automáticamente el SMS se reduce a 70, ya que para codificar este tipo de caracteres se necesita más de un byte. Si se opta por el envío de caracteres extendidos, debe de usar la variable DataCoding a 1 o 2, pero le recordamos que es posible que en muchos teléfonos el SMS llegue con caracteres raros o directamente el teléfono no pueda abrirlos. Debido a este problema si su envío tiene estos caracteres extraños, nosotros cambiaremos su cadena de caracteres a su homónima en el juego reducido, es decir, y como ejemplo, si nos envía á, la cambiaremos por a. Nosotros recomendamos que antes de hacer el envío a nuestra API, cambie los caracteres a GSM 7 bit, así el envío es fiel a lo que usted nos envía. Si aun así, quiere enviarnos cadenas extendidas, póngase en contacto con nosotros para habitarlas. Actualmente nosotros no tenemos soporte para envíos de SMS concatenados. Más de 160 caracteres reportará un error de envío. Lea más información aquí: Si desea más información no dude en contactar con nosotros. Página 4

5 HTTP y HTTPS XML POST La URL utilizada para enviar mensajes utilizando HTTP POST para envíos masivos es: Punto de acceso primario: Punto de acceso secundario: Punto de acceso secundario: La URL utilizada para enviar mensajes utilizando HTTPS POST para envíos masivos con textos diferentes: Punto de acceso primario: Punto de acceso secundario: Punto de acceso https primario y secundario: Recomendamos encarecidamente usar el formato HTTPS Formato XML para envíos masivos Este formato permite el envío de un único texto a múltiples teléfonos, sin necesidad de repetirlo. La línea de formato XML debe de tener XML= al principio. El formato del fichero de XML debe de ser el siguiente: <SMS> <authentification> <user></user> <password></password> </authentification> <message> <sender></sender> <smstext></smstext> <type></type> <datacoding></datacoding> <validityperiod></validityperiod> <appid></appid> <deferred></deferred> </message> <recipients> <phone> <id> </id> <gsm> </gsm> </phone> <phone> <id> </id> <gsm> </gsm> </phone> <phone> <id> </id> <gsm> </gsm> </phone> </recipients> </SMS> Como se muestra arriba, en el formato XML, la etiqueta <phone> contiene otra etiqueta <id>, la cual permite al cliente que envía la petición, identificar por su cuenta el mensaje SMS enviado. Esta etiqueta es opcional, por lo que si no necesitan reportes de entrega se puede obviar. En cualquier caso el sistema una vez enviado el fichero por vía POST, devolverá un fichero en el que dará el contenido de la respuesta asociado a ese id. Página 5

6 Para obtener los DLR correspondientes sólo debe de hacer la petición GET correspondiente explicado en el apartado Comandos adicionales de HTTP(S) GET Parámetros del fichero XML. Los parámetros obligatorios están en azul PARÁMETRO user password sender smstext DESCRIPCIÓN Usuario Contraseña Nombre del remitente del mensaje Remitente alfanumérico: largo máximo 11 caracteres Remitente numérico: largo máximo 11 caracteres Texto del mensaje (160 caracteres máx.). Recomendamos no usar comilla simple o doble ya que algunos DLR no se recibirán. gsm Número GSM receptor en formato internacional (3461xxxxxxxx, 5521xxxxxxxx,...). No incluir el 00 inicial. id type Datacoding Validityperiod Deferred Número de serie definido por el cliente. Usado para enlazar este id con el id que devuelve la API de GestMailing. Tipo de Mensaje Flash Un mensaje Flash se muestra directamente en la pantalla del teléfono, si este lo soporta. Parámetro opcional: valor predeterminado = 1 0 Enviado como Flash 1 Al móvil (por defecto) 2 A la SIM del teléfono Parámetro de codificación de datos Parámetro opcional, valor predeterminado = 0 0: 7 bit, por defecto 1: 8 bit. 2: UCS-2 Validez del mensaje en minutos, desde que se entrega en nuestra plataforma. Un período de validez mayor 2880 minutos (48hs) no es soportado Utilizado para programar el retraso de envío de SMS (No envía el SMS en el momento sino a un horario planificado). El tiempo de retraso es en minutos, hasta 2880 minutos (48 horas), a partir de la entrega en nuestra plataforma. Página 6

7 Formato XML para envíos masivos múltiples En este formato, a diferencia del anterior, permite envíos de SMS con textos diferentes para cada teléfono. Recuerde que debe llamar al script sendsms2.php. La línea de formato XML debe de tener XML= al principio. El formato del fichero de XML debe de ser el siguiente: <SMS_MULTIPLE> <authentification> <user></user> <password></password> </authentification> <SMS> <message> <sender></sender> <smstext></smstext> <type></type> <datacoding></datacoding> <validityperiod></validityperiod> <appid></appid> <deferred></deferred> <id> </id> <gsm> </gsm> </message> <message> <sender></sender> <smstext></smstext> <type></type> <datacoding></datacoding> <validityperiod></validityperiod> <appid></appid> <deferred></deferred> <id> </id> <gsm> </gsm> </message>... </SMS> </SMS_MULTIPLE> Como se muestra arriba, en el formato XML, la etiqueta <message> contiene otra etiqueta <id>, la cual permite al cliente que envía la petición, identificar por su cuenta el mensaje SMS enviado. Esta etiqueta es opcional, por lo que si no necesitan reportes de entrega se puede obviar. En cualquier caso el sistema, una vez enviado el fichero por vía POST, devolverá un fichero en el que dará el contenido de la respuesta asociado a ese id. Para obtener los DLR correspondientes sólo debe de hacer la petición GET correspondiente explicado en el apartado Comandos adicionales de HTTP(S) GET Parámetros del fichero XML. Los parámetros obligatorios están en azul PARÁMETRO user password sender smstext DESCRIPCIÓN Usuario Contraseña Nombre del remitente del mensaje Remitente alfanumérico: largo máximo 11 caracteres Remitente numérico: largo máximo 11 caracteres Texto del mensaje (160 caracteres máx.). Recomendamos no usar comilla simple o doble ya que algunos DLR no se recibirán. Página 7

8 gsm Número GSM receptor en formato internacional (3461xxxxxxxx, 5521xxxxxxxx,...). No incluir el 00 inicial. id type datacoding validityperiod deferred Número de serie definido por el cliente. Usado para enlazar este id con el id que devuelve la API de GestMailing. Tipo de Mensaje Flash Un mensaje Flash se muestra directamente en la pantalla del teléfono, si este lo soporta. Parámetro opcional: valor predeterminado = 1 0 Enviado como Flash 1 Al móvil (por defecto) 2 A la SIM del teléfono Parámetro de codificación de datos Parámetro opcional, valor predeterminado = 0 0: 7 bit, por defecto 1: 8 bit. 2: UCS-2 Validez del mensaje en minutos, desde que se entrega en nuestra plataforma. Un período de validez mayor 2880 minutos (48hs) no es soportado Utilizado para programar el retraso de envío de SMS (No envía el SMS en el momento sino a un horario planificado). El tiempo de retraso es en minutos, hasta 2880 minutos (48 horas), a partir de la entrega en nuestra plataforma Respuestas del servidor a peticiones POST XML La línea de respuesta XML será la siguiente <RESPONSE> <status> <id></id> <idgm></idgm> </status> <status> <id></id> <idgm></idgm> </status>... </RESPONSE> PARÁMETRO Id Idgm DESCRIPCIÓN Parámetro aportado por el cliente en la petición POST. Si no se aportó, sale vacío Es el valor de respuesta de la aplicación GestMailing según la tabla: Valores de respuesta a peticiones POST/GET Página 8

9 Ejemplo de petición POST XML sobre PHP <?php //URL para solicitud POST de $posturl = " // datos en formato XML $xmlstring = "<SMS> <authentification> <user>gm.test1</user> <password>gm.pass1</password> </authentification> <message> <sender>gestmail</sender> <smstext>este es el texto del mensaje</smstext> <type></type> <datacoding></datacoding> <validityperiod></validityperiod> <deferred></deferred> </message> <recipients> <phone> <id> </id> <gsm> </gsm> </phone> <phone> <id> </id> <gsm> </gsm> </phone> </recipients> </SMS>";?> $fields = utf8_encode($xmlstring); $fields = "XML=". urlencode($fields); // Solicitud POST realizada con CURL de PHP. Debe tener instalado el módulo Curl-PHP $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $posturl); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); // respuesta de la solicitud POST $response = curl_exec($ch); curl_close($ch); Página 9

10 HTTP y HTTPS GET La URL utilizada para enviar mensajes utilizando HTTP GET es: Punto de acceso primario: Punto de acceso secundario: La URL utilizada para enviar mensajes utilizando HTTPS GET es: Punto de acceso primario/secundario: Recomendamos encarecidamente usar llamadas HTTPS Ejemplo de envío para un mensaje de texto normal: a enviar &GSM= La respuesta a esta llamada GET puede ser un código de error o el ID del mensaje. Parámetros de línea de consulta. Los parámetros obligatorios están en azul PARÁMETRO user password sender SMSText DESCRIPCIÓN Usuario Contraseña Nombre del remitente del mensaje Remitente alfanumérico: largo máximo 11 caracteres Remitente numérico: largo máximo 11 caracteres Texto del mensaje (160 caracteres máx.). Recomendamos no usar comilla simple o doble ya que algunos DLR no se recibirán. GSM Número GSM receptor en formato internacional (3461xxxxxxxx, 5521xxxxxxxx,...). No incluir el 00 inicial. type DataCoding ValidityPeriod deferred Tipo de Mensaje Flash Un mensaje Flash se muestra directamente en la pantalla del teléfono, si este lo soporta. Parámetro opcional: valor predeterminado = 1 0 Enviado como Flash 1 Al móvil (por defecto) 2 A la SIM del teléfono Parámetro de codificación de datos Parámetro opcional, valor predeterminado = 0 0: 7 bit, por defecto 1: 8 bit. 2: UCS-2 Validez del mensaje en minutos, desde que se entrega en nuestra plataforma. Un período de validez mayor 2880 minutos (48hs) no es soportado Utilizado para programar el retraso de envío de SMS (No envía el SMS en el momento sino a un horario planificado). El tiempo de retraso es en minutos, hasta 2880 minutos (48 horas), a partir de la entrega en nuestra plataforma. Página 10

11 Tenga especial atención en la sintaxis de la llamada GET ya que la introducción de caracteres extraños como la comilla doble o simple en el texto o en el nombre del remitente, podría dar lugar a respuestas erróneas en el Gateway SMS. Aunque el SMS llegue a su destino, es posible que usted no obtenga el reporte de DLR Comandos adicionales de HTTP(S) GET Consulta de crédito disponibles Esta consulta devuelve los créditos, en euros ( ) que quedan disponibles al usuario. El punto separa los decimales. Consulta de crédito disponibles ampliados Como en la función anterior, muestra el total de créditos en euros ( ) y además por código de país el coste del SMS, así como el cálculo del número de mensajes de SMS disponibles. La respuesta está codificada en lenguaje XML con este formato: <RESPONSE> <credits>xxxxx.xx</credits> <route> <country>34</country> <cost>0.080</cost> <remain>12457</remain> </route> <route> <country>351</country> <cost>0.003</cost> <remain>112759</remain> </route>... </RESPONSE> Consulta de cobertura y créditos Con esta consulta puede saber para qué países tiene usted habilitado el envío así como su coste por SMS. La consulta devuelve un fichero html separado por <br> cada línea, de manera que queda codificado de la siguiente manera. Cod: XX, Coste: cccc.ccc Donde XX representa el código del país y cccc.ccc representa el precio por SMS, con la separación decimal por medio del punto. Consulta de la versión actual del software API Página 11

12 2.3. Recolección de informes de entrega Con este método API usted puede recolectar informes de entrega de los SMS enviados. Siempre que no devuelva error, cada SMS enviado devuelve un ID único que se usa para tratar su estado de entrega Método Pull Para poder recolectar informes de entrega, tanto en peticiones POST como GET deberá llamar a la siguiente URL: En este ejemplo, el ID devuelto por la aplicación fue: 5220dd La consulta devolverá dos valores. Un código, un espacio de separación y la fecha de entrega, codificada en formato: AAAA- MM-DD HH:MM:SS. La zona horaria estará siempre en Hora Central Europea y dependiendo de la fecha en CET o CEST. Por ejemplo: :39:48 Tabla: Valores de códigos devueltos VALOR DESCRIPCIÓN 1 Entregado en el teléfono 2 Entrega fallida 4 Mensaje en cola del SMSC 8 Entregado en el servidor de mensajes SMSC 16 Rechazado por SMSC 32 Notificación del SMSC -20 No existen datos para ese ID Otro valor No existe DLR de ese SMSC GestMailing sólo garantiza los DLR durante las 48 horas siguientes al envío del mensaje SMS. Si se consultase depués de esa fecha, daría error -20. Página 12

13 3. Valores de respuestas a peticiones de envíos SMS Las peticiones GET o POST, para el envío de SMS tienen estos valores comunes de respuestas Tabla: Valores de respuesta a peticiones POST/GET VALOR DESCRIPCIÓN -99 Error genérico de la Aplicación. No achacable al usuario -98 Error genérico relacionado con la base de datos. No achacable al usuario -10 Error de usuario o password. Campos USER o PASSWORD -2 Falta crédito para el envío o el país de recepción no está autorizado para el envío. -6 Error en el campo TO. Campo GSM de destino -7 Error en el mensaje. Es mayor de 160 caracteres o no existe -13 Error del campo SENDER -16 Error en el tipo de mensaje, campo TYPE -17 Error en el parámetro de codificación, CODING -18 Error en el parámetro VALIDITY -19 Error en el parámetro DEFERRED -20 No existen datos para la consulta > 0 ÉXITO, el valor de respuesta es el ID del mensaje enviado Página 13

14 4. Control de versiones Puede consultar la versión de la plataforma en v3.0 Septiembre Lanzamiento de versión nueva basada HTTP GET. v3.1 Octubre Mejoras y añadidos sobre la versión 3.0 Envío de correo al cliente cuando falta crédito Mejoras de rendimiento de la aplicación Comienzo del desarrollo web panel SMS v3.1.1 Noviembre Mejoras y añadidos sobre la versión 3.1 Envío de correo cuando baja de un umbral de crédito Solución a problemas con el DLR Report v3.2 Noviembre Mejoras y añadidos sobre la versión Versión API basada en POST Mejoras en el reporte de DLR Envíos de correos al cliente cuando se baja de un umbral de crédito v3.3 Noviembre Mejoras y añadidos sobre la versión 3.2 Cambios en las codificaciones de envíos Inicio de la Beta 0.2 del Web SMS v3.3.1 Marzo Añadidos sobre la versión 3.3 Se añade el script creditsplus.php v3.3.2 Enero Añadidos sobre la versión Se añade el script sendsms2.php para envíos múltiples masivos vía POST Página 14