Especificación técnica para la integración

de servicio de recargas electrónicas.

CONFIDENCIAL. Marzo 2019.

INTRODUCCIÓN
La información contenida en este documento esta sujeta a cambios sin previo aviso, y por efectos de ajustes
para obtener una mejor solución en la integración entre POS y el aplicativo para recargas Electrónicas.

El presente documento así como los ejemplos y especificaciones son incluidos sin limitación se provee “como
son”.

Audiencia a quien va dirigido.

El presente documento va dirigido a desarrolladores, programadores y cualquier persona relacionada con el
ámbito en tecnologías de información, POS o del área de Sistemas computacionales.

Alcance
El presente documento no incluye contraseñas o claves de acceso a servidores, solo provee la información
necesaria entender el funcionamiento de la integración entre POS y el aplicativo para recargas electrónicas.

Pre-requisitos
El desarrollador deberá estar familiarizado con programación de Servicios Web, XML y POS.

OBJETIVO
El presente documento tiene como objetivo dar a conocer la funcionalidad de la Integración para la comuni-
cación de la Terminal Punto de Venta (POS) con la Plataforma de recargas electrónicas de los diferentes prov-
eedores del servicio de telefonía celular.

El esquema de comunicación se encuentra estructurado en 3 Niveles, el primer Nivel lo componen las termi-
nales punto de venta (POS), el segundo nivel esta compuesto por el servidor de la Plataforma de Recargas
Electrónicas (Gateway) y el tercer nivel lo componen los proveedores de telefonía celular.

La función del Primer nivel la realiza el POS enviando mensajes de solicitud al servidor del Aplicativo, medi-
ante una conexión a internet.

La función del segundo nivel la realiza el WEB SERVICES en el servidor del Aplicativo, el cual recibe las peti-
ciones de la terminal POS de recarga las valida y las pasa al siguiente Nivel.

El último Nivel realiza la solicitud a los proveedores de telefonía celular con la petición ya antes recibida y
regresa la respuesta para que siga el proceso hasta el POS.

-1-
FLUJO DE CONEXIÓN AL SERVICIO

1. Entrega del Kit de instalación solicitado (Especificaciones Técnicas). Este kit es entregado en el
área de tecnología con copia para el área gerencial de la cadena comercial.

2. El equipo de desarrolladores de la cadena comercial, podrá trabajar en la

implementación de los componentes del kit con su POS, el cual podría ser agregar un modulo
a su POS ya existente.

3. Pre-Certificación en servidor de pruebas en el cual se llevaran a cabo todas las revisiones necesri-
as en los servicios que el aplicativo puede ofrecer, con la finalidad de corroborar el correcto funcionamiento
de la misma.

4. Certificación. Una vez aprobada la pre-certificación, el siguiente punto es la certificación, la cual

consiste en la verificación por ambas partes, para corroborar el correcto flujo de la información y que los
resultados de la pre-certificación no hayan sido manipulados.

5. Cuando la integración d elos productos ha sido certificada, la aplicación de POS está lista para ser
liberada en las tiendas piloto seleccionadas.

6. Ya una vez en Operación, deberán entregar obligatoriamente un archivo de Conciliaciones de las

transacciones realizadas diariamente, este documento lo podrán mandar a una dirección FTP, a primera
hora del día siguiente.

-2-
ESPECIFICACIONES COMERCIALES

Productos Existentes
El aplicativo de Recargas electrónicas maneja las siguientes operadoras, donde cada una
maneja el siguiente listado de productos y/o montos:

Productos:

00 ALO
10, 20, 30, 40, 50
01 Telcel
10, 20, 30, 50, 80, 100, 150, 200, 300, 500
02 Movistar
10, 20, 30, 40, 50, 60, 70, 80, 100, 120, 150, 200, 250, 300, 400, 500
03 Unefon
10, 20, 30, 50, 70, 100, 120, 150, 200, 300, 500, 750, 1000
04 Iusacell
10, 20, 30, 50, 70, 100, 120, 150, 200, 300, 500, 750, 1000
06 Virgin
20, 30, 40, 50, 100, 150, 200, 300, 500
07 Maz Tiempo
10, 20, 30, 50, 60, 100, 120, 150, 200, 300, 500
08 Cierto
10, 20, 30, 50, 100, 200, 500
09 Tuenti
80, 100, 150, 250, 300
12 AT&T
10, 20, 30, 50, 70, 100, 120, 150, 200, 300, 500, 750, 1000
13 Movistar Agrandado
35, 65, 105, 125, 155, 205
64 Amigo Sin Límite
20, 30, 50, 80, 100, 150, 200, 300, 500
67 Internet Amigo
5, 20, 30, 50, 100, 150, 200, 300, 500
84 Internet Movistar
10, 30, 60, 80, 120, 200, 300
88 Internet Movistar Libre
10, 30, 60, 80, 120, 200, 300

