🎟️ 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.

¿Qué hace la API de Cupones?
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

VentajaDescripción
⚡ Entrega automáticaEl cliente recibe su cupón por correo y WhatsApp sin intervención manual
📦 Carga masivaSube cientos de cupones de una vez, por Excel o JSON
🔄 Stock sincronizadoAl cargar cupones, el stock publicado en Falabella se actualiza
🛡️ Órdenes protegidasLas órdenes canceladas no consumen cupones
🔒 SeguroAutenticació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.

⚠️ Sin cupones disponibles
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.
❌ Orden cancelada
No se envía nada al cliente y no se consume ningún cupón.

🔐 Autenticación

Base URLhttps://api.homedeliverype.com
TokenPOST /api/token/ → devuelve access
HeaderAuthorization: Bearer {access}
POST /api/token/ HTTP/1.1
Host: api.homedeliverype.com
Content-Type: application/json

{
  "username": "tu_usuario",
  "password": "tu_contraseña"
}
Tu identidad viene del token.
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étodoRutaDescripción
POST/api/seller/cargar-cupon-jsonCarga masiva de cupones en JSON
POST/api/seller/cargar-cuponCarga 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"
    }
  ]
}
CampoObligatorioDescripción
codigoSíCódigo del cupón que recibirá el cliente
skuSíSKU de Falabella al que pertenece el cupón
servicioNoNombre comercial del servicio
fecha_vencimientoNoFecha 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.

ColumnaObligatoria
codigosSí
numero de skuSí
nombre de servicioNo
fecha de vencimientoNo

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 codigo y sku ya existe en tu cuenta, se omite como duplicado; el resto del lote se procesa igual.
  • Cada codigo debe ser único en todo el sistema. Si ya está en uso, esa fila se rechaza y aparece en errores_filas.
  • Si alguna fila falla, las demás se guardan de todos modos y la respuesta es 207.

🏷️ Estados del cupón

✅ activo
Disponible para ser entregado en la próxima compra del SKU.
⛔ inactivo
Ya fue entregado a un cliente y no se volverá a usar.

📊 Códigos de respuesta HTTP

CódigoSignificado
200Consulta o edición exitosa
201Cupones creados sin errores
207Carga parcial: algunas filas tuvieron error (ver errores_filas)
400Solicitud inválida (formato o campos incorrectos)
401Token ausente, inválido o expirado
404El 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 207 manejada (revisar errores_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?