API Documentación de integración API unificada para la integración de todos v.15.0 nuestros productos y servicios

Transcripción

1 Ekosolutions Ekosolutions API API API Documentación de integración API unificada para la integración de todos v.15.0 nuestros productos y servicios

2 Índice 1. SMS Premium pago único 1.1 Pasarela Gateway HTTPS/HTTP modo síncrona respuesta directa 1.2 Pasarela Gateway HTTPS/HTTP modo asíncrona doble respuesta 1.3 Recepción de confirmación de entrega (DLR) y confirmación de cobro (DRR) 2. SMS Premium suscripción Alertas SMS mediante webpin o SMS 2.1 Comprobación de operador móvil mediante HLR y envió de SMS Web Pin 2.2 Comprobación de pin y suscripción mediante checkpin 2.3 Envío de alertas mediante HTTP 2.4 Recepción de confirmación de entrega (DLR) y confirmación de cobro (DRR) 3. Envío de SMS 3.1 Envío de SMS mediante HTTPS/HTTP 3.2 Recepción del estado del envío y entrega Delivery report 3.3 Envío de SMS mediante SMPP 4. HLR Consulta de operador y estado del móvil 4.1 Consulta de operador del móvil abonado y estado mediante HTTP/HTTPS 5. Crear locución de voz sintética TTS 5.1 Crear locución de voz sintética TTS 5.2 Lista de voces sintéticas disponibles con su código de idioma y genero

3 1. SMS Premium pago único Esta pasarela permite ofrecer sus propios servicios bajo su plataforma o sistema convirtiendo los mensajes entrantes enviados por los s mediante su teléfono móvil en peticiones HTTP/S GET o POST enviadas a su servidor web y personalizando el mensaje de respuesta a enviar en la misma petición (modo sincrona) o enviando una petición a nuestros servidores de forma diferida en modo asincrona, además podrá recibir la confirmación de entrega y cobro de los mensajes mediante el servicio de DRR y DLR. 1.1 Pasarela Gateway HTTPS/HTTP modo síncrona respuesta directa Cada mensaje recibido será convertida en una petición GET o POST configurable desde la plataforma con los siguientes parámetros enviados de forma codificada mediante urlencode de PHP en la codificación utf8 con lo que deberá decodificarlos mediante la función urldecode de PHP o similares según el lenguaje de programación de su servicio web. text Texto enviado por el TEXTO_ENVIADO uniqueid ID única del SMS entrante keyword Palabra clave del servicio CHATSMS country Código ISO de 2 letras del pais ES para España op Código alfanumérico del operador en la plataforma MO destination Número de teléfono del móvil que envio el sms mnc Código de la red del operador único (Mobile network code) En Movistar España sería 1 mcc Código del país (Mobile country code) En España sería 214 from Número premium donde enviaron el SMS Premium id_campaign Id de la campaña sms asociada al servicio 1076 client Id número de la cuenta de cliente asociada al servicio 2 hour Hora de recepción del sms en GMT+1 hh-ii-ss date Fecha de recepción del sms en GMT+1 dd-mm-yyyy En caso de desear responder el mensaje entrante en modo síncrona deberá responder a su petición HTTP con el siguiente formato en texto plano: <msg>mensaje de respuesta en texto plano</msg> O si lo prefiere puede contestar mediante un wap push con el siguiente formato: <wap_url> <wap_text>texto del mensaje</wap_text>

4 Recuerde que nunca deberá superar los 160 caracteres en la respuesta de sus mensajes para evitar la facturación de MT adicionales incluyendo el texto legal enviado en el primer mensaje del del día en España según la regulación vigente y enviado de forma automática por Ekosolutions. 1.2 Pasarela Gateway HTTPS/HTTP modo asíncrona doble respuesta La recepción de los mensajes es igual al método síncrona pero varia la forma de contestarlos ya que en vez de contestarse en la respuesta de la petición entrante, deberá realizar una petición a nuestra API con el texto a enviar de respuesta, pudiendo así demorar la respuesta al mismo, útil por ejemplo para servicios de soporte al que requieran de una respuesta manual por parte de los operadores del Callcenter. La url donde deberá enviar la respuesta a sus MT es en modo SSL desde HTTPS: Llave de acceso de la cuenta de uniqueid ID única del SMS entrante text Texto para el mensaje de respuesta sin mención legal Tu clave es xxxx action Acción del API sendmt url URL en caso de desear enviar un WAP link dlr_url Url personalizada para recibir el delivery report Recepción de confirmación de entrega (DLR) y confirmación de cobro (DRR) Le podemos notificar en tiempo real la confirmación de entrega y cobro recibidas por las operadoras que dispongan de esta tecnología de esta forma podrá supervisarlos también en su plataforma o sistema. La URL de confirmación puede personalizarla con sus propias variables y url propias de su sistema en cada SMS definiéndola en la variable dlr_url enviada a la hora de responder los mensajes con el texto de respuesta en el modo asíncrona o en la configuración de su pasarela Gateway en modo síncrona. Las variables GET que recibirá serán:

5 status 1 cobrado, 2 fallido 1 type Tipo de servicio 1 sms premium o 2 sms alertas 1 uniqueid ID única del SMS entrante error Descripción del error en caso de fallido Saldo insuficiente 2. SMS Premium suscripción Alertas SMS mediante webpin o SMS Ofrezca sus propios servicios de suscripción utilizando nuestros contenidos o los suyos propios y recibiendo beneficios por cada SMS enviado a los suscriptores permitiendo el alta a través de SMS y a través de la web con validación a través de un pin enviado a los s mediante SMS y confirmado desde la web. 2.1 Comprobación de operador móvil mediante HLR y envío de SMS Web Pin El alta puede realizarse a través de SMS o mediante web a través del servicio webpin en este apartado vamos a ofrecer los detalles para realizar el envío de webpin y también la posibilidad de utilizar el servicio HLR para comprobar el operador del teléfono para enviar el pin sin necesidad de preguntarlo al. La url donde deberá enviar la petición para enviar el webpin: Llave de acceso de la cuenta de destination Teléfono del destinatario con prefijo del pais from Número del número premium operator Código del operador o dejar en blanco para auto detectar MO country Código iso número del pais 724 keyword Palabra clave asociada al servicio PREMIO action Acción del api sendpin

6 La respuesta del api en caso de haber sido enviado el pin correctamente será con un OK seguido del código de retorno del operador. Por ejemplo OK SMSWEBPIN 0001 Para Movistar OK SMSWEBPIN 0002 Para Vodafone En caso de error el mensaje de retorno será KO seguido del código de error por ejemplo: KO MOBILENOTVALIDBYOPERATOR OPCODE Comprobación de pin y suscripción mediante checkpin Una vez enviado el pin el deberá introducirlo en un formulario y desde su aplicación comprobarlo utilizando nuestra API. La url donde deberá enviar la petición para comprobar el pin y procesar el alta es: Llave de acceso de la cuenta de destination Teléfono del destinatario con prefijo del país from Número del número premium operator Código del operador o dejar en blanco para auto detectar MO country Código iso número del país 724 keyword Palabra clave asociada al servicio PREMIO action Acción del api checkpin pin Pin enviado por el operador al 1234 La respuesta del api en caso de haber introducido el pin correcto y no haber ocurrido ningún error, se confirmará la suscripción del con una respuesta con la palabra OKSTART seguido del código de retorno del operador. Por ejemplo OKSTART SMSWEBPIN 0101 Para Movistar OKSTART SMSWEBPIN 0102 Para Vodafone En caso de error el mensaje de retorno será KO seguido del código de error por ejemplo: KO INVALIDPIN OPCODE4004

7 2.3 Envío de alertas mediante HTTP o HTTPS Para realizar el envío de una alerta SMS a un teléfono móvil suscrito deberá realizar la siguiente petición. La url donde deberá enviar la petición para comprobar el pin y procesar el alta es: Llave de acceso de la cuenta de destination Teléfono del destinatario con prefijo del pais from Número del número Premium country Código ISO número del país 724 keyword Palabra clave asociada al servicio PREMIO action Acción del api sendalert text Texto a enviar en el SMS como alerta Sonido divertido para tu teléfono url URL a enviar como wap link dlr_url Url personalizada para recibir el delivery report La respuesta del api en caso de haber enviado correctamente la alerta SMS será: OK SENDALERT En caso de error el mensaje de retorno será KO seguido del código de error. Código de error KO MAXPERDAY Descripción del error Número de mensajes por día superado KO NOSUSCRIPTION El teléfono no está suscrito a este servicio de alertas

8 2.4 Recepción de confirmación de entrega (DLR) y confirmación de cobro (DRR) Le podemos notificar en tiempo real la confirmación de entrega y cobro recibidas por las operadoras que dispongan de esta tecnología de esta forma podrá supervisarlos también en su plataforma o sistema. La URL de confirmación puede personalizarla con sus propias variables y url propias de su sistema en cada SMS definiéndola en la variable dlr_url enviada a la hora de responder los mensajes con el texto de respuesta en el modo asíncrona o en la configuración de su pasarela Gateway en modo síncrona. Las variables GET que recibirá serán: status 1 cobrado, 2 fallido 1 type Tipo de servicio 1 SMS Premium o 2 SMS Suscripciones uniqueid ID única del SMS entrante error Descripción del error en caso de fallido Saldo insuficiente 2