-3-
TABLA DE PRODUCTOS

CÓDIGO OPERADORA VALOR

M010 MOVISTAR $10

M020 MOVISTAR $20
M030 MOVISTAR $30
M040 MOVISTAR $40
M050 MOVISTAR $50
M060 MOVISTAR $60
M070 MOVISTAR $70
M080 MOVISTAR $80
M100 MOVISTAR $100
M120 MOVISTAR $120
M150 MOVISTAR $150
M200 MOVISTAR $200
M250 MOVISTAR $250
M300 MOVISTAR $300
M400 MOVISTAR $400
M500 MOVISTAR $500
U010 UNEFON $10
U020 UNEFON $20
U030 UNEFON $30
U050 UNEFON $50
U070 UNEFON $70
U100 UNEFON $100
U120 UNEFON $120
U150 UNEFON $150
U200 UNEFON $200
U300 UNEFON $300
U500 UNEFON $500
U750 UNEFON $750
U1000 UNEFON $1000
I010 IUSACELL $10
I020 IUSACELL $20
I030 IUSACELL $30
I050 IUSACELL $50
I070 IUSACELL $70
I100 IUSACELL $100
I120 IUSACELL $120

-4-
TABLA DE PRODUCTOS

CÓDIGO OPERADORA VALOR

I150 IUSACELL $150

I200 IUSACELL $200
I300 IUSACELL $300
I500 IUSACELL $500
I750 IUSACELL $750
I1000 IUSACELL $1000
V020 VIRGIN $20
V030 VIRGIN $30
V040 VIRGIN $40
V050 VIRGIN $50
V100 VIRGIN $100
V150 VIRGIN $150
V200 VIRGIN $200
V300 VIRGIN $300
V500 VIRGIN $500
MT010 MAZ TIEMPO $10
MT020 MAZ TIEMPO $20
MT030 MAZ TIEMPO $30
MT050 MAZ TIEMPO $50
MT060 MAZ TIEMPO $60
MT100 MAZ TIEMPO $100
MT120 MAZ TIEMPO $120
MT150 MAZ TIEMPO $150
MT200 MAZ TIEMPO $200
MT300 MAZ TIEMPO $300
MT500 MAZ TIEMPO $500
C010 CIERTO $10
C020 CIERTO $20
C030 CIERTO $30
C050 CIERTO $50
C100 CIERTO $100
C200 CIERTO $200
C500 CIERTO $500
TT080 TUENTI $80
TT100 TUENTI $100

-5-
TABLA DE PRODUCTOS

CÓDIGO OPERADORA VALOR

TT150 TUENTI $150

TT250 TUENTI $250
TT300 TUENTI $300
N010 AT&T $10
N020 AT&T $20
N030 AT&T $30
N050 AT&T $50
N070 AT&T $70
N100 AT&T $100
N120 AT&T $120
N150 AT&T $150
N200 AT&T $200
N300 AT&T $300
N500 AT&T $500
N750 AT&T $750
N1000 AT&T $1000
M035 MOVISTAR AGRANDADO $35
M065 MOVISTAR AGRANDADO $65
M105 MOVISTAR AGRANDADO $105
M125 MOVISTAR AGRANDADO $125
M155 MOVISTAR AGRANDADO $155
M205 MOVISTAR AGRANDADO $205
ALO10 ALO $10
ALO20 ALO $20
ALO30 ALO $30
ALO40 ALO $40
ALO50 ALO $50
A020 TELCEL $20
A030 TELCEL $30
A050 TELCEL $50
A80 TELCEL $80
A100 TELCEL $100
A150 TELCEL $150
A200 TELCEL $200
A300 TELCEL $300
A500 TELCEL $500

-6-
TABLA DE PRODUCTOS

CÓDIGO OPERADORA VALOR

INT5 INTERNET AMIGO 10MB $5

