Para qué sirve#
Permite que una tienda o carrito de compras externo valide un cupón, lo canjee cuando el pedido se paga y lo libere si el pedido se cancela. Los cupones se crean en Cupones.
Permisos de la credencial: cupones:validar (lectura) y cupones:canjear (escritura; cubre canjear y liberar). También los cubren los comodines «todas las APIs de lectura / escritura».
Quién la habilita: un administrador, en Configuración → APIs y Webhooks (la API viene habilitada). El módulo de Cupones debe estar encendido; si no, responde error modulo_apagado (503).
Endpoints#
| Método | Ruta | Para qué |
|---|---|---|
GET / POST | /api/v1/cupones/consultar | Solo carga el cupón por su código (cómo está configurado). No valida ni aplica nada. |
POST | /api/v1/cupones/validar | Comprueba el código contra el carrito y calcula el descuento. No gasta el cupón. |
POST | /api/v1/cupones/canjear | Gasta un uso al confirmar el pago. Idempotente por referencia_externa. |
POST | /api/v1/cupones/liberar | Devuelve el uso si el pedido se cancela o el pago falla. |
Consultar (solo cargar el cupón)#
Si solo necesitas leer el cupón (por ejemplo para mostrar «10 % hasta el 31 de diciembre» o saber a qué productos aplica) usa consultar: no lo valida contra un carrito ni un comprador, no calcula descuentos y no gasta usos. Usa el permiso cupones:validar.
GET https://crm.tuempresa.com/api/v1/cupones/consultar?codigo=BIENVENIDA10
Authorization: Bearer cnx_TU_LLAVETambién acepta POST con {"codigo": "BIENVENIDA10"}. Respuesta:
{ "datos": { "codigo": "BIENVENIDA10", "nombre": "Bienvenida", "estado": "activo", "activo": true,
"tipo": "pct", "valor": 10, "tope_descuento": 50, "envio_gratis": false,
"inicia_at": null, "vence_at": "2026-12-31T23:59:00-05:00",
"max_usos": 100, "usos": 4, "usos_restantes": 96, "max_usos_contacto": 1,
"monto_minimo": null, "cantidad_minima": null, "solo_primera_compra": false, "combinable": false,
"para_contactos": true, "total_contactos": 1,
"aplica_a_todos_los_productos": false,
"productos_incluidos": [ { "producto_id": 12, "producto": "Curso A", "todas_las_referencias": true },
{ "producto_id": 12, "precio_id": 30, "referencia": "A-PRO" } ],
"productos_excluidos": [ { "categoria_id": 3, "categoria": "Libros" } ] } }Devuelve también los cupones vencidos, agotados o desactivados (mira estado). Si el código no existe responde 404 no_encontrado. No expone la lista de contactos, solo cuántos son. Para saber si el cupón sirve para un comprador y un carrito concretos, usa validar.
Validar#
POST https://crm.tuempresa.com/api/v1/cupones/validar
Authorization: Bearer cnx_TU_LLAVE
Content-Type: application/json
{
"codigo": "BIENVENIDA10",
"contacto": { "email": "[email protected]" },
"items": [ { "producto_id": 12, "precio_id": 30, "cantidad": 2 } ],
"codigos_aplicados": []
}- codigo: no distingue mayúsculas.
- contacto: quién compra:
{"id": 123},{"email": "…"},{"telefono": "…"}o{"numero_documento": "…"}. Es necesario si el cupón tiene límite por contacto (lo normal), es para contactos concretos o es de primera compra. - items: el carrito. Cada línea necesita
producto_id,precio_id(la referencia) oreferencia, ycantidad. El precio sale del catálogo; puedes enviarpreciosi tu tienda cobra otro. Es obligatorio para cupones de porcentaje. - codigos_aplicados: otros cupones que el carrito ya tiene (solo se suman los combinables).
Respuesta cuando el cupón sirve (HTTP 200):
{ "datos": { "valido": true, "codigo": "BIENVENIDA10", "tipo": "pct", "valor": 10, "descuento": 25.0,
"envio_gratis": false, "subtotal_elegible": 250.0,
"lineas": [ { "indice": 0, "elegible": true, "descuento": 25.0 } ],
"combinable": false, "vence_at": "2026-12-31T23:59:00-05:00", "usos_restantes": 96 } }Un cupón que no se puede usar NO es un error HTTP: responde 200 con {"datos": {"valido": false, "motivo": "vencido", "mensaje": "Este cupón ya venció."}}. Muestra el mensaje al comprador; los motivos están en Cupones. Los errores HTTP son solo para datos mal formados (422), módulo apagado (503) o sin permiso (403).
Canjear#
Llámalo cuando el pedido se confirma o se paga, con los mismos datos de validar más la referencia_externa (el número de pedido de tu tienda, obligatoria) y, opcionalmente, pedido_id (el id del pedido en Connecto si lo creaste con la API de pedidos).
{ "codigo": "BIENVENIDA10", "referencia_externa": "WEB-1001",
"contacto": { "email": "[email protected]" }, "items": [ { "producto_id": 12, "precio_id": 30, "cantidad": 2 } ] }- Vuelve a validar todas las reglas y es seguro con compras simultáneas: dos pedidos a la vez nunca superan el límite de usos.
- Es idempotente: repetir la llamada con la misma
referencia_externadevuelve el mismo canje ("repetido": true) sin gastar otro uso, así que puedes reintentar si se cortó la conexión. - Respuesta:
{"datos": {"canjeado": true, "uso_id": 7, "descuento": 25.0, "envio_gratis": false, "repetido": false}}; si no se pudo,{"canjeado": false, "motivo": "…", "mensaje": "…"}.
Liberar#
{ "codigo": "BIENVENIDA10", "referencia_externa": "WEB-1001" }Devuelve el uso (también el de «usos por contacto»). Es idempotente. Respuesta: {"datos": {"liberado": true}}.
Flujo recomendado en el carrito#
- El cliente escribe el código → validar con el carrito actual y muestra el descuento (o el
mensaje). - Si el carrito cambia → validar otra vez.
- Al pagar → canjear con el número de pedido. Si no se pudo canjear, avisa al cliente antes de cobrar.
- Si el pedido se cancela o el pago falla → liberar.
<!-- Fuente: shared/src/Core/Api/CuponesApi.php, shared/src/Core/Api/Catalogo.php, shared/src/Core/Cupones.php -->