API Versión 2.6 USUARIO FINAL

Transcripción

1 Un Producto de HispaServices Networks. API Versión 2.6 USUARIO FINAL Índice Pág. 1 Información y Consideraciones Pág sendsms 2. pedir_coste 3. get_report - Ejemplo. - URL. - Parámetros Requeridos: username, password, mensaje, destino -Parámetros Opcionales remitente - Parámetros Opcionales callback (Ejemplo) ruta fecha wap - Devuelve (Valores y Ejemplo) - Envío Programado - CallBack smsid, status, msisdn - Ejemplo. - URL. - Parámetros Requeridos: username, password, mensaje, destino - Parámetros Opcionales remitente, callback, ruta, smsid, fecha, saldo - Devuelve en caso de Éxito - Devuelve en caso de Fallo - Ejemplo. - URL. - Parámetros Requeridos: username, password, sms_id - Devuelve en caso de Fallo - Devuelve en caso de Éxito Pág. 3 Pág. 4 Pág. 5 Pág. 6 Pág. 7 Pág. 8 APENDICE A / B Rutas de Envío / Caracteres Permitidos Pág. 9 APENDICE C Nuevos Servicios Pág. 10 1

2 INFORMACIÓN: Utilizando las diferentes funciones contempladas en esta documentación puede dotar del envío de SMS a su software o página web de forma sencilla y rápida con el único requisito de que el equipo disponga de conexión a Internet. Mediante esta API, se dan las herramientas necesarias para desarrollar la integración: enviar sms, consultar coste, consultar saldo, consultar el estado de un envío, etc. Gracias a estas funciones, además de poder automatizar y adaptar el envío de SMS a su empresa, también se abre la posibilidad de revender los SMS a los usuarios del software o página web gracias a los precios ajustados de los que disponemos. De esta manera, el envío de SMS baratos y de calidad, además de ser un valor añadido a su software, puede consolidarse como una fuente de ingresos nada despreciable. Aquellos interesados en revender el servicio de SMS consulten también la API de Distribuidores; específicamente diseñada para reducir el tiempo de desarrollo drásticamente sin perder ninguna funcionalidad, mediante el control total de subcuentas asociadas a su cuenta principal, y con plena confidencialidad y seguridad. De esta forma, sus clientes pueden darse de alta o realizar recargas online en su pasarela de pago, y hacer efectiva la recarga de forma inmediata y automatizada tras confirmar el pago. CONSIDERACIONES: Para garantizar la calidad tanto de sus desarrollos como del servicio SMS, se deben evitar solicitudes innecesarias. Un ejemplo de mal uso, sería que para disponer de un listado de historial con confirmaciones, se solicitase el reporte de cada envío del listado. En este caso, además de guardar en la base de datos cada envío después de una respuesta satisfactoria para disponer de un historial detallado; es necesario disponer de campos para guardar los destinatarios confirmados y los fallidos. De esta forma, se solicita únicamente nuevo reporte para aquellos envíos que no han sido confirmados todavía en su totalidad, y actualizando la información en la base de datos cada vez que se devuelve un reporte. Con este mismo objetivo, en caso de desear mostrar el saldo pendiente, se recomienda disponer de un campo en la base de datos, que sea modificado tras cada envío o compra; y actualizado por si ocurriese algún desfase, al solicitar el coste de un SMS. De esta manera, no es necesario realizar peticiones innecesarias para conocer el saldo de créditos restantes, o el total de créditos consumidos; valores que pueden ser consultados directamente en la base de datos de la aplicación. Si se siguen estas consideraciones, además de mejorar la experiencia del usuario final y evitar esperas y posibles problemas con su conexión a Internet, permite disponer de un detallado historial de envíos realizando únicamente consultas en local (filtrado, exportación a CSV, estadísticas de envío, etc.). 2