INT20 INTERNET AMIGO 50MB $20
INT30 INTERNET AMIGO 100MB $30
INT50 INTERNET AMIGO 200MB $50
INT100 INTERNET AMIGO 400MB $100
INT150 INTERNET AMIGO 700MB $150
INT200 INTERNET AMIGO 1GB $200
INT300 INTERNET AMIGO 2GB $300
INT500 INTERNET AMIGO 4GB $500
SL020 AMIGO SIN LIMITE 20 $20
SL030 AMIGO SIN LIMITE 30 $30
SL050 AMIGO SIN LIMITE 50 $50
SL80 AMIGO SIN LIMITE 100 $80
SL100 AMIGO SIN LIMITE 100 $100
SL150 AMIGO SIN LIMITE 150 $150
SL200 AMIGO SIN LIMITE 200 $200
SL300 AMIGO SIN LIMITE 300 $300
SL500 AMIGO SIN LIMITE 500 $500
DM010 INTERNET MOVISTAR $10
DM030 INTERNET MOVISTAR $30
DM060 INTERNET MOVISTAR $60
DM080 INTERNET MOVISTAR $80
DM120 INTERNET MOVISTAR $120
DM200 INTERNET MOVISTAR $200
DM300 INTERNET MOVISTAR $300
DML010 INTERNET MOVISTAR LIBRE $10
DML030 INTERNET MOVISTAR LIBRE $30
DML060 INTERNET MOVISTAR LIBRE $60
DML080 INTERNET MOVISTAR LIBRE $80
DML120 INTERNET MOVISTAR LIBRE $120
DML200 INTERNET MOVISTAR LIBRE $200
DML300 INTERNET MOVISTAR LIBRE $300
YN020 YouTube + Netflix 1 días $20
YN040 YouTube + Netflix 3 días $40
YN060 YouTube + Netflix 7 días $60
YN100 YouTube + Netflix 7 días $100

-7-
CÓDIGO DE RESPUESTAS

CÓDIGO DESCRIPCIÓN
00 TRANSACCIÓN EXITOSA
01 TELEFONO INVÁLIDO REVISAR TELEFONÍA
02 DESTINO NO DISPONIBLE
03 MONTO NO VÁLIDO
04 NO SE PUEDE ABONAR
05 SALDO INSUFICIENTE
06 MANTENIMIENTO OPERADORA EN CURSO
07 RECHAZO TABLA DE TRANSACCIONES LLENA
08 TIME-OUT OPERADORA
09 AUTORIZADOR NO DISPONIBLE
10 INTERMITENCIA EN SERVICIO
11 OPERADORA NO DISPONIBLE
12 DATOS INCORRECTOS
13 FECHA PDV NO VALIDA
14 USUARIO BLOQUEADO
15 POSIBLE DUPLICADO, REVISAR CORTE (F10)
16 PRODUCTO NO DISPONIBLE
17 MOVIMIENTO NO ENCONTRADO
18 MOVIMIENTO YA REVERSADO
19 MOVIMIENTO NO AUTORIZADO
20 ERROR INDETERMINADO
21 NO SE PUDO REVERSAR
22 TIME -OUT OPERADORA
23 ERROR DE LA BASE DE DATOS OPERADORA
25 APLICATIVO NO VÁLIDO
30 OPERADORA NO DISPONIBLE
66 MANTENIMIENTO EN OPERADORA
72 TIME -OUT OPERADORA
73 TIME -OUT OPERADORA
75 TIME -OUT OPERADORA
83 TIME -OUT OPERADORA
87 TELÉFONO NO SUSCEPTIBLE DE ABONO
91 TIME -OUT OPERADORA
96 TIME -OUT OPERADORA

-8-
DATOS TÉCNICOS IMPORTANTES

Time-Out para solicitud de Venta: 60 Segundos.

Time-Out para Consulta de Transacciones: 15 Segundos.

Logs y/o Bitácora: Se deberá guardar de ambos lados, los logs de envió y recepción de ambas partes.

SOLICITUD DE VENTA TIEMPO AIRE ELECTRÓNICOS

El sistema externo hace una solicitud de abono de tiempo aire, enviando los datos:

XML de solicitud de venta:

<?xml version=”1.0” encoding=”utf-8” ?>
<SOLICITARTRANSACCION>
<PuntoVenta>PRUEBA0000</PuntoVenta>
<Password>432143</Password>
<Producto>A030</Producto>
<FechaVenta>18/03/2016 17:50:48</FechaVenta>
<Telefono>6561576892</Telefono>
<Folio>287</Folio>
<FechaInicio>18/03/2016 17:50:48</FechaInicio>
</SOLICITARTRANSACCION>

CAMPO TIPO FORMATO DESCRIPCIÓN

PuntoVenta String Máximo 10 Dígitos Usuario de venta
Password String Contraseña del usuario
Producto String Máximo 5 Dígitos Código de producto
(Ver tabla de productos)
FechaVenta DateTime dd/MM/aaaa Folio de la caja
HH:mm:ss Fecha de venta de transacción
Telefono String 10 Dígitos Teléfono a recargar
Folio String Máximo 10 Dígitos Folio de caja
FechaInicio DateTime dd/MM/aaaa
HH:mm:ss Fecha de venta de transacción

