Documentación para desarrolladores

Integra Redimly a tu punto de venta.

Una API REST simple para crear cupones, generar el pase de Apple Wallet y confirmar canjes desde tu propio sistema.

Base URL https://app.redimly.com

Introducción

Todas las respuestas son JSON. Los endpoints públicos (los que usan tus clientes finales) no requieren autenticación; los de /api/dashboard requieren el token de tu negocio.

Los intentos de login están limitados a 10 por 15 minutos por IP, y el registro a 20 por hora — si integras un flujo automatizado de alta de cuentas, ten esto en cuenta.

Autenticación

Cada negocio tiene su propia cuenta. Obtén un token con /api/auth/login y envíalo en cada request autenticado como Authorization: Bearer <token>. El token expira a los 7 días.

POST /api/auth/register Sin auth

Crea la cuenta de un negocio nuevo.

Request
{ "businessName": "Café Andina", "email": "hola@cafeandina.com", "password": "mínimo 8 caracteres" }
Response 201
{ "token": "eyJhbGciOiJIUzI1NiIs...", "business": { "id": "...", "name": "Café Andina", "email": "...", "role": "BUSINESS" } }
POST /api/auth/login Sin auth

Inicia sesión con email y contraseña.

Request
{ "email": "hola@cafeandina.com", "password": "..." }
Response 200
{ "token": "...", "business": { "id": "...", "name": "...", "email": "...", "role": "BUSINESS" } }
GET /api/auth/me Requiere token

Datos del negocio autenticado.

Response 200
{ "id": "...", "name": "...", "email": "...", "logoUrl": null, "role": "BUSINESS" }

Cupones

Los cupones se crean desde el panel de negocio. Estos endpoints son públicos — los usa la landing de reclamo que ve tu cliente final.

GET /api/coupons/:id Sin auth

Detalle público de un cupón, para renderizar la landing de reclamo.

Response 200
{ "id": "...", "title": "20% de descuento en tu compra", "description": "...", "discountText": "20% OFF", "validFrom": "2026-09-13T00:00:00.000Z", "validUntil": "2026-10-13T00:00:00.000Z", "active": true, "businessName": "Café Andina", "businessLogoUrl": null }
POST /api/coupons/:id/claim Sin auth

Un cliente final reclama el cupón — crea el canje y deja listo el pase para descargar. Requiere customerName y al menos customerEmail o customerPhone. Si el cupón tiene maxRedemptions, responde 410 una vez agotado.

Request
{ "customerName": "Ana Torres", "customerEmail": "ana@correo.com" }
Response 201
{ "redemptionId": "a0ca99a2-...", "downloadUrl": "/api/pass/a0ca99a2-....pkpass" }
Response 410 (agotado)
{ "error": "Este cupón alcanzó su límite de unidades disponibles" }
GET /api/pass/:redemptionId.pkpass Sin auth

Descarga el .pkpass firmado para agregar a Apple Wallet (o un archivo de ejemplo si el negocio todavía no configuró certificados de Apple).

Canjes

Usados por la pantalla de escaneo del negocio (/scan.html) al momento de canjear un cupón en el mostrador.

GET /api/redemptions/:qrCode Sin auth

Estado del canje antes de confirmarlo — para mostrarle al negocio si el cupón es válido antes de canjear.

Response 200
{ "status": "valid", // también puede ser: "already_redeemed" | "expired" | "not_found" "coupon": { "title": "...", "discountText": "20% OFF", "businessName": "...", "validUntil": "..." }, "customerName": "Ana Torres", "redeemedAt": null }
POST /api/redemptions/:qrCode/redeem Sin auth

Confirma el canje. Falla si el QR ya fue usado o si el cupón venció — un QR, un solo canje.

Response 200
{ "status": "redeemed", "redeemedAt": "2026-09-13T13:00:00.000Z" }
Response 409
{ "error": "Este cupón ya fue canjeado", "status": "already_redeemed" }
GET /api/redemptions/:redemptionId/qrcode.png Sin auth

Imagen PNG del código QR de un canje, además del barcode nativo dentro del .pkpass.

Panel de negocio

Requieren Authorization: Bearer <token>. Cada negocio solo ve y modifica sus propios cupones — nunca los de otro.

GET/api/dashboard/summaryRequiere token

Cupones activos, reclamos, canjes y tasa de canje de tu negocio.

GET/api/dashboard/couponsRequiere token

Lista de tus cupones con conteos de reclamos y canjes.

POST/api/dashboard/couponsRequiere token

Crea un cupón para tu negocio.

Request
{ "title": "20% de descuento en tu compra", "discountText": "20% OFF", "description": "Válido en toda la tienda", "validFrom": "2026-09-13", "validUntil": "2026-10-13" }
GET/api/dashboard/coupons/:idRequiere token

Detalle de un cupón propio, con la lista completa de reclamos.

PATCH/api/dashboard/coupons/:idRequiere token

Edita cualquier campo del cupón, o actívalo/desactívalo con { "active": false }.

Guía de integración

El flujo completo para conectar Redimly a tu punto de venta, de punta a punta.

  1. Crea la cuenta de tu negocio Desde /dashboard/register.html, o vía POST /api/auth/register si lo haces desde tu propio sistema. Guarda el token que te devuelve.
  2. Crea un cupón Llama a POST /api/dashboard/coupons con el token, o créalo a mano desde el panel. Cada cupón tiene su propio id.
  3. Comparte el link de reclamo El link público es https://app.redimly.com/claim.html?couponId=<id> — compártelo por WhatsApp, redes o tu propia web. No requiere autenticación.
  4. El cliente reclama y agrega el cupón a Wallet La landing pública llama a POST /api/coupons/:id/claim, genera el .pkpass, y el cliente lo guarda en su iPhone con un QR único.
  5. En el mostrador, escanea y confirma Tu equipo usa /scan.html (o tu propia integración con GET /api/redemptions/:qrCode + POST /api/redemptions/:qrCode/redeem) para validar y canjear. El sistema bloquea un segundo intento sobre el mismo QR.

Errores

Todos los errores tienen la forma { "error": "mensaje" }. Códigos que puedes recibir:

CódigoCuándo
400Faltan campos requeridos o el valor no es válido
401Token ausente, inválido o expirado; credenciales incorrectas
403Cuenta suspendida, o sin permisos para la acción
404El cupón, canje o negocio no existe
409Conflicto — ej. un QR que ya fue canjeado, o email ya registrado
410El cupón alcanzó su límite de unidades disponibles (maxRedemptions)
429Demasiados intentos de login/registro, o de generación de imágenes, desde la misma cuenta/IP
500Error interno — si lo ves de forma consistente, contáctanos