3 A continuación se indican los diferentes comandos que ofrecemos en nuestro API para integrar en las aplicaciones cliente. 1. sendsms Permite enviar mensajes SMS a uno o más destinatarios. Nota: Por favor, limite usted mismo las conexiones concurrentes, envíe un único proceso para garantizar la calidad del servicio. Si sufre problemas de latencia, considere usar HTTPKeepAlive. Ejemplo: A dos destinatarios de España, texto Prueba HispaSMS nótese URLencoding): contraseña&mensaje=prueba+hispasms&destino= , Nota: usuario (Nombre Cuenta Cliente) contraseña (Contraseña Cuenta Cliente). URL La url actual es: Parámetros requeridos: username password mensaje: máx. 160 caracteres para texto, máx. 280 para 8bit destino: Lista de teléfonos separados por,. Para dar un servicio eficiente se presupone que los destinos son números válidos de teléfono. Para más información sobre posibles números de teléfono acuda a Parámetros opcionales: remitente: Identificación del emisor del mensaje (máx. 11 caracteres). Esta opción es libre de uso, no hay restricción al nombre de Remitente, pero el cliente acepta su uso excluyendo a HispaSMS de los posibles daños o Ilegalidades que puedan realizarse por el uso indebido del servicio (uso de remitentes personalizados, ver página de términos de uso en el párrafo 11). Para pedir un remitente nuevo, acceda entre con su usuario y contraseña y vaya a Datos en el panel de control. Al final de la página en el desplegable seleccione remitente de mensajes y pulse Editar. En este menú podrá agregar remitentes personalizados que podrá utilizar en sus envíos sin límite. La opción de remitente está garantizada en la Ruta PREMIUM. Si no se especificase remitente, por defecto se utilizará HispaSMS.es ó HispaSMS. 3

4 callback: URI (Uniform Resource Identifier) a la que se va a enviar el reporte de envío cuando el mensaje llegue al terminal. Esta opción sólo es posible en la ruta 3, en caso de ser enviado por otra ruta, el dato será ignorado. Ejemplo: ruta: Ruta elegida para el envío del mensaje. La ruta existente en la actualidad es la 3 (Ruta Premium). cualquier otro valor o en su defecto, será tomado como 3 (Premium). Para más información acuda al Apéndice. fecha: Fecha y hora a la que desea que se realice el envío, el formato debe ser del tipo yyyy-mm-dd y hh:mm:ss, hora Española. wap: Si este parámetro es enviado, se enviará un WAP Push con la dirección especificada en esta variable. Ejemplo: DEVUELVE El mensaje devuelto tiene la forma: Codigo_estado Descripcion_estado batch_id (batch_id es opcional, dependiendo del error o ruta elegida) Los posibles valores de codigo_estado son: 0: En progreso (No ha sucedido ningún error en el envío). 2: Error. Compruebe que el número sea válido, y su operadora este dentro de la cobertura. Por favor póngase en contacto con nosotros si persiste. 3: Fallo de autentificación. O ausencia de parámetros requeridos. 4: Error en la validación de datos. 5: Créditos insuficientes. La descripción es en inglés y puede variar por lo que no debería depender de la descripción, sino del código de estado que es constante. Sin embargo, puede contener información útil para detectar errores cuando desarrolla la aplicación. batch_id, será siempre un valor entero positivo mayor que 0 que identifica al mensaje. Es fundamental guardarlo para posteriormente pedir reportes del mensaje y/o reporte automático ( callback ). Más información en callback y get_report. Ejemplos de respuestas: 3 Authentication failure 4 Unaccepted SenderID 3 Required parameters missing 5 Insufficient Credits 0 IN_PROGRESS Error 4

5 Envío Programado Los envíos programados te permiten enviar el mensaje a una hora y fecha especificada previamente. Los créditos son reducidos en el momento en el que se solicitan, y son agregados a la cuenta de créditos bloqueados. Los mensajes no se pueden cancelar. Si se especifica una fecha pasada, el mensaje sería enviado inmediatamente, y se devuelve un código de estado 0. Si la fecha es correcta se envían más tarde y tras la petición se devuelve 1. La hora especificada debe ser según GMT +1:00 (Hora Española). Sólo es posible realizar envíos programados a través de la Ruta Premium. Callback Cuando los mensajes llegan al terminal se devuelve una confirmación de entrega GET a la url especificada. De esta manera, se asegura que el mensaje ha sido recibido por el receptor. De esta manera, se asegura que el mensaje ha sido recibido por el receptor. Los parámetros enviados son: 1. smsid: La id suministrada al realizar el envío. 2. status: El estado del envío. 3. msisdn: El número de teléfono móvil sobre el que se aplica (útil para casos de envíos múltiples). 4. El parámetro status podrá tomar los valores: 0 : Caso satisfactorio 1: En Proceso (temporal, se realiza nuevo callback cuando el mensaje llegue). 2 : Error en el envío Sólo es aplicable si se ha especificado una dirección de callback y el mensaje es por la Ruta PREMIUM. 5

