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#
| Permiso | Para qué sirve | Tipo |
|---|---|---|
cupones:validar | Validar cupones y calcular su descuento (no los gasta) | lectura |
cupones:canjear | Canjear y liberar cupones | escritura |
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ámetro | Descripción |
|---|---|
codigo | el código del cupón (no distingue mayúsculas) |
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/cupones/consultar?codigo=valor" \
-H "Authorization: Bearer cnx_TU_LLAVE"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();$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)#
| Campo | Descripción |
|---|---|
codigo | el código del cupón |
{
"codigo": "BIENVENIDA10"
}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"}'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();$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)#
| Campo | Descripción |
|---|---|
codigo | el código del cupón (no distingue mayúsculas) |
contacto | quié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) |
items | el 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_aplicados | otros cupones que el carrito ya tiene (solo se pueden sumar los marcados como combinables) |
{
"codigo": "BIENVENIDA10",
"contacto": {
"email": "[email protected]"
},
"items": [
{
"producto_id": 12,
"precio_id": 30,
"cantidad": 2
}
]
}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}]}'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();$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)#
| Campo | Descripción |
|---|---|
codigo | el código del cupón |
referencia_externa | obligatoria: el número de pedido de tu tienda |
contacto | igual que en validar |
items | igual que en validar |
codigos_aplicados | igual que en validar |
pedido_id | opcional: id del pedido en Connecto, si lo creaste por la API de pedidos |
{
"referencia_externa": "WEB-1001",
"codigo": "BIENVENIDA10",
"contacto": {
"email": "[email protected]"
},
"items": [
{
"producto_id": 12,
"precio_id": 30,
"cantidad": 2
}
]
}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}]}'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();$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)#
| Campo | Descripción |
|---|---|
codigo | el código del cupón |
referencia_externa | la misma referencia con la que se canjeó |
{
"codigo": "BIENVENIDA10",
"referencia_externa": "WEB-1001"
}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"}'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();$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».