🎟️ Cupones - API
Vende productos digitales (entradas, vales, códigos de servicio) en Falabella sin preocuparte por la entrega. Tú cargas tus códigos de cupón; cuando un cliente compra, nosotros le enviamos su cupón automáticamente.
Te permite cargar, consultar y administrar tu inventario de cupones desde tu propio sistema. La entrega al cliente final es automática: no necesitas integrar nada adicional para que el cupón llegue.
Beneficios
| Ventaja | Descripción |
|---|---|
| ⚡ Entrega automática | El cliente recibe su cupón por correo y WhatsApp sin intervención manual |
| 📦 Carga masiva | Sube cientos de cupones de una vez, por Excel o JSON |
| 🔄 Stock sincronizado | Al cargar cupones, el stock publicado en Falabella se actualiza |
| 🛡️ Órdenes protegidas | Las órdenes canceladas no consumen cupones |
| 🔒 Seguro | Autenticación con token JWT; solo ves y administras tus propios cupones |
🔄 Cómo funciona
Paso 1️⃣ : Cargas tus cupones
Envías tus códigos asociados a cada SKU de Falabella, por API (JSON) o subiendo un Excel. Cada cupón queda activo y disponible.
Paso 2️⃣ : El cliente compra
Un cliente compra tu producto en Falabella. Verificamos que la orden no esté cancelada.
Paso 3️⃣ : Asignamos un cupón
Tomamos un cupón activo del SKU comprado (siempre el más antiguo primero). Se asigna un cupón por cada unidad comprada.
Paso 4️⃣ : Lo entregamos
El cliente recibe el cupón por correo electrónico, con el diseño de tu marca, y un aviso por WhatsApp. El cupón pasa a inactivo.
Paso 5️⃣ : Confirmamos la entrega
La orden se marca como entregada. Puedes ver el estado de cada cupón consultando la API.
Si se acaban los cupones de un SKU, el cliente recibe un correo informativo y la orden no se marca como entregada. Mantén tu stock cargado.
No se envía nada al cliente y no se consume ningún cupón.
🔐 Autenticación
| Base URL | https://api.homedeliverype.com |
|---|---|
| Token | POST /api/token/ → devuelve access |
| Header | Authorization: Bearer {access} |
POST /api/token/ HTTP/1.1
Host: api.homedeliverype.com
Content-Type: application/json
{
"username": "tu_usuario",
"password": "tu_contraseña"
}
No necesitas enviar tu ID de seller en ninguna llamada: la API lo obtiene del token y solo te muestra tus propios cupones.
📋 Endpoints
| Método | Ruta | Descripción |
|---|---|---|
| POST | /api/seller/cargar-cupon-json | Carga masiva de cupones en JSON |
| POST | /api/seller/cargar-cupon | Carga masiva de cupones con un archivo Excel |
| GET | /api/seller/cupones/ | Lista todos tus cupones |
| GET | /api/seller/cupones/{id}/ | Detalle de un cupón |
| GET | /api/seller/cupones/search/ | Busca por codigo, sku, estado o servicio |
| GET | /api/seller/cupones/estadisticas/ | Totales: cupones, activos, inactivos, SKUs y entregas |
| PUT | /api/seller/cupones/{id}/ | Edita sku, codigo o estado de un cupón |
| DELETE | /api/seller/cupones/{id}/ | Elimina un cupón de forma permanente |
Ejemplo de búsqueda
GET /api/seller/cupones/search/?sku=1594056050447&estado=activo
Authorization: Bearer {access}
📦 Cargar cupones
Opción 1: JSON
POST /api/seller/cargar-cupon-json
Authorization: Bearer {access}
Content-Type: application/json
{
"cupones": [
{
"codigo": "CUPON123",
"sku": "1594056050447",
"servicio": "Entrada General",
"fecha_vencimiento": "2026-12-31"
}
]
}
| Campo | Obligatorio | Descripción |
|---|---|---|
codigo | Sí | Código del cupón que recibirá el cliente |
sku | Sí | SKU de Falabella al que pertenece el cupón |
servicio | No | Nombre comercial del servicio |
fecha_vencimiento | No | Fecha en formato YYYY-MM-DD |
Opción 2: Excel
Envía el archivo como multipart/form-data en el campo file a POST /api/seller/cargar-cupon. Solo se lee la primera hoja.
| Columna | Obligatoria |
|---|---|
codigos | Sí |
numero de sku | Sí |
nombre de servicio | No |
fecha de vencimiento | No |
Respuesta
La respuesta indica cuántos cupones se crearon, cuántos se omitieron por estar duplicados y el detalle de las filas con error:
{
"cupones_creados": 98,
"cupones_duplicados": 2,
"errores_filas": [ ... ]
}
Reglas de carga
- Todo cupón cargado queda en estado
activo. - Si un cupón con el mismo
codigoyskuya existe en tu cuenta, se omite como duplicado; el resto del lote se procesa igual. - Cada
codigodebe ser único en todo el sistema. Si ya está en uso, esa fila se rechaza y aparece enerrores_filas. - Si alguna fila falla, las demás se guardan de todos modos y la respuesta es 207.
🏷️ Estados del cupón
Disponible para ser entregado en la próxima compra del SKU.
Ya fue entregado a un cliente y no se volverá a usar.
📊 Códigos de respuesta HTTP
| Código | Significado |
|---|---|
| 200 | Consulta o edición exitosa |
| 201 | Cupones creados sin errores |
| 207 | Carga parcial: algunas filas tuvieron error (ver errores_filas) |
| 400 | Solicitud inválida (formato o campos incorrectos) |
| 401 | Token ausente, inválido o expirado |
| 404 | El cupón no existe o no pertenece a tu cuenta |
💻 Ejemplos de código
Cada ejemplo hace el flujo completo: obtiene el token, carga cupones en JSON y lista tus cupones. Las credenciales se leen de las variables de entorno HD_USER y HD_PASSWORD; nunca las guardes en el código fuente.
PHP (cURL)
<?php
const BASE_URL = 'https://api.homedeliverype.com';
function request(string $method, string $path, ?array $body = null, ?string $token = null): array {
$ch = curl_init(BASE_URL . $path);
$headers = ['Content-Type: application/json'];
if ($token) {
$headers[] = "Authorization: Bearer $token";
}
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return [$status, json_decode($response, true)];
}
// 1. Token
[, $auth] = request('POST', '/api/token/', [
'username' => getenv('HD_USER'),
'password' => getenv('HD_PASSWORD'),
]);
$token = $auth['access'];
// 2. Carga de cupones (201 = OK, 207 = carga parcial)
[$status, $result] = request('POST', '/api/seller/cargar-cupon-json', [
'cupones' => [
['codigo' => 'CUPON123', 'sku' => '1594056050447',
'servicio' => 'Entrada General', 'fecha_vencimiento' => '2026-12-31'],
],
], $token);
echo "Carga: HTTP $status\n";
print_r($result);
// 3. Listado
[, $cupones] = request('GET', '/api/seller/cupones/', null, $token);
print_r($cupones);
Java 11+ (HttpClient + Jackson)
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import java.util.Map;
public class CuponesClient {
private static final String BASE_URL = "https://api.homedeliverype.com";
private static final HttpClient http = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(30)).build();
private static final ObjectMapper mapper = new ObjectMapper();
static HttpResponse<String> send(String method, String path, Object body, String token) throws Exception {
HttpRequest.Builder req = HttpRequest.newBuilder(URI.create(BASE_URL + path))
.timeout(Duration.ofSeconds(30))
.header("Content-Type", "application/json");
if (token != null) {
req.header("Authorization", "Bearer " + token);
}
HttpRequest.BodyPublisher publisher = body == null
? HttpRequest.BodyPublishers.noBody()
: HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body));
return http.send(req.method(method, publisher).build(), HttpResponse.BodyHandlers.ofString());
}
public static void main(String[] args) throws Exception {
// 1. Token
var auth = send("POST", "/api/token/", Map.of(
"username", System.getenv("HD_USER"),
"password", System.getenv("HD_PASSWORD")), null);
String token = mapper.readTree(auth.body()).get("access").asText();
// 2. Carga de cupones (201 = OK, 207 = carga parcial)
var carga = send("POST", "/api/seller/cargar-cupon-json", Map.of("cupones", List.of(
Map.of("codigo", "CUPON123", "sku", "1594056050447",
"servicio", "Entrada General", "fecha_vencimiento", "2026-12-31"))), token);
System.out.println("Carga: HTTP " + carga.statusCode() + " " + carga.body());
// 3. Listado
var lista = send("GET", "/api/seller/cupones/", null, token);
JsonNode cupones = mapper.readTree(lista.body());
System.out.println(cupones.toPrettyString());
}
}
C# (.NET 6+)
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
var http = new HttpClient
{
BaseAddress = new Uri("https://api.homedeliverype.com"),
Timeout = TimeSpan.FromSeconds(30)
};
// 1. Token
var authResp = await http.PostAsJsonAsync("/api/token/", new
{
username = Environment.GetEnvironmentVariable("HD_USER"),
password = Environment.GetEnvironmentVariable("HD_PASSWORD")
});
authResp.EnsureSuccessStatusCode();
var auth = await authResp.Content.ReadFromJsonAsync<JsonElement>();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", auth.GetProperty("access").GetString());
// 2. Carga de cupones (201 = OK, 207 = carga parcial)
var carga = await http.PostAsJsonAsync("/api/seller/cargar-cupon-json", new
{
cupones = new[]
{
new { codigo = "CUPON123", sku = "1594056050447",
servicio = "Entrada General", fecha_vencimiento = "2026-12-31" }
}
});
Console.WriteLine($"Carga: HTTP {(int)carga.StatusCode}");
Console.WriteLine(await carga.Content.ReadAsStringAsync());
// 3. Listado
var cupones = await http.GetFromJsonAsync<JsonElement>("/api/seller/cupones/");
Console.WriteLine(cupones);
C++ (libcurl + nlohmann/json)
#include <curl/curl.h>
#include <nlohmann/json.hpp>
#include <cstdlib>
#include <iostream>
#include <string>
using json = nlohmann::json;
const std::string BASE_URL = "https://api.homedeliverype.com";
static size_t write_cb(char* ptr, size_t size, size_t nmemb, void* userdata) {
static_cast<std::string*>(userdata)->append(ptr, size * nmemb);
return size * nmemb;
}
long request(const std::string& method, const std::string& path,
const json* body, const std::string& token, std::string& out) {
CURL* curl = curl_easy_init();
struct curl_slist* headers = curl_slist_append(nullptr, "Content-Type: application/json");
if (!token.empty()) {
headers = curl_slist_append(headers, ("Authorization: Bearer " + token).c_str());
}
std::string payload = body ? body->dump() : "";
curl_easy_setopt(curl, CURLOPT_URL, (BASE_URL + path).c_str());
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, method.c_str());
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 30L);
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &out);
if (body) {
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload.c_str());
}
long status = 0;
if (curl_easy_perform(curl) == CURLE_OK) {
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &status);
}
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return status;
}
int main() {
curl_global_init(CURL_GLOBAL_DEFAULT);
// 1. Token
json creds = {{"username", std::getenv("HD_USER")},
{"password", std::getenv("HD_PASSWORD")}};
std::string resp;
request("POST", "/api/token/", &creds, "", resp);
std::string token = json::parse(resp)["access"];
// 2. Carga de cupones (201 = OK, 207 = carga parcial)
json carga = {{"cupones", {{
{"codigo", "CUPON123"}, {"sku", "1594056050447"},
{"servicio", "Entrada General"}, {"fecha_vencimiento", "2026-12-31"}
}}}};
resp.clear();
long status = request("POST", "/api/seller/cargar-cupon-json", &carga, token, resp);
std::cout << "Carga: HTTP " << status << "\n" << resp << "\n";
// 3. Listado
resp.clear();
request("GET", "/api/seller/cupones/", nullptr, token, resp);
std::cout << json::parse(resp).dump(2) << "\n";
curl_global_cleanup();
}
// Compilar: g++ -std=c++17 cupones.cpp -lcurl -o cupones
❓ Preguntas frecuentes
¿Necesito hacer algo para que el cupón llegue al cliente?
No. Basta con tener cupones activos cargados para el SKU. La entrega por correo y WhatsApp es automática.
¿Qué pasa si se me acaban los cupones?
El cliente recibe un correo informativo y la orden queda pendiente de entrega. Te recomendamos revisar /api/seller/cupones/estadisticas/ con frecuencia y recargar antes de quedarte sin stock.
¿Qué pasa si el cliente compra varias unidades?
Se entrega un cupón por cada unidad comprada.
¿Puedo reutilizar un código de cupón?
No. Cada código es único en el sistema y, una vez entregado, queda inactivo.
¿Cómo sé qué cupones ya se entregaron?
Consulta GET /api/seller/cupones/search/?estado=inactivo.
¿Puedo personalizar el correo que recibe el cliente?
Sí. El correo usa el nombre, colores, imagen y términos y condiciones de tu negocio. Escríbenos para configurarlo.
¿Se actualiza mi stock en Falabella?
Sí, al cargar cupones nuevos se actualiza el stock publicado de los SKUs habilitados. Consulta con nuestro equipo para habilitar tus SKUs.
✅ Checklist de integración
- Credenciales de acceso recibidas
- Token obtenido con
POST /api/token/ - SKUs de Falabella identificados
- Primera carga de cupones realizada (JSON o Excel)
- Respuesta
207manejada (revisarerrores_filas) - Plantilla de correo de tu marca configurada con nuestro equipo
- Monitoreo de stock con
/estadisticas/
📞 Soporte & Contacto
¿Quieres activar el servicio de cupones o tienes dudas con la integración?
api@homedeliverype.com
developers.homedeliverype.com