6 2. pedir_coste Permite conocer de antemano los créditos que costará el envío del mensaje, pudiendo ser destinatario múltiple y/o distintos países. Todos los parámetros son idénticos a sendsms salvo el parámetro saldo disponible únicamente en esta función. Los valores devueltos en caso de fallo también coinciden. Ejemplo: contraseña&mensaje=hola+hispasms&destino= , Nota: usuario (Nombre Cuenta Cliente) contraseña (Contraseña Cuenta Cliente). Es recomendable especificar la ruta que se envía o sino será considerado ruta 3. URL La url actual es: Parámetros requeridos: username password mensaje: máx. 160 caracteres para texto, máx. 280 para 8bit destino: Lista de teléfonos separados por, Parámetros opcionales: Son los mismos que para sendsms. Se aconseja estrechamente que se utilicen los mismos parámetros que para sendsms para asegurar que el coste es el correcto. remitente: Sin uso. callback: Sin uso. ruta: Por defecto se utiliza ruta 3. smsid: Sin uso. fecha: Sin uso. saldo: Si el valor de este parámetro es 1, se devolverá el saldo disponible en la cuenta actualmente (sin descontar el precio del SMS por el que se pide el coste). 6

7 Devuelve en caso de éxito: 0 Ticket price precio (donde precio es un número flotante de hasta 3 decimales) 0 Ticket price precio saldo (Únicamente disponible si el parámetro saldo=1, saldo es un número de hasta 3 decimales). Devuelve en caso de fallo: El mensaje devuelto tiene la forma: Codigo_estado Descripcion_estado Los posibles valores de codigo_estado son: 2: Error. Compruebe que el número sea válido, y su operadora este dentro de la cobertura. Por favor póngase en contacto con nosotros si el problema persiste. 3: Fallo de autentificación. O ausencia de parámetros requeridos. 4: Error en la validación de datos. La descripción es en inglés y puede variar por lo que no debería depender de la descripción, sino del código de estado que es constante. Sin embargo, puede contener información útil para detector errores cuando desarrolla la aplicación. Ejemplo: 0 Ticket price

8 3. get_report Con get_report es posible solicitar el estado de un mensaje, para comprobar si este ha llegado ya correctamente a su destino. Es imprescindible haber guardado el identificador devuelto tras enviar el mensaje. URL Ejemplo: ontraseña&sms_id= Nota: usuario (Nombre Cuenta Cliente) contraseña (Contraseña Cuenta Cliente). Parámetros requeridos: username password sms_id : La ID devuelta tras solicitar el envío con sendsms Devuelve en caso de fallo: status_code status_description Los valores para status_code son: 1: Envío en proceso (temporal, envío pendiente o programado para fecha posterior a la actual). 2: Error interno 3: Error de autentificación 4: Reporte no disponible (ruta 1) 5: Faltan parámetros requeridos Devuelve en caso de éxito: 0 Destinos_recibidos Destinos_fallados 8

9 Apéndice A: Rutas de envío HispaSMS ofrece distintas rutas para que el cliente elija la opción que más se adapta a sus necesidades: Ruta Premium Es una ruta de cobertura mundial y calidad extrema a un precio excepcional. Además dispone de remitentes personalizados ilimitados. Reporte de envío. Posibilidad de Programar sus envíos con fecha y hora. Muchos más servicios disponibles (ver web). Nota: Ruta por defecto. Apéndice B: Caracteres Permitidos Los caracteres que se pueden enviar en el cuerpo del mensaje son las letras de la 'a' a la 'z', de la 'A' a la 'Z', los números del '0' al '9', espacios, saltos de línea y los especiales más habituales, como por $ é É ñ Ñ Ç _ - * = +!? # % &., : ; ü Ü ( ) / Nota: Los caracteres que no puedan ser mostrados en el teléfono móvil serán suplantados por los de mayor semejanza. Por ejemplo, áíóú será sustituido por aiou. 9

10 Apéndice C: Nuevos Servicios HispaSMS además de mensajes de Texto, ofrece la posibilidad de realizar envíos FlashSMS, WAP-Push y MMS. Como también ofrecemos la posibilidad de dar servicios de SMS Premium (micropagos, etc.). Para mayor información, por favor, póngase en contacto con nosotros para que le podamos asesorar mejor. Página Web: Depto. Comercial: [email protected] Depto. Soporte Técnico: [email protected] 10