Ir al contenido
Documentación de Connecto
connecto.lat
API para desarrolladoresReferencia

Cupones de descuento (validar y canjear)

Para tiendas y carritos externos: comprueba un código de cupón contra el carrito y devuelve el descuento, lo canjea cuando se paga el pedido (sin pasarse del límite de usos) y lo libera si el pedido se cancela.

Permisos#

PermisoPara qué sirveTipo
cupones:validarValidar cupones y calcular su descuento (no los gasta)lectura
cupones:canjearCanjear y liberar cuponesescritura

Endpoints#

GET /cupones/consultar#

Solo CARGA el cupón por su código: devuelve cómo está configurado (tipo y valor, tope, vigencia, usos, límites, mínimos, combinable, productos incluidos y excluidos y su estado). No lo valida contra un carrito, no calcula descuentos y no gasta usos. Responde 404 si el código no existe.

Permiso: cupones:validar · lectura

Parámetros de la consulta#

ParámetroDescripción
codigoel código del cupón (no distingue mayúsculas)
Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar?codigo=valor" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar?codigo=valor", {
  method: "GET",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar?codigo=valor");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);

POST /cupones/consultar#

Lo mismo que el GET, con el código en el cuerpo (JSON).

Permiso: cupones:validar · lectura

Cuerpo (JSON)#

CampoDescripción
codigoel código del cupón
Ejemplo de cuerpo
{
  "codigo": "BIENVENIDA10"
}
Ejemplo en curl
curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"BIENVENIDA10"}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar", {
  method: "POST",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "codigo": "BIENVENIDA10"
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'codigo' => 'BIENVENIDA10',
)),
]);
$datos = json_decode(curl_exec($ch), true);

POST /cupones/validar#

Comprueba si el código se puede usar con este comprador y este carrito y calcula el descuento. NO gasta el cupón: llámalo cada vez que el cliente cambie el carrito. Un cupón que no se puede usar responde 200 con valido=false y un «motivo» (no_existe, inactivo, no_iniciado, vencido, agotado, limite_contacto, contacto_no_elegible, contacto_requerido, no_es_primera_compra, no_combinable, sin_productos_elegibles, monto_minimo, cantidad_minima…) y un «mensaje» listo para mostrar.

Permiso: cupones:validar · lectura

Cuerpo (JSON)#

CampoDescripción
codigoel código del cupón (no distingue mayúsculas)
contactoquién compra: {"id": 123} o {"email": "..."} o {"telefono": "..."} o {"numero_documento": "..."} (necesario si el cupón tiene límite por contacto, es para contactos concretos o es de primera compra)
itemsel carrito: lista de {"producto_id", "precio_id" (la referencia), "referencia", "cantidad", "precio"?}. Basta producto_id, precio_id o referencia; el precio sale del catálogo salvo que lo envíes. Necesario para cupones de porcentaje.
codigos_aplicadosotros cupones que el carrito ya tiene (solo se pueden sumar los marcados como combinables)
Ejemplo de cuerpo
{
  "codigo": "BIENVENIDA10",
  "contacto": {
    "email": "[email protected]"
  },
  "items": [
    {
      "producto_id": 12,
      "precio_id": 30,
      "cantidad": 2
    }
  ]
}
Ejemplo en curl
curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/validar" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"BIENVENIDA10","contacto":{"email":"[email protected]"},"items":[{"producto_id":12,"precio_id":30,"cantidad":2}]}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/validar", {
  method: "POST",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "codigo": "BIENVENIDA10",
    "contacto": {
        "email": "[email protected]"
    },
    "items": [
        {
            "producto_id": 12,
            "precio_id": 30,
            "cantidad": 2
        }
    ]
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/validar");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'codigo' => 'BIENVENIDA10',
  'contacto' => 
  array (
    'email' => '[email protected]',
  ),
  'items' => 
  array (
    0 => 
    array (
      'producto_id' => 12,
      'precio_id' => 30,
      'cantidad' => 2,
    ),
  ),
)),
]);
$datos = json_decode(curl_exec($ch), true);

POST /cupones/canjear#

Gasta un uso del cupón cuando el pedido se confirma o se paga. Vuelve a validar todas las reglas y es seguro con compras simultáneas (nunca supera el límite de usos). Es idempotente: repetir la llamada con la misma «referencia_externa» devuelve el mismo canje sin gastar otro uso.

Permiso: cupones:canjear · escritura

Cuerpo (JSON)#

CampoDescripción
codigoel código del cupón
referencia_externaobligatoria: el número de pedido de tu tienda
contactoigual que en validar
itemsigual que en validar
codigos_aplicadosigual que en validar
pedido_idopcional: id del pedido en Connecto, si lo creaste por la API de pedidos
Ejemplo de cuerpo
{
  "referencia_externa": "WEB-1001",
  "codigo": "BIENVENIDA10",
  "contacto": {
    "email": "[email protected]"
  },
  "items": [
    {
      "producto_id": 12,
      "precio_id": 30,
      "cantidad": 2
    }
  ]
}
Ejemplo en curl
curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/canjear" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"referencia_externa":"WEB-1001","codigo":"BIENVENIDA10","contacto":{"email":"[email protected]"},"items":[{"producto_id":12,"precio_id":30,"cantidad":2}]}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/canjear", {
  method: "POST",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "referencia_externa": "WEB-1001",
    "codigo": "BIENVENIDA10",
    "contacto": {
        "email": "[email protected]"
    },
    "items": [
        {
            "producto_id": 12,
            "precio_id": 30,
            "cantidad": 2
        }
    ]
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/canjear");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'referencia_externa' => 'WEB-1001',
  'codigo' => 'BIENVENIDA10',
  'contacto' => 
  array (
    'email' => '[email protected]',
  ),
  'items' => 
  array (
    0 => 
    array (
      'producto_id' => 12,
      'precio_id' => 30,
      'cantidad' => 2,
    ),
  ),
)),
]);
$datos = json_decode(curl_exec($ch), true);

POST /cupones/liberar#

Devuelve el uso del cupón (pedido cancelado, pago fallido). Idempotente.

Permiso: cupones:canjear · escritura

Cuerpo (JSON)#

CampoDescripción
codigoel código del cupón
referencia_externala misma referencia con la que se canjeó
Ejemplo de cuerpo
{
  "codigo": "BIENVENIDA10",
  "referencia_externa": "WEB-1001"
}
Ejemplo en curl
curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/liberar" \
  -H "Authorization: Bearer cnx_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"BIENVENIDA10","referencia_externa":"WEB-1001"}'
Ejemplo en javascript
const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/liberar", {
  method: "POST",
  headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "codigo": "BIENVENIDA10",
    "referencia_externa": "WEB-1001"
})
});
const datos = await respuesta.json();
Ejemplo en php
$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/liberar");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(array (
  'codigo' => 'BIENVENIDA10',
  'referencia_externa' => 'WEB-1001',
)),
]);
$datos = json_decode(curl_exec($ch), true);

Respuesta#

validar: {"datos": {"valido": true, "codigo", "tipo": "pct|envio", "valor", "descuento" (USD), "envio_gratis", "subtotal_elegible", "lineas": [{"indice", "elegible", "descuento"}], "combinable", "vence_at", "usos_restantes"}} o {"valido": false, "motivo", "mensaje"}. canjear: {"datos": {"canjeado": true, "uso_id", "descuento", "envio_gratis", "repetido"}}. Si el módulo de cupones está apagado: error 503 «modulo_apagado».

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