Nota: Excluir los espacios en blanco al inicio y al final de los campos de String, con el fin de no tener problemas inesperados al
momento de la Operación, esto es para todos los campos String en el documento técnico.

-9-
CONSULTA DE TRANSACCIÓN
El cliente estará en la obligación de realizar la Consulta de Transacción, una vez que no halla obtenido
respuesta en el time-out establecido anteriormente, la solicitud de la misma tiene que ser como mínimo 1
segundo después del mismo.

XML de consulta de transacción:

<CONSULTARTRANSACCION>
<PuntoVenta>PRUEBA0000</PuntoVenta>
<Password>432143</Password>
<Telefono>6561576892</Telefono>
<FolioCaja>287</FolioCaja>
</CONSULTARTRANSACCION>

CAMPO TIPO FORMATO DESCRIPCIÓN

PuntoVenta String Máximo 10 Dígitos Usuario de venta
Password String Máximo 10 Dígitos Contraseña del usuario
Telefono String 10 Dígitos Teléfono a recargar
FolioCaja String Máximo 10 Dígitos Folio de caja

RESPUESTAS A LAS SOLICITUDES

El XML de respuesta siempre será el mismo, en todos los casos.

XML de respuesta para solicitud de Venta y Consulta de Transacciones:

Xml de respuesta:
<RESPUESTA>
<Confirmacion>00</Confirmacion>
<Descripcion>OPERACIÓN EXITOSA</Descripcion>
<Folio>287</Folio>
</RESPUESTA>

CAMPO TIPO FORMATO DESCRIPCIÓN

Confirmación String 2 Dígitos Código de respuesta
(tabla de respuestas)
Descripción String Máximo 10 Dígitos Descripción de la respuesta
Folio Int 1 a 6 dígitos Folio del proveedor de 1 a 6 dígitos
(0-999999)

-10-
CONSULTA DE SALDO
Siempre se podrá consultar el saldo disponible del usuario que esta vendiendo, este procedimiento no
genera ningún costo económico.

Xml de consulta de saldo:

<SALDO>
<PuntoVenta>PRUEBA0000</PuntoVenta>
<Password>432143</Password>
<FechaInicio>18/03/2009 17:50:48</FechaInicio>
<Tipo>TAE</Tipo>
</SALDO>

CAMPO TIPO FORMATO DESCRIPCIÓN

PuntoVenta String Máximo 10 Dígitos Usuario de venta
Tipo String Máximo 3 Dígitos En este caso se enviará “TAE” para
indicar que es Tiempo Aire
Electrónico
Saldo Int Indica el saldo disponible

Xml de respuesta para la consulta de saldo:

<RESPUESTA>
<PuntoVenta>PRUEBA0000</PuntoVenta>
<Tipo>TAE</Tipo>
<Saldo>17.00</Saldo>
</RESPUESTA>

CAMPO TIPO FORMATO DESCRIPCIÓN

PuntoVenta String Máximo 10 Dígitos Usuario de venta
Tipo String Máximo 3 Dígitos En este caso se enviará “TAE” para
indicar que es Tiempo Aire
Electrónico
Saldo Int Indica el saldo disponible

-11-
PRE-CERTIFICACIÓN DE INTEGRACIÓN PARA TIEMPO AIRE

Datos para el servidor de Pruebas:

URL de prueba: http://187.189.78.196:54637/wsTransactions.asmx?WSDL
Servicio: wsTransactions

Parámetros de Entrada: XML que contiene los parámetros que serán validados en el servicio,
las pruebas se realizaran únicamente con los siguientes códigos de producto:

$30=A030 $50=A050 $100=A100 $200=A200

Usuario: PRUEBA0000
Password: 432143

Caso Escenario Código Teléfonos Monto

1 Abono a número de teléfono válido 00 6643047287 30
2 Abono a número de teléfono válido 00 6643047287 50
3 Abono a número de teléfono válido 00 6643047287 100
4 Teléfono inválido revisar telefonía 01 6145144055 30
5 Producto no disponible 28 5510105137 11
6 Abono a un teléfono, presentando 09 6643047292 200
desconexión enlace del autorizador

-12-
IMPRESIÓN DE TICKET
Todos los tickets deben de llevar la siguiente información:

En la parte superior:
No. TRANSACCIÓN
No. AUTORIZACIÓN
MONTO
TELÉFONO

Dependiendo del operadora es la información a imprimir para el soporte en caso de algún

problema con el abono celular. Por ejemplo:

TELCEL:
Estimado cliente en caso de presentarse algún problema con su tiempo aire favor de comunicarse a atención a clientes TELCEL *264 desde
su telcel o desde el interior de la república al 01800-710-5687. Vigencia del tiempo aire abonado: 30 Días.

En la parte inferior del ticket va la siguiente información:

Fecha-Hora de la Transacción:
Tienda:
Lo Atendió:

Las instrucciones y forma del ticket están certificadas avaladas por TELCEL, es importante respetar la infor-
mación que contiene.

-13-
 CONCILIACIÓN DE TRANSACCIONES
El archivo de conciliaciones contiene solo las transacciones exitosas realizadas por el integrador entre las
00:00:00 horas y las 23:59:59 el día anterior. Se deberá enviar diariamente vía FTP asignado durante su certifi-
cación con el fin de verificar la correcta aplicación de la venta por ambas partes. En caso de encon- trarse
diferencias se atenderán directamente entre el departamento de conciliación y el integrador para su revisión.
En caso de no enviar el archivo se tomaran todas las transacciones como exitosas y por lo tanto no se
aceptarán reclamaciones de dichas transacciones en días posteriores.

Formato de archivo de entrada

Nombre del archivo:
Generar con el formato: [Usuario]_[Fecha]_TAE_[Diferencia de horario].TXT
Cada campo será separado por guiones bajos.

DESCRIPCIÓN FORMATO VALOR LONGITUD OBSERVACIONES

[Usuario] Variable Variable Usuario de venta al que se le va a

conciliar la venta del mismo así como
de sus hijos.
Ejemplo: Prueba00
[Fecha] ddmmaaaa Variable 8 Fecha que se está conciliando.
dd=día
mm=mes
aaaa=año
[TAE] Valor fijo. TAE 3 Indica que el producto que está
conciliando es tiempo aire
electrónico, cada archivo contiene sólo
un producto que se estará conciliando
y debe estar identificado, en este caso,
siempre se indicará el valor fijo de TAE.

-14-
DESCRIPCIÓN FORMATO VALOR LONGITUD OBSERVACIONES

[Diferencia de horario] Variable Hasta 2 Diferencia de horario para

ajustar zonas horarias.
Ejemplo:
a) -1 UTC -5 (Horario del centro)
b) 0 UTC -6 (Horario de Chihuahaua)
c) +1 UTC -7 (Horario Baja California)

Las transacciones que se realizazon en

Cd. de México (-1 UTC -5 Horario del centro)
deberán indicarse con una diferencia de -1
ya que van adelante una hora respecto a
Chihuahua. En el caso de transacciones que
se hayan realizado en Chihuahua
(0 UTC -6 horario de Chihuahua)
deberán indicar 0 en su diferencia de
horario.
Extensión .txt. 4 Extensión del archivo enviado.

Ejemplo de nombre del archivo:

Prueba000_16022015_TAE_-1.txt

Formato del contenido del archivo:

Cabecero:

DESCRIPCIÓN FORMATO VALOR INICIO LONGITUD OBSERVACIONES

Cabecero Valor fijo. HDR 1 3 Cabecero del archivo,

HDR es un identificador
y debe indicarse como
valor fijo.
Fecha ddmmaaaa Variable 4 8 Fecha que se está
conciliando.
dd=día
mm=mes
aaaa=año
Ejemplo:16022016

Ejemplo del encabezado del archivo:

HDR16022015

-15-
 Detalle:

DESCRIPCIÓN FORMATO VALOR INICIO LONGITUD OBSERVACIONES

Número Telefónico Variable 1 10 Número telefónico al

que se recargó tiempo
aire incluyendo la clave
lada.
Ejemplo: 6566792512
Folio de proveedor Variable 11 10 Número de autorización
de la venta de tiempo
aire.
Justificando con ceros a
la izquierda cuando la
longitud sea menor.
Ejemplos:
a)1023456789
b)0000102348
Fecha ddmmaaaa Variable 21 8 Fecha de la venta de la
transacción, que debe
coincidir con la fecha del
encabezado.
dd=día
mm=mes
aaaa=año
Ejemplo:16022015
Monto a abonar Variable 29 4 Monto abonado sin
decimales.
Justificando con ceros a
la izquierda cuando la
longitud sea menor.
Ejemplos:
a)0500
(para una recarga de
quinientos pesos)
b)0020
(para una recarga de
veinte pesos)

Ejemplo de detalles del archivo:

65637399320000434486160220150030
65666985930000104548160220150020
65630682980000814837160220150020

-16-
Ejemplo de un archivo con el formato aplicado:

Fecha de conciliación

HDR

Número de teléfono Recarga

al que se recarga

Folio de venta Fecha de transacción

-17-