Introducción y objetivos

Gift Cards API fue creada con el objetivo de poder canjear los códigos de los bonos en restaurantes, hoteles, clubs, droguerías de Colsubsidio de manera presencial, incluyendo a los Ecommerce de Colsubsidio de manera online.

Qué es Gift Cards API

Gift Cards API es un modelo diseñado para que las empresas puedan generar tarjetas de regalo digitales y ofrecerlas como beneficios a sus empleados. A través de la plataforma, los empleados pueden redimir estas tarjetas de regalo utilizando los puntos asignados.

La API de Gift Cards se creó con el propósito de permitir el seguimiento del CANJE de las tarjetas en sistemas externos, es decir, en las plataformas del proveedor de los servicios o productos asociados a la tarjeta de regalo, brindando así una integración sencilla y eficiente.

Uso de la API de Gift Cards

La API de Gift Cards cuenta con dos funciones principales que permiten gestionar el uso de las tarjetas de manera segura y eficiente: consultar gift card y canjear gift card. Ambas funciones requieren la clave privada (Key) y el código único de la tarjeta (codigo_giftcard) como parámetros obligatorios.
A continuación, se describen las funcionalidades:

Consultar Gift Card:

Esta función permite verificar la información asociada a una Gift Card específica. Es útil para conocer detalles como la vigencia, el estado, el valor disponible, y los datos del usuario asociado.

Parámetros de Entrada:

1. Key: Clave privada para autenticación.
2. codigo_giftcard: Código único de la Gift Card.

Parámetros de Salida:

1. Id_usuario: Representa el identificador único del usuario asociado a la Gift Card.
2. arr_usuario: Contiene información detallada del usuario asociado:
   1. usuario_identificacion: Identificación del usuario.
   2. usuario_nombre: Nombre completo del usuario.
   3. usuario_email: Correo electrónico del usuario.
   4. usuario_tef: Teléfono de contacto del usuario.
3. giftcard_fecha_vencimiento: Indica la fecha de vencimiento de la tarjeta.
4. valor: Representa el valor disponible en la Gift Card.
5. cod_giftcard: Código único que identifica a la Gift Card.
6. id_status: Identificador numérico que indica el estado actual de la Gift Card.
7. des_status: Descripción del estado de la Gift Card (por ejemplo, activa, vencida, redimida, etc.).
8. signature: Firma digital generada para validar la autenticidad de la transacción.

Canjear Gift Card:

Esta función se utiliza para procesar el canje de una Gift Card, registrando que ha sido utilizada y actualizando su estado.

Parámetros de Entrada:

1. Key: Clave privada para autenticación.
2. codigo_giftcard: Código único de la Gift Card.

Parámetros de Salida:

1. cod_giftcard: Código único que identifica a la Gift Card.
2. id_status: Identificador numérico que indica el estado actual de la Gift Card después del canje.
3. des_status: Descripción del estado de la Gift Card tras la operación (por ejemplo, canjeado, error, etc.).
4. signature: Firma digital generada para validar la autenticidad de la transacción.

Integración API de Gift Cards

Se debe tener en cuenta que todos los servicios en esta integración se realizan con el protocolo HTTP POST.

Recomendaciones

Antes de canjear una tarjeta, utiliza la función de consulta para verificar su estado y vigencia, evitando intentos fallidos con tarjetas expiradas o inválidas. Además, siempre realiza las solicitudes mediante HTTPS y registra las transacciones, incluyendo las firmas digitales, para garantizar la trazabilidad y la validación de las operaciones realizadas