Documentación API – Recargas Alistae

Referencia técnica oficial para la integración de distribución transaccional de saldo y tiempo aire a través de nuestra API RESTful.

Objetivo

Este documento está dirigido a ti, como integrador. Aquí encontrarás toda la información técnica necesaria para conectarte y consumir saldo o tiempo aire desde nuestra plataforma B2B Alistae de forma automatizada, utilizando servicios web mediante nuestra API REST.

Flujo de Recarga

Las transacciones a través de la API siguen un modelo estricto diseñado para garantizar la solidez y consistencia en el saldo. A continuación, te explicamos cómo debes operar el ciclo de vida de una recarga:

  1. 1
    Transacción Inicial: Realiza la solicitud de recarga utilizando el método doTransaction.
  2. 2
    Validación de Respuesta: Analiza el JSON de respuesta. Debes validar el campo code para confirmar el resultado final de la transacción. Un code: "00" representa una transacción exitosa; cualquier otro código te indica que la recarga no fue exitosa. (Puedes consultar qué significa cada código utilizando el método getCodes).
  3. 3
    Consideraciones de Tiempo (Timeout): El tiempo compromiso para recibir una respuesta es de 60 segundos. Si llegas a los 59 segundos y aún no logras obtener respuesta, debes lanzar inmediatamente una consulta solicitando el estado real con el método query. Al enviar esta consulta, da por terminada la transacción original en tu sistema sin importar su resultado. Si sigues sin obtener una respuesta tras usar el método query, te recomendamos reintentar la recarga.
[doTransaction] ──> (Espera de respuesta) ──(Respuesta recibida)──> [Validar 'code'] | | | +── code = "00" -> Transacción Exitosa | └── Otros -> Error (Sin respuesta tras 59 segundos) | v [query] ────────> (Finalizar transacción local) | └── (Aún sin respuesta) -> Sugerencia: Reintentar

Autenticación y Credenciales

admin_panel_settings

Todas las peticiones a la API de Alistae requieren tus datos asignados para autenticarse, los cuales deben viajar explícitos dentro de cada esquema JSON que envíes. En un entorno de pruebas utilizarás:

  • personuser: APIDev
  • keypassword: 123456 (Debe enviarse encriptada en MD5 como e10adc3949ba59abbe56e057f20f883e)
  • vpn_keyShared Key: API (Empleada para componer el identificador de la transacción).

Métodos de la API

doTransaction

Este método es el encargado de procesar la solicitud de recarga.

POST https://api.alistae.com/api0001/customer/doTransaction

Parámetros de Entrada

Campo Tipo Longitud Descripción
id String 30 Identificador de tu cliente para cada transacción. Este valor debe ser único en el día. Se compone por tu SharedKey (proporcionada en tus accesos) + el ID del cliente. (Ej: ALS00020190101ABC).
user String 20 El usuario proporcionado por Alistae en tus accesos.
password String 20 Tu contraseña asignada encriptada estricamete en MD5.
sku String 20 SKU único del producto o servicio a recargar.
reference String 20 Teléfono o referencia a la cual se asignará la transacción.
amount Number 10 Monto a cobrar. En el caso de contratar un servicio, debes indicarlo aquí.

upload Request 

{ 
  "user": "APIDev", 
  "password": "e10adc3949ba59abbe56e057f20f883e", 
  "id": "ALS0047", 
  "sku": "TAE0100", 
  "reference": "5555555555", 
  "amount": "0.0" 
}

download Response 

{ 
  "id": "ALS0041", 
  "product": "TAE050", 
  "amount": "10.0", 
  "transaction": "3005", 
  "description": "Transaccion Exitosa", 
  "timeRequest": "16/08/2019 11:45:48", 
  "branch": "TELCEL", 
  "code": "00", 
  "cost": "10.0", 
  "reference": "5555555555", 
  "auth": "988739" 
}

query

Utilízalo para verificar el estado de una transacción previa. Te resultará vital usarlo si pasan más de 59 segundos tras un doTransaction y no obtienes respuesta.

POST https://api.alistae.com/api0001/customer/query

Parámetros de Entrada

