MANUAL TECNICO API SMS-HTTP

Transcripción

1 El presente documento tiene como objetivo describir la API HTTP para el envío de mensajes SMS Versión 3.1 MANUAL TECNICO API SMS-HTTP Estrategia de utilización

2 CONTENIDO 1 INTRODUCCION FORMATO SMS ESTANDAR HTTP PLANO PARAMETROS RESPUESTA FORMATO SMS POPUP HTTP PLANO PARAMETROS RESPUESTA FORMATO SMS VIA XML HTTP XML ESTRUCTURA XML PARAMETROS RESPUESTA XML RECOPILACIÓN DE INFORMES DE ENTREGA PUSH Estructura del WebService Ejemplo de implementación RECOPILACIÓN DE INFORMES DE ENTREGA PULL PARAMETROS RESPUESTA LISTA DE STATUS LISTA GSMERROR Documento técnico página 1

3 1 INTRODUCCION El presente documento tiene como objetivo explicar el uso de la API de HTTP para envió masivo de mensajes utilizando la funcionalidad que Zona4 disponibiliza para esta actividad. 2 FORMATO SMS ESTANDAR HTTP PLANO El formato utilizado en esta API y la URL definida por Zona4 es: URL: <NombreEnvio>&SMSText=<Mensaje_de_Texto>&GSM=<Número destino1, Numero destino2,,numero destino n> 2.1 PARAMETROS Los parámetros de la API son: URL User Password Sender Mensaje Destino URL de la API ( Username del usuario Password del usuario Nombre de quien envía, máximo 11 caracteres Mensaje, máximo 160 caracteres N destinatario gms con formato internacional, se pueden enviar más de un número con el mismo formato, con separador de coma ( , , , ) con un máximo de 300 números GSM 2.2 RESPUESTA La estructura de respuesta del mensaje está compuesta con los siguientes parámetros: <results> <destination>gsm_number_1</destination> <destination>gsm_number_2</destination> <destination>gsm_number_n</destination> Documento técnico página 2

4 </results> Los valores existentes de CODESTATUS disponibles son: Valor Descripción 0 Mensaje enviado correctamente -1 Error en proceso de envío -2 Sin créditos disponibles en la cuenta -3-5 Usuario o password invalido FORMATO SMS POPUP HTTP PLANO El formato utilizado en esta API y la URL definida por Zona4 es: URL: <NombreEnvio>&SMSText=<Mensaje_de_Texto>&GSM=<Número destino1, Numero destino2,,numero destino n>& datacoding= PARAMETROS Los parámetros de la API son: URL User Password Sender Mensaje Destino URL de la API ( Username del usuario Password del usuario Nombre de quien envía, máximo 11 caracteres Mensaje, máximo 160 caracteres N destinatario gms con formato internacional, se pueden enviar más de un número con el mismo formato, con separador de coma Documento técnico página 3

5 ( , , , ) con un máximo de 300 números GSM datacoding Parámetro fijo RESPUESTA La estructura de respuesta del mensaje está compuesta con los siguientes parámetros: <results> <destination>gsm_number_1</destination> <destination>gsm_number_2</destination> <destination>gsm_number_n</destination> </results> Los valores existentes de CODESTATUS disponibles son: Valor Descripción 0 Mensaje enviado correctamente -1 Error en proceso de envío -2 Sin créditos disponibles en la cuenta -3-5 Usuario o password invalido Documento técnico página 4

6 4 FORMATO SMS VIA XML HTTP XML El formato utilizado en esta API y la URL definida por Zona4 es: URL: POST Host: wssms.zona4.cl Content-Type: application/xml Accept: */* 4.1 ESTRUCTURA XML XML= <SMS> <authentication> <username>account_username</username> <password>account_password</password> </authentication> <message> <sender>zona4</sender> <text>mensaje</text> <flash></flash> <type></type> <wapurl></wapurl> <binary></binary> <datacoding>240</datacoding> <esmclass></esmclass> <srcton></srcton> <srcnpi></srcnpi> <destton></destton> <destnpi></destnpi> Documento técnico página 5

7 <senddatetime>4d3h2m1s</senddatetime> <ValidityPeriod></ValidityPeriod> <appid></appid> <pushurl></pushurl> <nopush></nopush> <recipients> <gsm messageid="clientmsgid1"> </gsm> <gsm messageid="clientmsgid2"> </gsm> <gsm messageid="clientmsgid3"> </gsm> <gsm messageid="clientmsgid4"> </gsm> </recipients> </message> </SMS> 4.2 PARAMETROS Los parámetros de la API son: URL Authentication.Username Authentication.Password Message.Sender Message.Text messageid Message.datacoding URL de la API ( Username del usuario Password del usuario Nombre de quien envía, máximo 11 caracteres Mensaje, máximo 160 caracteres N destinatario GSM con formato internacional, se pueden enviar más de un número con el mismo formato, con separador de coma ( , , , ) El valor de messageid debe comenzar con clientmsgid agregando un numero secuencia por cada número destino que se envíe, más el numero GSM de destino: <gsm messageid="clientmsgid1"> </gsm> <gsm messageid="clientmsgid2"> </gsm> 240, para envío de mensajes tipo PopUp 0, para envío de mensajes SMS normales 4.3 RESPUESTA XML El formato de cadena de retorno XML será el siguiente, por petición exitosa: Documento técnico página 6

8 Status Code: 200 Content-Type: text/csv;charset= UTF-8 Content-Length: 277 Date: Tue, 22 May :28:50 GMT La estructura de respuesta del mensaje está compuesta con los siguientes parámetros para la recepción de multiples registros: <results> <status>0</status> <messageid>clientmsgid1</messageid> <destination> </destination> <status><0</status> <messageid>clientmsgid2</messageid> <destination> </destination> </results> 5 RECOPILACIÓN DE INFORMES DE ENTREGA PUSH La solución permite que la información llegue directo a un servicio que su empresa disponibilice, cuando el estado final del mensaje sea recibido por la plataforma de Zona4. El cliente debe disponibilizar una URL para consumir el WebService con una estructura definida, y llegarán en forma automática el estado de los mensajes directamente desde la plataforma de ZONA4 ni bien sea informado. El servicio ejecutará como máximo 4 veces el intento de informar el mensaje, es por eso que el servicio debe estar siempre activo. 5.1 Estructura del WebService El formato de la estructura XML del informe de entrega será: <DeliveryReport> <message id= msgid sentdate= xxxxx donedate= xxxxx status= xxxxxx gsmerror= 0 />... </DeliveryReport> Documento técnico página 7

9 5.2 Ejemplo de implementación Script de Ejemplo para leer los datos, posterior al envío del mensaje mediante el método PUSH, usando un ejemplo desarrollado en PHP: <?php // read raw POST data $postdata = file_get_contents( php://input ); // extract XML structure from it using PHP s DOMDocument Document Object Model parser $dom = new DOMDocument(); $dom->loadxml($postdata); // create new XPath object for quering XML elements (nodes) $xpath = new domxpath($dom); // query message element $reports = $xpath->query( /DeliveryReport/message ); // write out attributes of each message element foreach ($reports as $node) { echo <br>id:. $node->getattribute( id ); echo <br>sent:. $node->getattribute( sentdate ); echo <br>done:. $node->getattribute( donedate ); echo <br>status:. $node->getattribute( status ); echo <br>gsmerrorcode:. $node->getattribute( gsmerrorcode ); }?> 6 RECOPILACIÓN DE INFORMES DE ENTREGA PULL La solución permite recolectar información del estado final de los mensajes a partir de una funcionalidad diseñada para estos efectos. Esta API permite recuperar el estado de un mensaje en particular o de un conjunto de mensajes que han sido enviados, a través de una estructura XML con un formato especifico. La información del estado final del mensaje estará disponible solo una vez para su recuperación y procesamiento. Una vez que se rescate el estado de un mensaje en particular, no se podrá obtener dicha información, obteniendo solo el mensaje NO_DATA La URL para obtener informes de entrega, a través del método HTTP GET es: mensage] 6.1 PARAMETROS Los parámetros utilizados son: Username Documento técnico página 8

10 Password Id mensaje - opcional, para solicitar informes de entrega específicos - posibilidad de solicitar varios separando con el carácter coma (,) 6.2 RESPUESTA Valores de retorno: 5: nombre de usuario y / o contraseña no válidos 10: nombre de usuario desconocido 11: contraseña desconocida NO_DATA: No existe información para el mensaje La estructura de informe de entrega XML es el siguiente: <DeliveryReport> <message id=" " sentdate="2014/12/09 19:06:27" donedate="2014/12/09 19:09:34" status="delivered" gsmerror="0" /> <message id=" " sentdate="2014/12/09 20:42:34" donedate="2014/12/09 20:45:38" status="delivered" gsmerror="0" /> </DeliveryReport> Si se utiliza la opción de consulta sin un Id de mensaje específico, la solución entregará un listado de 100 estados de mensajes, para su gestión. 6.3 LISTA DE STATUS A continuación se describen los distintos status de los mensajes recopilados STATUS DESCRIPCION NOT_SENT El mensaje se pone en cola en el sistema Zona4 pero no puede ser sometido a SMSC (posible razón: Conexión SMSC está abajo) SENT El mensaje fue enviado a través de una ruta que no admite informes de entrega NOT_DELIVERED El mensaje no pudo ser entregado DELIVERED El mensaje fue entregado exitosamente al recipiente NOT_ALLOWED El cliente no tiene autorización para enviar a la red especificada (el mensaje no será cargado) INVALID_DESTINATION_ADDRESS Invalido/incorrecto recipiente GSM INVALID_SOURCE_ADDRESS Ha especificado la dirección incorrecta / inválida / Prohibido fuente (nombre del remitente) ROUTE_NOT_AVAILABLE Usted está tratando de utilizar el enrutamiento que no está disponible para su cuenta NOT_ENOUGH_CREDITS No hay créditos disponibles en su cuenta para enviar el mensaje REJECTED El mensaje ha sido rechazado por razones variadas INVALID_MESSAGE_FORMAT Su mensaje tiene un formato inválido Documento técnico página 9

11 6.4 LISTA GSMERROR Los errores disponibles para gsmerror son: ERROR DESCRIPTION VALUE ERROR DESCRIPTION VALUE EC_UNKNOWN_SUBSCRIBER 1 EC_OR_encapsulatedAC_NotSupported 1027 EC_UNIDENTIFIED_SUBSCRIBER 5 EC_OR_transportProtectionNotAdequate 1028 EC_ABSENT_SUBSCRIBER_SM 6 EC_OR_potentialVersionIncompatibility 1030 EC_ILLEGAL_SUBSCRIBER 9 EC_OR_remoteNodeNotReachable 1031 EC_TELESERVICE_NOT_PROVISIONED 11 EC_NNR_noTranslationForAnAddressOfSuchNatur 1152 EC_ILLEGAL_EQUIPMENT 12 EC_NNR_noTranslationForThisSpecificAddress 1153 EC_CALL_BARRED 13 EC_NNR_subsystemCongestion 1154 EC_FACILITY_NOT_SUPPORTED 21 EC_NNR_subsystemFailure 1155 EC_ABSENT_SUBSCRIBER 27 EC_NNR_unequippedUser 1156 EC_SUBSCRIBER_BUSY_FOR_MT_SMS 31 EC_NNR_MTPfailure 1157 EC_SM_DELIVERY_FAILURE 32 EC_NNR_networkCongestion 1158 EC_MESSAGE_WAITING_LIST_FULL 33 EC_NNR_unqualified 1159 EC_SYSTEM_FAILURE 34 EC_NNR_SCCPfailure 1163 EC_UNEXPECTED_DATA_VALUE 36 EC_UA_userSpecificReason 1281 EC_SM_DF_memoryCapacityExceeded 256 EC_UA_userResourceLimitation 1282 EC_SM_DF_equipmentProtocolError 257 EC_UA_resourceUnavailable 1283 EC_SM_DF_equipmentNotSM_Equipped 258 EC_PA_providerMalfunction 1536 EC_SM_DF_sc_Congestion 260 EC_PA_ressourceLimitation 1538 EC_SM_DF_invalidSME_Address 261 EC_PA_maintenanceActivity 1539 EC_SM_DF_subscriberNotSC_Subscriber 262 EC_PA_versionIncompatibility 1540 EC_PROVIDER_GENERAL_ERROR 500 EC_PA_abnormalMapDialog 1541 EC_NO_RESPONSE 502 EC_TIME_OUT 2048 EC_SERVICE_COMPLETION_FAILURE 503 EC_InvalidMscAddress 2051 EC_UNEXPECTED_RESPONSE_FROM_PEER 504 EC_InvalidPduFormat 4096 EC_MISTYPED_PARAMETER 507 EC_Cancelled 4100 EC_INITIATING_RELEASE 511 EC_ValidityExpired 4101 EC_ERROR_PORTABILITY_OPERATOR 501 Documento técnico página 10