Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioConfiguración general e IA

API: Cupones de descuento

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étodoRutaPara qué
GET / POST/api/v1/cupones/consultarSolo carga el cupón por su código (cómo está configurado). No valida ni aplica nada.
POST/api/v1/cupones/validarComprueba el código contra el carrito y calcula el descuento. No gasta el cupón.
POST/api/v1/cupones/canjearGasta un uso al confirmar el pago. Idempotente por referencia_externa.
POST/api/v1/cupones/liberarDevuelve 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.

Texto
GET https://crm.tuempresa.com/api/v1/cupones/consultar?codigo=BIENVENIDA10
Authorization: Bearer cnx_TU_LLAVE

También acepta POST con {"codigo": "BIENVENIDA10"}. Respuesta:

Texto
{ "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#

Texto
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) o referencia, y cantidad. El precio sale del catálogo; puedes enviar precio si 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):

Texto
{ "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).

Texto
{ "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_externa devuelve 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#

Texto
{ "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#

  1. El cliente escribe el código → validar con el carrito actual y muestra el descuento (o el mensaje).
  2. Si el carrito cambia → validar otra vez.
  3. Al pagar → canjear con el número de pedido. Si no se pudo canjear, avisa al cliente antes de cobrar.
  4. 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 -->

¿Te fue útil esta página?
Última actualización: 14/11/2026