Cupones

Endpoints para gestión de cupones de descuento y beneficios.

Listar Cupones

GET /api/coupons

Retorna una lista paginada de cupones con opciones de filtro. Los resultados están limitados a un máximo de 100 cupones por solicitud. Funciona con integraciones de franquicia y empresa.

Casos de uso:

• Consultar cupones emitidos
• Generar informes de utilización
• Monitorear cupones por vencer

Parámetros de Query

Parámetro	Tipo	Obligatorio	Descripción
date_start	string	Sí	Fecha de inicio para filtrar por fecha de creación (YYYY-MM-DD)
date_end	string	Sí	Fecha de fin para filtrar por fecha de creación (YYYY-MM-DD)
date_of_use_start	string	No	Fecha de inicio para filtrar por fecha de uso (YYYY-MM-DD)
date_of_use_end	string	No	Fecha de fin para filtrar por fecha de uso (YYYY-MM-DD)
expiration_date_start	string	No	Fecha de inicio para filtrar por fecha de expiración (YYYY-MM-DD)
expiration_date_end	string	No	Fecha de fin para filtrar por fecha de expiración (YYYY-MM-DD)
coupon_status	string	No	Estado del cupón: Utilizado, No Utilizado, Vencido, Por Vencer
limit	integer	Sí	Número de cupones por solicitud (máximo 100)
offset	integer	Sí	Número de cupones a omitir (mínimo 1)
search	string	No	Término de búsqueda por código o información del cliente
order_column	string	Sí	Columna para ordenación (ej: created_at)
order_type	string	Sí	Dirección de ordenación: ASC o DESC
module	string	Sí	Contexto del módulo: premiado o falae

Ejemplo de Solicitud

curl -X GET "https://api-b2s.experienciab2s.com/api/coupons?date_start=2024-01-01&date_end=2024-12-31&limit=10&offset=1&order_column=created_at&order_type=DESC&module=falae" \
     -H "Authorization: Bearer SU_TOKEN"

Respuesta Exitosa (200)

{
  "limit": 10,
  "offset": 1,
  "total": 45,
  "coupons": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "code": "WELCOME2024",
      "status": true,
      "date_of_use": "2024-03-15",
      "expiration_date": "2024-12-31",
      "created_at": "2024-01-15T10:30:00.000Z",
      "bonus": {
        "id": "bonus-uuid",
        "name": "5% Cashback",
        "type": "answer"
      },
      "client": {
        "id": "client-uuid",
        "name": "Juan García",
        "email": "juan@example.com",
        "phone": "(11) 99999-9999"
      }
    }
  ]
}

Tipos de Bonus Disponibles

Tipo	Descripción
answer	Respuesta de encuesta
birthday	Cumpleaños
default	Predeterminado
create	Creación
fidelityProgram	Programa de fidelidad
prizeDraw	Sorteo
marketing	Marketing
roulette	Ruleta
winning_registration_roulette	Registro ganador de ruleta
infinity	Infinito

---

Buscar Cupones de un Cliente

GET /api/coupons/clients/{company_id}

Retorna una lista de cupones vinculados a un cliente específico, utilizando teléfono, email o CPF como criterio de búsqueda. Es necesario informar el company_id en la ruta de la solicitud.

Casos de uso:

• Consultar cupones de un cliente en atención
• Verificar beneficios disponibles
• Validar cupón antes del canje

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
company_id	string	Sí	ID de la empresa

Parámetros de Query

Parámetro	Tipo	Obligatorio	Descripción
phone	string	No*	Teléfono en formato internacional E.164 (ej: 551199999999)
email	string	No*	Dirección de email del cliente
cpf	string	No*	CPF del cliente en formato 000.000.000-00

Nota: Al menos un parámetro de búsqueda (phone, email o cpf) debe ser proporcionado.

Ejemplo de Solicitud

curl -X GET "https://api-b2s.experienciab2s.com/api/coupons/clients/103a525c-0ce3-4182-a504-aad595425233?email=cliente@ejemplo.com" \
     -H "Authorization: Bearer SU_TOKEN"

Respuesta Exitosa (200)

[
  {
    "id": "103a525c-0ce3-4182-a504-aad595425233",
    "status": true,
    "expiration_date": "2024-12-31",
    "date_of_use": "2024-05-10",
    "created_at": "2024-01-01T12:00:00.000Z",
    "code": "ABCDEF123",
    "bonus": {
      "name": "5% Cashback"
    }
  },
  {
    "id": "303a525c-0ce3-4182-a504-aad595425233",
    "status": false,
    "expiration_date": "2024-11-30",
    "date_of_use": null,
    "created_at": "2024-02-15",
    "code": "XYZ789",
    "bonus": {
      "name": "10% Cashback"
    }
  }
]

Estructura de la Respuesta

Campo	Tipo	Descripción
id	string	ID único del cupón
code	string	Código del cupón
status	boolean	true = utilizado, false = no utilizado
expiration_date	string	Fecha de expiración
date_of_use	string	Fecha de utilización (null si no usado)
created_at	string	Fecha de creación
bonus.name	string	Nombre del beneficio

Códigos de Respuesta

Código	Descripción
200	Cupones encontrados
400	Parámetros inválidos
401	Token ausente o inválido
404	Cliente no encontrado

---

Marcar Cupón como Utilizado

PATCH /api/coupons/status/{id}

Actualiza el estado de un cupón, marcándolo como utilizado. El sistema valida si el cupón existe, si no fue utilizado anteriormente y si no está expirado (fecha de expiración debe ser mayor a 3 horas del horario actual).

Validaciones automáticas:

• Si el cupón existe
• Si no fue utilizado anteriormente
• Si todavía está dentro de la validez (al menos 3 horas antes de la expiración)

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	Sí	ID único del cupón a ser actualizado

Ejemplo de Solicitud

curl -X PATCH "https://api-b2s.experienciab2s.com/api/coupons/status/abc123-cupon-id" \
     -H "Authorization: Bearer SU_TOKEN"

Respuesta Exitosa (204)

El estado del cupón fue actualizado exitosamente. Ningún contenido es retornado en la respuesta.

Respuestas de Error (400)

{
  "status": "error",
  "message": "Coupon already used"
}

{
  "status": "error",
  "message": "Coupon expired"
}

Códigos de Respuesta

Código	Descripción
204	Cupón actualizado exitosamente
400	Cupón ya utilizado o expirado
401	Token ausente o inválido
404	Cupón no encontrado