Campo Tipo Longitud Descripción
id String 30 El identificador que enviaste en la transacción de origen a consultar (compuesto de tu SharedKey y tu id). Ej: ALS0890080909.
user String 20 Tu usuario proporcionado por Alistae.
password String 20 Tu contraseña asignada encriptada en MD5.

upload Request 

{ 
  "user": "APIDev", 
  "password": "e10adc3949ba59abbe56e057f20f883e", 
  "id": "ALS0304" 
}

download Response 

{ 
  "id": "ALS0041", 
  "product": "TAE100", 
  "amount": "100.0", 
  "transaction": "530", 
  "description": "Transaccion Exitosa", 
  "timeRequest": "23/05/2020 17:03:40", 
  "branch": "TELCEL", 
  "code": "00", 
  "cost": "10.0", 
  "reference": "5555555555", 
  "auth": "987633" 
}

balance

Emplea este método para obtener el saldo que tienes disponible en tu bolsa.

POST https://api.alistae.com/api0001/customer/balance

Parámetros de Entrada

Campo Tipo Longitud Descripción
user String 20 Tu usuario proporcionado.
password String 20 Tu contraseña asignada encriptada en MD5.

upload Request 

{ 
  "user": "APIDev", 
  "password": "e10adc3949ba59abbe56e057f20f883e" 
}

download Response 

{ 
  "product": "Balance", 
  "balance": "8760.0", 
  "date": "23/07/2019 10:13:34" 
}

getProducts

Facilita tu integración obteniendo la matriz actualizada de todos los productos y servicios aceptados listos para transaccionar.

GET https://api.alistae.com/api0001/customer/getProducts
info

Dado que es un método de consulta general GET, no requiere enviar parámetros de entrada. Solo invoca la URL.

Estructura de la Respuesta

Campo Longitud Descripción
amount 30 Monto transaccional del producto ofrecido.
description - Texto explicativo que describe el producto comercialmente.
branch 20 Identificador asociado de la Marca / Carrier / Proveedor al que pertenece el producto.
sku 20 Código único del producto o SKU necesario para enviarse en tus transacciones doTransaction.

download Response (Ejemplo) 