9 3. Envío de SMS Envio de mensajes sms masivos a través de nuestra API o servidor SMPP. 3.1 Envío de SMS mediante HTTPS/HTTP La url donde deberá enviar la respuesta a sus MT es en modo SSL desde HTTPS: Llave de acceso de la cuenta de from Remitente el mensaje PROBANDO destination Número de teléfono donde enviar el SMS separados por comas para enviar a múltiples destinatarios , text Texto para el mensaje Hola este es el texto del mensaje action Acción del API sendsms url URL en caso de desear enviar un WAP link dlr_url Url personalizada para recibir el delivery report La respuesta del api en caso de enviar correctamente los SMS: OK OK En caso de error el mensaje de retorno será KO seguido del código de error. Código de error KO NOCREDIT Descripción del error Saldo insuficiente para enviar el SMS

10 3.2 Recepción del estado del envío y entrega Delivery report Le podemos notificar en tiempo real la confirmación de envío y entrega de los mensajes enviados reportado por las operadoras de telefonía móvil. La URL de confirmación puede personalizarla con sus propias variables y url propias de su sistema en cada SMS definiéndola en la variable dlr_url enviada a la hora de responder los mensajes con el texto de respuesta en el modo asíncrona o en la configuración de su pasarela Gateway en modo síncrona. Las variables GET que recibirá serán: status 1 recibido, 2 fallido, 3 enviado al operador, 4 fallido sms push type Tipo de servicio 3 envío de sms 3 1 uniqueid ID único del SMS enviado error Descripción del error en caso de fallido No entregado 3.3 Envío de SMS mediante SMPP Para enviar SMS debe habilitar la IP de su servidor desde el apartado Mi cuenta y generar un APIKEY de acceso que será la contraseña de acceso al servidor SMPP y como deberá introducir el ID de su cuenta de cliente que también podrá visualizar desde el apartado mi cuenta. Datos de nuestro servidor SMPP: HOST: accesosms.es PUERTO: 2775 TYPE: EKO

11 4. HLR Consulta de operador y estado del móvil 4.1 Consulta de operador del móvil abonado y estado mediante HTTP/HTTPS Consulte el operador y estado de un teléfono móvil La url donde deberá enviar la petición para comprobar el pin y procesar el alta es: Llave de acceso de la cuenta de destination Teléfono del destinatario con prefijo del pais action Acción del api hlr La respuesta del api en caso de realizar la consulta correctamente: response_code=ok ported=no imsi= Country = Spain Network = Xfera Moviles MCC=214 MNC=04 En caso de error el mensaje de retorno será KO seguido del código de error. Código de error KO INVALIDNUMBER Descripción del error Número de teléfono incorrecto KO NOCREDIT Saldo HLR insuficiente

12 5. Crear locución con voz sintética TTS 5.1 Crear locución de voz sintética TTS Consulte el operador y estado de un teléfono móvil La url donde deberá enviar la petición para comprobar el pin y procesar el alta es: Llave de acceso de la cuenta de lang Idioma de la voz sintética es-es gender Genero de la voz sintética female= mujer male = home female Text Texto a generar en la locución Hola probando voz sintética action Acción del api tts La respuesta del api en caso de generar la locución de forma correcta: OK f29fe6bc810a88d2e9674be ec8307.wav En caso de error el mensaje de retorno será KO seguido del código de error. Código de error KO TTSERROR Descripción del error Error a la hora de generar la locución KO NOCREDIT No dispone del saldo necesario para generar la locución

13 5.2 Lista de voces sintéticas disponibles con su código de idioma y genero lang Gender descripción en-us female United States English Female Voice hu-hu female Hungarian Female Voice de-de male German Male Voice tr-tr female Turkish Female Voice de-de female German Female Voice es-es female Spain Spanish Female Voice en-us male United States English Male Voice cn-hk female Hong Kong Chinese Female Voice ru-ru female Russian Female Voice pt-pt female Portugal Portuguese Female Voice en-au female Australian English Female Voice el-gr female Greek Female Voice cn-tw female Taiwanese Chinese Female it-it female Italian Female Voice en-gb female United Kingdom English Female Voice es-es male Spain Spanish Male Voice es-ca female Spain Catalan Female Voice cn-cn male China Chinese Male Voice pl-pl female Polish Female Voice sv-se female Swedish Female Voice fr-ca male Canadian French Male Voice en-ca female Canadian English Female Voice es-mx male Mexican Spanish Male Voice fr-fr male French Male Voice fr-ca female Canadian French Female Voice pt-br female Brazil Portuguese Female Voice ko-kr female Korean Female Voice tr-tr male Turkish Male Voice es-mx female Mexican Spanish Female Voice ar-ar male Arabic Male Voice nl-nl female Dutch Female Voice cn-cn female China Chinese Female Voice fr-fr female European French Female Voice fi-fi female Finnish Female Voice cs-cz female Czech Republic Czech Female Voice ko-kr male Korean Male Voice ja-jp female Japanese Female Voice pt-pt male Portugal Portuguese Male Voice en-gb male United Kingdom English Male Voice ja-jp male Japanese Male Voice da-dk female Denmark Danish Female Voice ru-ru male Russian Male Voice it-it male Italian Male Voice