MT - HTML API Interface Copyright 2008-2009 FTL Management S.A.. www.txtcel.com
Índice Descripción 2 Enviar SMS 5 Verificar estado de un SMS 7 Verificar el saldo 8 Anexo 1 - Estados de un SMS 9 Anexo 2 - Ejemplo con HTML 10 Anexo 3 - Ejemplo con PHP 11 Página 1/11
Descripción Este documento describe como enviar mensajes MT/Push utilizando la API HTTP (API en adelante) de la plataforma Txt2cel FTL Management S.A.. (Txt2cel en adelante). Los envíos se realizan por el protocolo http o https y a través de la aplicación para mantener un registro de todos los envíos y los estados de cada mensaje. En cualquier momento se puede acceder a la aplicación para consultar el registro de sms y las estadísticas. Es necesario obtener un usuario y clave de Txt2cel para poder operar con esta inteface. Puede realizarlo desde la web de Txt2cel en http://www.txt2cel.com en el apartado de Crear Cuenta, o bien contactando via e-mail a sales@txt2cel.com. Txt2cel recomienda utilizar el protocolo https para garantizar la seguridad de los datos enviados y recibidos. Todas las peticiones a la API deben realizarse a la siguiente url: - Sin seguridad: http://sms.txt2cel.com - Con seguridad: https://sms.txt2cel.com Nota 1: Sólo se permite el paso de parámetros por el método POST. Nota 2: Las Variables y los valores predefinidos son case-sensitive. Para cualquier incidencia pueden contactar con soporte técnico en: - Entrando en la aplicación y seleccionado Soporte en el menú. - Enviando un e-mail a support@txt2cel.com Página 2/11
Enviar SMS Se permiten enviar los siguientes tipos de sms: - Texto: Hasta 160 caracteres dependiendo del país de destino. - Texto UTF: Hasta 70 caracteres, los caracteres soportados dependen de la red de destino y del móvil del usuario. - Binario (WapPush): Con un cuerpo de hasta 50 caracteres, y una url. La suma del cuerpo y la url no puede pasar los 160 caracteres. Variable Descripción m l_user l_password Type Gw.HTTPSendMT Usuario Contraseña Valores aceptados: Txt, Uni, WP (Texto, UTF/Unicode, WapPush) Originator Quién envía el mensaje. Se acepta A-Z y 0-9. Min: 4 cars. (1) SinglePhone Número de móvil con prefijo. Ej: 346nnnnnnnn (2) Msg Mensaje a enviar. Min: 2 cars. (3) URL Obligatorio si es Binario/WapPush. La URL debe ser completa. Ej: http://www.test.com/a/b/ Cert Opconal. Valores aceptados: Y, N. Default=N (4) (1) No todos los países permiten caracteres. Para enviar un número cómo origen mire la nota (2) (2) No está permitido el envío del signo + o el 00 y debe contener el prefijo del país. Ejemplos: (1) Correcto: 34600000000 (2) Correcto: (34) 600 000-000 (3) Incorrecto: 600000000 (4) Incorrecto: 0034600000000 (5) Incorrecto: +34600000000 (3) Para mensajes de Texto (Txt) es recomendable utilizar únicamente los caracteres A-Z, 0-9 y los signos de puntuación para que sea visible en todos los dispositivos móviles. (4) Si Cert tiene el valor Y automáticamente Unicode es deshabilitado y el Type es Txt. Una vez realizada la petición el resultado devuelto puede ser una de las siguientes opciones (cada linea está separada por el tag <BR>): Página 3/11
- DENIED: El usuario/clave son incorrectos. - LOCKED: El usuario no ha finalizado la inscripción. Contactar con soporte. - ERROR: Ha ocurrido algún error al procesar las Variables. A continuación habrá una lista de cada uno de los errores. - Si todo es correcto se recibirá el siguiente formato: - OK: n (nº de sms enviados) - BLACKLISTED: n (nº de sms no enviados por BlackList) - NOROUTE: n (nº de sms no enviados por que no hay ruta de destino) - NOCREDIT: n (nº de sms no enviados por falta de crédito) - LIMITMONTH: n (nº de sms no enviados por límite mensual) - ID:n,n,n... (Identificador de los sms enviados separados por coma) Ejemplos de respuestas: Ejemplo 1: DENIED<BR> Ejemplo 2: OK:3<BR> BLACKLISTED:0<BR> NOROUTE:0<BR> NOCREDIT:0<BR> LIMITMONTH:0<BR> ID:1,2,4<BR> Página 4/11
Verificar estado de un SMS El procedimiento es similar al envío de un MT, pero con los siguientes parámetros: Variable Descripción m l_user l_password ID Gw.HTTPCheckMT Usuario Contraseña Identificador del sms a comprobar El resultado de la petición puede ser: - DENIED: El usuario, la contraseña o el identificador son incorrectos,. - LOCKED: El usuario no ha finalizado la inscripción. Contactar con soporte. - Si todo es correcto se recibirá el siguiente formato: - STATUS:n (ver tabla Anexo 1) Ejemplos de respuestas: Ejemplo 1: DENIED<BR> Ejemplo 2: STATUS:0<BR> Página 5/11
Verificar el saldo Variable Descripción m l_user l_password Gw.HTTPCheckAccountBalance Usuario Contraseña El resultado de la petición puede ser: - DENIED: El usuario, la contraseña o el identificador son incorrectos,. - LOCKED: El usuario no ha finalizado la inscripción. Contactar con soporte. - Si todo es correcto se recibirá el siguiente formato: - BALANCE:n (n representa el número de créditos disponibles) Ejemplos de respuestas: Ejemplo 1: DENIED<BR> Ejemplo 2: BALANCE:100.00<BR> Página 6/11
Anexo 1 - Estados de un SMS Valor Descripción -1 No procesado. 0 Correcto. >0 Error Página 7/11
Anexo 2 - Ejemplo con HTML El siguiente código está disponible en la url http://sms.txt2cel.com/html_api/html.test.html <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> <title>mt - HTML API Interface - Test</title> </head> <body> <center><font size="+2">mt - HTML API Interface - Test</font></center><br> <center><u><b>send SMS</b></u><br><br></center> <form method="post" action="https://sms.txt2cel.com/?m=gw.httpsendmt"> <table style="border:1px black solid" align="center"> <tr><th>variable</th><th>value</th></tr> <tr><td>l_user</td><td><input type="text" name="l_user" value=""><td></tr> <tr><td>l_password</td><td><input type="text" name="l_password" value=""><td></tr> <tr><td>type</td><td><select name="type"><option>txt</option><option>uni</option><option>wp</option></select><td></tr> <tr><td>originator</td><td><input type="text" name="originator" value=""><td></tr> <tr><td>msg</td><td><textarea cols="20" rows="3" name="msg"></textarea><td></tr> <tr><td>url</td><td><input type="text" name="url" value=""><td></tr> <tr><td>singlephone</td><td><input type="text" name="singlephone" value=""><td></tr> <tr><td>cert</td><td><select name="cert"><option>n</option><option>y</option></select><td></tr> <tr><td colspan="2" align="center"><input type="submit" name="submit" value="submit"></td></tr> </table> </form> <br> <center><u><b>check SMS status</b></u><br><br></center> <form method="post" action="https://sms.txt2cel.com/?m=gw.httpcheckmt"> <table style="border:1px black solid" align="center"> <tr><th>variable</th><th>value</th></tr> <tr><td>l_user</td><td><input type="text" name="l_user" value=""><td></tr> <tr><td>l_password</td><td><input type="text" name="l_password" value=""><td></tr> <tr><td>id</td><td><input type="text" name="id" value=""><td></tr> <tr><td colspan="2" align="center"><input type="submit" name="submit" value="submit"></td></tr> </table> <br> </form> <br> <center><u><b>check account balance</b></u><br><br></center> <form method="post" action="https://sms.txt2cel.com/?m=gw.httpcheckaccountbalance"> <table style="border:1px black solid" align="center"> <tr><th>variable</th><th>value</th></tr> <tr><td>l_user</td><td><input type="text" name="l_user" value=""><td></tr> <tr><td>l_password</td><td><input type="text" name="l_password" value=""><td></tr> <tr><td colspan="2" align="center"><input type="submit" name="submit" value="submit"></td></tr> </table> <br> </form> <br> </body> </html> Página 8/11
Anexo 3 - Ejemplo con PHP <? /*** ***/ MT - HTML API Interface - Test define('server_url', 'http://sms.txt2cel.com/'); define('user', 'change_it'); define('password', 'change_it'); // Send SMS $PostFields = ''; $PostFields.= 'l_user='.urlencode(user); $PostFields.= '&l_password='.urlencode(password); $PostFields.= '&Type='.urlencode('Txt'); $PostFields.= '&Originator='.urlencode('TEST'); $PostFields.= '&Msg='.urlencode('Hello World!'); $PostFields.= '&SinglePhone='.urlencode('34999999999'); $PostFields.= '&Cert='.urlencode('N'); $curl = curl_init(); curl_setopt($curl, CURLOPT_URL, SERVER_URL.'?m=Gw.HTTPSendMT'); curl_setopt($curl, CURLOPT_POST, 1); curl_setopt($curl, CURLOPT_POSTFIELDS, $PostFields); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); $result = curl_exec($curl); curl_close($curl); echo "Result for <b>send SMS</b><br>"; $aresult = explode("<br>", $result); switch ($aresult[0]) { case 'DENIED': case 'LOCKED': // Do some actions here. die("denied"); break; case 'ERROR': // Do some actions here. die($result); break; } default: // Do some actions here. die($result); break; // End SMS?> Muchas Gracias www.txt2cel.com Página 9/11