Recarga REST
Descripción general#
La recogida de datos la realizará la Tienda Virtual, que capturará la información de recarga y los datos de la tarjeta (en caso de recarga con pago) o solo la información de recarga (para realizar una sola recarga).
Y para saber más sobre estas nomenclaturas (Bin, Software Express, Carat, e-Sitef) Leer más
Comunicación#
Para realizar una transacción de Web Service, todas las comunicaciones se realizarán a través de HTTPS / SSL. Es importante que el servidor del comerciante admita un cifrado de al menos 128 bits. El servidor de la tienda debe realizar llamadas a direcciones específicas para transacciones REST.
Se debe llamar a cada servicio utilizando la URL base concatenada del recurso deseado (ver el capítulo referente al servicio que se va a consumir). El método HTTP (GET, POST o PUT) indica la acción esperada en el recurso elegido. A continuación se muestran las URL base dePortal Carat:
URL base de producción:
https://esitef-ec.softwareexpress.com.br/e-sitef
URL base de homologación:
https://esitef-homologacao.softwareexpress.com.br/e-sitef
Todas las llamadas realizadas a los servicios serán respondidas sincrónicamente.
Atención:
Nunca use la IP en lugar del dominio esitef-ec.softwareexpress.com.br. La IP puede cambiar en cualquier momento y sin previo aviso, por lo que es importante utilizar el dominio para acceder a Portal Carat.
Importante:
Además de los parámetros de devolución del servicio descritos en esta especificación, Portal Carat puede devolver otros parámetros sin previo aviso.
Es importante que la aplicación esté preparada para recibir los parámetros desconocidos además de los parámetros ya especificados y simplemente ignorarlos.
Flujo de recarga sin pago#
El flujo de recarga sin pago se puede realizar según el ejemplo de la figura anterior.
El desarrollador debe seguir lo especificado en el documento de integración de Portal Carat y enviar los parámetros:
- Según tamaño y tipo (numérico o alfanumérico);
- Si el campo es obligatorio, condicional u opcional.
En resumen, a continuación se muestra el flujo transaccional de Recarga. Con eso, conviene aclarar algunas dudas, agilizando el proceso de integración con Portal Carat.
- 1 . El flujo comienza cuando la aplicación de la tienda realiza una llamada para iniciar una recarga;
- 1 \ .1. De forma síncrona, Portal Carat realizará un HTTPS_POST en la URL de autenticidad informada por el comerciante y registrada en el backoffice de Portal Carat. El POST enviado contendrá el NIT necesario para proceder con la recarga;
- 1 \ .2. La respuesta de la tienda a POST HTTPS debe ser "200 OK";
- 1 \ .3. La respuesta de Portal Carat a la llamada para iniciar la recarga será un código que indicará éxito (valor
0) o fracaso (valor diferente de0);
- 2. La tienda debe entonces hacer una llamada a listar concesionarios pasando el NIT recibido previamente;
- 2 \ .1. Portal Carat devuelve una lista que contiene los datos del concesionario1;
- 3 . Luego, la tienda debe hacer una llamada para enumerar los datos de la sucursal pasando el código de concesionario elegido, el código de área deseado y el NIT;
- 3 \ .1. Portal Carat devuelve los datos del afiliado, incluidos posibles montos de recarga, períodos de validez, montos de bonificación, entre otros;
- 4 . La tienda debe entonces hacer una llamada para efectuar recarga pasando el NIT, el código del concesionario elegido, el teléfono, el código de área y el valor seleccionado;
- 4 \ .1. Portal Carat inicia la recarga con el operador elegido y devuelve los datos de recarga pendientes de confirmación;
- 5 . La tienda debe inevitablemente hacer una llamada para confirmar la recarga pasando el NIT y un campo que indique si la recarga pendiente debe ser confirmada o deshecha en el operador;
- 5 \ .1. Portal Carat devuelve una respuesta indicando el resultado de confirmar o cancelar la recarga;
Flujo de recarga con pago#
El flujo de recarga con o sin pago es el mismo, con el agregado de que el flujo de pago requiere que los datos de pago se envíen en la llamada efectuar recarga.