Canjear el código

La API de canje resuelve dos preguntas en el punto de venta: si el código sigue vigente y el consumo definitivo. Funciona igual para cupones y para giftcards. En las giftcards, el monto no se consulta aquí: ya lo recibiste al registrar la compra.

Entornos

Entorno	Host
Producción	https://n1-loyalty-core-redemption-api.n1co.com
Pruebas	https://n1-loyalty-core-redemption-api.n1co.dev

Toda petición a /api/v1/* requiere el header X-Api-Key con la llave que n1co te entregue. Cada entorno tiene la suya.

Endpoints

Endpoint	Qué hace
POST /api/v1/coupons/validate	Comprueba que el código es utilizable, sin consumirlo.
POST /api/v1/coupons/redeem	Lo consume de forma definitiva.

El consumo es idempotente

Llamar dos veces a redeem con el mismo código no lo descuenta dos veces: la segunda llamada responde un rechazo. Reintentar tras un error de red es seguro.

Petición

POST /api/v1/coupons/validate
X-Api-Key: <tu-llave>
Content-Type: application/json

{ "code": "HPY-SOL-073" }

Respuesta

Ambos endpoints responden HTTP 200 siempre que la petición se haya procesado, incluso cuando el código fue rechazado. Un rechazo es un resultado de negocio, no un error de transporte.

// Aceptado
{ "success": true,  "rejectionCode": null, "message": "Valid coupon" }

// Rechazado
{ "success": false, "rejectionCode": "COUPON_EXPIRED", "message": "The coupon expired on..." }

Programa contra rejectionCode, no contra message

rejectionCode es un identificador estable e independiente del idioma. message es texto en inglés pensado solo para diagnóstico; si necesitas mostrarle algo al cajero en español, tradúcelo de tu lado a partir del código.

Códigos de rechazo

rejectionCode	Qué ocurrió
CODE_NOT_FOUND	El código no existe. Suele ser un error de digitación.
COUPON_EXPIRED	El código venció.
COUPON_LIMIT_REACHED	Ya se canjeó.
COUPON_NOT_YET_ACTIVE	Todavía no inicia su vigencia.
CODE_NOT_IN_TRIGGERED_CAMPAIGN	El código no corresponde a tu comercio.
COUPON_REJECTED_BY_CONDITION	Una condición de la promoción lo bloqueó.
UNKNOWN_REASON	Motivo no reconocido. Trátalo como no válido.

Errores técnicos

Estos sí usan códigos HTTP semánticos y un cuerpo distinto:

{ "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } }

HTTP	error.code	Cuándo
400	INVALID_REQUEST	Falta code o viene vacío.
401	UNAUTHORIZED	El X-Api-Key falta o no es válido.
415	UNSUPPORTED_MEDIA_TYPE	El Content-Type no es application/json.
502	UPSTREAM_ERROR	Falla temporal del servicio.
503	SERVICE_UNAVAILABLE	Servicio no disponible.

Ante 502 o 503, no des la giftcard por canjeada

Son fallas temporales, no rechazos. Reintenta: el consumo es idempotente.

El flujo en caja

1. El cajero digita o escanea el código.
2. Tu sistema lo busca en tu base local, con lo que recibiste en la compra.
3. Llamas a validate para confirmar la vigencia.
4. Según el producto:
   • Cupón: entregas la promoción que representa.
   • Giftcard: la eliges como medio de pago y aplicas el monto que ya tenías guardado. El cajero nunca lo teclea, y cobras el resto por otro medio si hace falta.
5. Llamas a redeem al confirmar la venta.

Si redeem es rechazado, no cierres la venta con ese código

Un rechazo entre los pasos 3 y 5 significa que el código se usó en ese intervalo. Revierte la promoción o el descuento y solicita otro medio de pago.

Cuándo confirmar el canje

Puedes llamar a redeem en el momento de la venta o en lote al cierre del día.

Confirmarlo en el momento es lo más seguro: mientras el canje viva solo en tu sistema, el mismo código puede usarse en dos sucursales antes de que ninguna de las dos lo sepa.

El lote es viable cuando tus cajas operan sin conexión permanente, a cambio de aceptar esa ventana. Si eliges esta modalidad, coordínala con n1co para definir la frecuencia.