[ 
  { "amount":"5", "description":"Internet 5", "branch":"TELCEL", "sku":"INT5" }, 
  { "amount":"10", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"ALO010" }, 
  { "amount":"10", "description":"Tiempo Aire Electronico", "branch":"TELCEL", "sku":"TAE010" }, 
  { "amount":"20", "description":"Paquete Amigo 20", "branch":"TELCEL", "sku":"PA20" }, 
  { "amount":"20", "description":"Internet 20", "branch":"TELCEL", "sku":"INT20" }, 
  { "amount":"20", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE020" }, 
  { "amount":"20", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"ALO020" }, 
  { "amount":"30", "description":"Internet 30", "branch":"TELCEL", "sku":"INT30" }, 
  { "amount":"30", "description":"Paquete Amigo 30", "branch":"TELCEL", "sku":"PA30" }, 
  { "amount":"30", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"ILIM030" }, 
  { "amount":"30", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"ALO030" }, 
  { "amount":"30", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE030" }, 
  { "amount":"50", "description":"Amigo Entretenimiento", "branch":"TELCEL", "sku":"AEN050" }, 
  { "amount":"50", "description":"Paquete Amigo 50", "branch":"TELCEL", "sku":"PA50" }, 
  { "amount":"50", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"ALO050" }, 
  { "amount":"50", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE050" }, 
  { "amount":"50", "description":"Internet 50", "branch":"TELCEL", "sku":"INT50" }, 
  { "amount":"80", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE080" }, 
  { "amount":"80", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"PA80" }, 
  { "amount":"100", "description":"Internet 100", "branch":"TELCEL", "sku":"INT100" }, 
  { "amount":"100", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE100" }, 
  { "amount":"100", "description":"Paquete Amigo 100", "branch":"TELCEL", "sku":"PA100" }, 
  { "amount":"100", "description":"Tiempo Aire Electronico", "branch":"TELCEL", "sku":"ALO100" }, 
  { "amount":"100", "description":"Amigo Entretenimiento", "branch":"TELCEL", "sku":"AEN100" }, 
  { "amount":"150", "description":"Paquete Amigo 150", "branch":"TELCEL", "sku":"PA150" }, 
  { "amount":"150", "description":"Internet 150", "branch":"TELCEL", "sku":"INT150" }, 
  { "amount":"150", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE150" }, 
  { "amount":"150", "description":"Tiempo Aire Electronico", "branch":"TELCEL", "sku":"ALO150" }, 
  { "amount":"200", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE200" }, 
  { "amount":"200", "description":"Paquete Amigo 200", "branch":"TELCEL", "sku":"PA200" }, 
  { "amount":"200", "description":"Tiempo Aire Electronico", "branch":"TELCEL", "sku":"ALO200" }, 
  { "amount":"200", "description":"Internet 200", "branch":"TELCEL", "sku":"INT200" }, 
  { "amount":"300", "description":"Paquete Amigo 300", "branch":"TELCEL", "sku":"PA300" }, 
  { "amount":"300", "description":"Internet 300", "branch":"TELCEL", "sku":"INT300" }, 
  { "amount":"300", "description":"Tiempo Aire Electronico", "branch":"TELCEL", "sku":"ALO300" }, 
  { "amount":"300", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE300" }, 
  { "amount":"500", "description":"Internet 500", "branch":"TELCEL", "sku":"INT500" }, 
  { "amount":"500", "description":"Timepo Aire Electronico", "branch":"TELCEL", "sku":"TAE500" }, 
  { "amount":"500", "description":"Tiempo Aire Electronico", "branch":"TELCEL", "sku":"ALO500" }, 
  { "amount":"500", "description":"Paquete Amigo 500", "branch":"TELCEL", "sku":"PA500" } 
]

getCodes

Solicita el catálogo centralizado de códigos de repuesta emitidos. Dependerás de este catálogo para determinar lógicamente si el valor del atributo code que recibes dictamina alguna acción adicional (como informar a tu usuario de crédito insuficiente o rechazos).

GET https://api.alistae.com/api0001/customer/getCodes
info

Este método tampoco requiere enviar parámetros de entrada.

Estructura de la Respuesta

Campo Longitud Descripción
code 30 El código que la API devuelve durante en sus respuestas.
description - Explicación o definición en sistema del código reportado.

download Response (Ejemplo) 

[
  {"code":"00", "description":"Transaccion Exitosa"},
  {"code":"01", "description":"Referencia/Teléfono no soporta el servicio"},
  {"code":"02", "description":"Destino no disponible"},
  {"code":"03", "description":"Producto/Monto no valido"},
  {"code":"04", "description":"Referencia/Teléfono No Susceptible de Activación o Abono"},
  {"code":"05", "description":"Crédito insuficiente"},
  {"code":"06", "description":"Mantenimiento del proveedor en curso"},
  {"code":"07", "description":"Rechazo por tabla de transacciones llena"},
  {"code":"08", "description":"Rechazo por time out interno"},
  {"code":"09", "description":"Autorizador no disponible"},
  {"code":"10", "description":"Gestor de servicios no disponible"},
  {"code":"11", "description":"Activación/Abono no permitida"},
  {"code":"12", "description":""},
  {"code":"13", "description":""},
  {"code":"14", "description":"Activación/Abono no permitida"},
  {"code":"18", "description":"Transacción en proceso, realice consulta"},
  {"code":"20", "description":"Transacción no exitosa"},
  {"code":"21", "description":"Transacción no procesada"},
  {"code":"22", "description":"Activación/Abono no permitida"},
  {"code":"23", "description":"Producto no permitido para este método"},
  {"code":"24", "description":"Activación/Abono no permitida"},
  {"code":"30", "description":"Ventas no permitidas"},
  {"code":"32", "description":"Acceso Denegado"},
  {"code":"33", "description":"Session expirada"},
  {"code":"35", "description":"Servicio no disponible"},
  {"code":"37", "description":"Intento de fraude"},
  {"code":"38", "description":"Datos incorrectos"},
  {"code":"40", "description":"Id Transacción ya existente"},
  {"code":"50", "description":"Dato invalido"},
  {"code":"56", "description":"No se puede actualizar el nodo"},
  {"code":"58", "description":"Region/Canal invalido"},
  {"code":"59", "description":"Terminal Invalida"}
]