Coupon

Un cupón, promoción o descuento de la plataforma.

Tipo (type)

  • personal — códigos de un solo uso (uno por cliente).
  • batch — un único código reutilizable (promo_code).
  • promo — sin código; se aplica automáticamente a quien cumpla las condiciones.
  • gift_card — no descuenta la orden, acredita saldo al cliente (como una recarga).

Estado (status)

pending (en configuración) → generating (enviado; ya no se editan los parámetros, se están aplicando) → ready (listo para arrancar en starts_at) → running (activo, se puede canjear) → finished (expirado). Endpoints: set-ready, set-finished, update (solo pending), update-running (solo running).

Descuento

  • price_e2 — descuento fijo (× 100); price_prc — descuento porcentual (fracción 0–1).
  • applies_to — sobre qué se calcula: total | subtotal | base_price | service | delivery.
  • min_purchase_e2 — compra mínima para poder aplicarlo.
  • total_count / spent_count — máximo de canjes y canjes ya realizados.
  • starts_at / ends_at — vigencia (si ends_at es null, no expira).

Alcance (target_type + targets)

target_type define el tipo de objetivos del cupón: company, city, branch_group, branch, good. Los objetivos concretos se gestionan como CouponTarget (PUT/DELETE coupons/{id}/targets/{targetId}). Los cupones también pueden usar descuentos por reglas (config.fee_rules) en lugar de targets.

Configuración (config)

Objeto con condiciones y ajustes finos del cupón; los config_* del modelo son el acceso tipado.

Clave Tipo Descripción
limit int|null Máximo de usos por cliente
amount_limit_e2 int|null Tope de descuento por uso (× 100)
max_discount_e2 int|null Tope de descuento acumulado del cupón (× 100)
max_purchase_e2 int|null Compra máxima para poder aplicarlo (× 100)
usable_in_promos bool Se puede combinar con promociones automáticas
avoid_same_target_promos bool No acumular con otra promo del mismo objetivo
users_registered_since / users_registered_until date|null Solo clientes registrados en ese rango
min_purchase_count / max_purchase_count int|null Compras previas del cliente exigidas
last_purchase_min_days / last_purchase_max_days int|null Días desde la última compra del cliente
join_last_purchase_count bool Contar compras de todas las marcas de la company
purchase_condition_mode string Nivel al que se cuentan las compras previas: company | branch_group | branch
only_deliveries bool Solo aplica a órdenes con envío
is_cashback bool Se acredita como cashback en vez de descontar al instante
is_fixed bool Descuento fijo (no proporcional al monto)
receiver string|null Destinatario del cashback
days array Días de la semana en que aplica
hour_beg / hour_end string Franja horaria en que aplica (HH:MM)
branch_id int|null Restringe el cupón a una sucursal
company_assumption_prc float Porcentaje del descuento asumido por la company (fracción 0–1)
fee_rules array Descuentos por reglas (alternativa a los targets)
apply_for_unit bool Aplicar el descuento por unidad del producto
apply_after_tax bool Aplicar el descuento después de impuestos
custom_discount_tag string|null Etiqueta a mostrar para este descuento
internal_code string|null Código interno de referencia
source_whitelist array Orígenes de orden permitidos (Ridery, WhatsApp, …)
target_blacklist array Objetivos excluidos del cupón
collision_slot int Franja de colisión para evitar solapes entre promociones

Estructura de Datos

Atributo Tipo Descripción
id int
name string Nombre para identificar el cupón
promo_code string\|null Código de canje; solo en cupones batch
type string personal | batch | promo | gift_card
status string pending | generating | ready | running | finished
price_e2 int Descuento fijo (× 100)
price_prc float Descuento porcentual (fracción 0–1)
min_purchase_e2 int Compra mínima para aplicar el cupón (× 100)
total_count int Máximo de canjes permitidos (0 = ilimitado)
spent_count int Canjes realizados
starts_at datetime\|null Fecha/hora programada de inicio
ends_at datetime\|null Fecha/hora programada de fin; null = no expira
created_at datetime\|null
updated_at datetime\|null
deleted_at datetime\|null
company_id int Company dueña del cupón
branch_id int\|null Sucursal a la que se restringe el cupón, si aplica
applies_to string total | subtotal | base_price | service | delivery
target_type string Tipo de objetivos del cupón (company | city | branch_group | branch | good)
branch_group_id int\|null Comercio (marca) del cupón, si aplica
config array Condiciones y ajustes del cupón (ver "Configuración")
whitelist array\|null Lista de clientes habilitados (cupones con whitelist)
loop_config array\|null Configuración de repetición automática del cupón (renovación periódica)
activePromos ActivePromo> Índice de promociones activas derivadas del cupón
allLogs ApiLog>
branch Branch\|null
branchGroup BranchGroup\|null
company Company
company_assumption float Porcentaje del descuento asumido por la company (= config.company_assumption_prc)
config_amount_limit_e2 int\|null Tope de descuento por uso (× 100)
config_apply_after_tax bool\|null Aplicar el descuento después de impuestos
config_apply_for_unit bool Aplicar el descuento por unidad del producto
config_avoid_same_target_promos bool\|null No acumular con otra promo del mismo objetivo
config_branch_id int\|null Sucursal a la que restringe el cupón
config_collision_slot int\|null Franja de colisión para evitar solapes
config_custom_discount_tag string\|null Etiqueta a mostrar para el descuento
config_days array Días de la semana en que aplica
config_fee_rules array Descuentos por reglas
config_hours_beg string Inicio de la franja horaria (HH:MM)
config_hours_end string Fin de la franja horaria (HH:MM)
config_internal_code string\|null Código interno de referencia
config_is_cashback bool\|null Se acredita como cashback
config_is_fixed bool\|null Descuento fijo (no proporcional)
config_join_last_purchase_count bool Contar compras de todas las marcas de la company
config_last_purchase_max_days int\|null Máximo de días desde la última compra
config_last_purchase_min_days int\|null Mínimo de días desde la última compra
config_limit int\|null Máximo de usos por cliente
config_max_discount_e2 int\|null Tope de descuento acumulado del cupón (× 100)
config_max_purchase_count int\|null Máximo de compras previas del cliente
config_max_purchase_e2 int\|null Compra máxima para poder aplicarlo (× 100)
config_min_purchase_count int\|null Mínimo de compras previas del cliente
config_only_deliveries bool\|null Solo aplica a órdenes con envío
config_order Order\|null Orden asociada a la condición de compra (interno)
config_purchase_condition_mode string\|null Nivel al que se cuentan las compras previas
config_receiver string\|null Destinatario del cashback
config_registered_since datetime\|null Solo clientes registrados desde esta fecha
config_registered_until datetime\|null Solo clientes registrados hasta esta fecha
config_source_whitelist array Orígenes de orden permitidos
config_target_blacklist array Objetivos excluidos del cupón
config_usable_in_promos bool\|null Se puede combinar con promociones automáticas
couponTargets CouponTarget> Objetivos concretos del cupón
couponTickets CouponTicket> Tickets/códigos generados del cupón
couponUsages CouponUsage> Canjes del cupón
has_ruled_discounts bool El cupón usa descuentos por reglas (config.fee_rules)
lastUsage CouponUsage\|null Último canje registrado
logs ApiLog>
mapped_target_blacklist array Objetivos excluidos, resueltos a sus nombres
mapped_target_names array Objetivos del cupón, resueltos a sus nombres
mapped_whitelist array Whitelist resuelta a datos de cliente
total_assumed_discount_e2 int Descuento total asumido por la company (× 100)
total_discount_e2 int Descuento total otorgado por el cupón (× 100) 
{
    "id": 45,
    "name": "3% de descuento en tu envío",
    "promo_code": null,
    "type": "personal",
    "status": "finished",
    "price_e2": 0,
    "price_prc": 0.03,
    "min_purchase_e2": 1000,
    "total_count": 15,
    "spent_count": 0,
    "starts_at": "2020-09-02 14:43:50",
    "ends_at": null,
    "created_at": "2020-09-02 14:27:25",
    "updated_at": "2022-06-02 16:32:54",
    "deleted_at": null,
    "branch_id": null,
    "applies_to": "delivery",
    "target_type": "branch_group",
    "branch_group_id": null,
    "config": {
        "limit": null,
        "amount_limit_e2": null,
        "max_discount_e2": null,
        "max_purchase_e2": null,
        "usable_in_promos": true,
        "users_registered_since": null,
        "users_registered_until": null,
        "min_purchase_count": null,
        "max_purchase_count": null,
        "last_purchase_min_days": null,
        "last_purchase_max_days": null,
        "join_last_purchase_count": false,
        "only_deliveries": false,
        "is_cashback": false,
        "is_fixed": false,
        "company_assumption_prc": 0,
        "days": [],
        "hour_beg": "00:00",
        "hour_end": "00:00",
        "fee_rules": [],
        "apply_for_unit": true,
        "apply_after_tax": false,
        "custom_discount_tag": null,
        "source_whitelist": [],
        "target_blacklist": [],
        "purchase_condition_mode": "company",
        "avoid_same_target_promos": false,
        "collision_slot": 1000,
        "human_amount_limit_e2": 0,
        "human_max_discount_e2": 0,
        "human_max_purchase_e2": 0,
        "human_company_assumption_prc": 0
    },
    "whitelist": null,
    "loop_config": null,
    "human_price_e2": 0,
    "human_price_prc": 3,
    "human_min_purchase_e2": 10
}

Endpoints

Insertar Coupon

Crea un nuevo cupón o descuento.

El parámetro type especifica el tipo de cupón a ser creado. Este valor no podrá ser modificado.

  • type=personal: Genera tantos códigos diferentes como total_count hayan disponibles para el canje. Cada código puede ser utilizado una única vez.
  • type=batch: Almacena un único código especificado por el administrador como promo_code. El código puede ser canjeado más de una vez, hasta agotarse el total_count.
  • type=promo: No genera códigos de cupón. En cambio, aplica el descuento a todos los objetivos configurados de forma que afecta a todas las compras realizadas.

El cupón se crea en estado pending. Antes de guardarlo se validan las combinaciones de parámetros (config, applies_to, target_type, type); combinaciones incompatibles se rechazan.

Método URI Cabeceras
POST /companies/{companyId}/coupons Authorization 
{
    "name": "string|max:80",
    "promo_code": "required_if:type,batch|string|min:5|max:20|regex:/^[0-9a-zA-Z]{5,20}$/",
    "type": "required|string|in:personal,batch,promo,gift_card",
    "price_e2": "integer|min:0",
    "price_prc": "numeric|between:0.0000,1.0000",
    "min_purchase_e2": "integer|min:0",
    "total_count": "required|integer|min:0",
    "applies_to": "string|in:total,subtotal,base_price,service,delivery",
    "target_type": "string|in:company,city,branch_group,good",
    "human_price_e2": "numeric|min:0.0",
    "human_price_prc": "numeric|between:0.00,100.00",
    "human_min_purchase_e2": "numeric|min:0.0",
    "whitelist": [
        "integer|exists:clients,id"
    ],
    "config": {
        "limit": "nullable|integer",
        "amount_limit_e2": "nullable|integer|min:1",
        "max_discount_e2": "nullable|integer",
        "max_purchase_e2": "nullable|integer|min:1",
        "usable_in_promos": "boolean",
        "avoid_same_target_promos": "boolean",
        "users_registered_since": "date",
        "users_registered_until": "date",
        "min_purchase_count": "nullable|integer",
        "max_purchase_count": "nullable|integer",
        "last_purchase_min_days": "nullable|integer",
        "last_purchase_max_days": "nullable|integer",
        "join_last_purchase_count": "nullable|boolean",
        "only_deliveries": "boolean",
        "is_cashback": "boolean",
        "is_fixed": "boolean",
        "company_assumption_prc": "numeric|min:0|max:100",
        "days": "array",
        "hour_beg": "string",
        "hour_end": "string",
        "apply_for_unit": "boolean",
        "apply_after_tax": "boolean",
        "custom_discount_tag": "nullable|string|max:10",
        "source_whitelist": "array",
        "target_blacklist": "array",
        "purchase_condition_mode": "string|in:company,branch_group,branch",
        "collision_slot": "nullable|integer|min:0|max:999999",
        "fee_rules": [
            {
                "is_enabled": "boolean",
                "name": "required|string|max:32",
                "label": "string|max:32",
                "description": "string",
                "layer": "integer|min:0|max:255",
                "price_min_e2": "integer|min:0",
                "human_price_min_e2": "numeric|min:0.0",
                "price_max_e2": "integer",
                "human_price_max_e2": "numeric",
                "hour_beg": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "hour_end": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "conditions": "array",
                "payment_methods": [
                    "required|string"
                ],
                "payment_currencies": [
                    "required|string"
                ]
            }
        ]
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
EF316 400 El cupón no admite ese target_type.
EF320 400 Un cupón personal no puede tener total_count ilimitado.
EF328 400 El cupón no puede tener a la vez descuento propio y descuentos por reglas.
EF333 400 Combinación de configuración no soportada.

Insertar Coupon de BranchGroup

Crear cupón de un comercio

Crea un Coupon acotado a un branch_group (marca). Se crea en estado pending y se validan las combinaciones de parámetros como en el endpoint de creación de company.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/coupons Authorization 
{
    "name": "string|max:80",
    "promo_code": "required_if:type,batch|string|min:5|max:20|regex:/^[0-9a-zA-Z]{5,20}$/",
    "type": "required|string|in:personal,batch,promo,gift_card",
    "price_e2": "integer|min:0",
    "price_prc": "numeric|between:0.0000,1.0000",
    "min_purchase_e2": "integer|min:0",
    "total_count": "required|integer|min:0",
    "applies_to": "string|in:total,subtotal,base_price,service,delivery",
    "target_type": "string|in:company,city,branch_group,good",
    "human_price_e2": "numeric|min:0.0",
    "human_price_prc": "numeric|between:0.00,100.00",
    "human_min_purchase_e2": "numeric|min:0.0",
    "whitelist": [
        "integer|exists:clients,id"
    ],
    "config": {
        "limit": "nullable|integer",
        "amount_limit_e2": "nullable|integer|min:1",
        "max_discount_e2": "nullable|integer",
        "max_purchase_e2": "nullable|integer|min:1",
        "usable_in_promos": "boolean",
        "avoid_same_target_promos": "boolean",
        "users_registered_since": "date",
        "users_registered_until": "date",
        "min_purchase_count": "nullable|integer",
        "max_purchase_count": "nullable|integer",
        "last_purchase_min_days": "nullable|integer",
        "last_purchase_max_days": "nullable|integer",
        "join_last_purchase_count": "nullable|boolean",
        "only_deliveries": "boolean",
        "is_cashback": "boolean",
        "is_fixed": "boolean",
        "company_assumption_prc": "numeric|min:0|max:100",
        "days": "array",
        "hour_beg": "string",
        "hour_end": "string",
        "apply_for_unit": "boolean",
        "apply_after_tax": "boolean",
        "custom_discount_tag": "nullable|string|max:10",
        "source_whitelist": "array",
        "target_blacklist": "array",
        "purchase_condition_mode": "string|in:company,branch_group,branch",
        "collision_slot": "nullable|integer|min:0|max:999999",
        "fee_rules": [
            {
                "is_enabled": "boolean",
                "name": "required|string|max:32",
                "label": "string|max:32",
                "description": "string",
                "layer": "integer|min:0|max:255",
                "price_min_e2": "integer|min:0",
                "human_price_min_e2": "numeric|min:0.0",
                "price_max_e2": "integer",
                "human_price_max_e2": "numeric",
                "hour_beg": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "hour_end": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "conditions": "array",
                "payment_methods": [
                    "required|string"
                ],
                "payment_currencies": [
                    "required|string"
                ]
            }
        ]
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
EF316 400 El cupón no admite ese target_type.
EF320 400 Un cupón personal no puede tener total_count ilimitado.
EF328 400 El cupón no puede tener a la vez descuento propio y descuentos por reglas.
EF333 400 Combinación de configuración no soportada.

Listar Coupon

{info} Soporta: Paginación Filters Carga dinámica

Devuelve la lista de cupones y promociones.

Método URI Cabeceras
GET /companies/{companyId}/coupons Authorization

Mostrar Coupon

{info} Soporta: Carga dinámica

Detalles de un Cupón

Método URI Cabeceras
GET /companies/{companyId}/coupons/{couponId} Authorization

Actualizar Coupon

Actualizar cupón.

Requiere status=pending

Modifica los parámetros del cupón. Si se cambia el target_type, todos los targets que hayan sido previamente configurados se perderán.

Método URI Cabeceras
PATCH /companies/{companyId}/coupons/{couponId} Authorization 
{
    "name": "string|max:80",
    "price_e2": "integer|min:0",
    "price_prc": "numeric|between:0.0000,1.0000",
    "min_purchase_e2": "integer|min:0",
    "total_count": "integer|min:0",
    "applies_to": "string|in:total,subtotal,base_price,service,delivery",
    "target_type": "string|in:company,city,branch_group,good",
    "human_price_e2": "numeric|min:0.0",
    "human_price_prc": "numeric|between:0.00,100.00",
    "human_min_purchase_e2": "numeric|min:0.0",
    "whitelist": [
        "integer|exists:clients,id"
    ],
    "config": {
        "limit": "nullable|integer",
        "amount_limit_e2": "nullable|integer|min:1",
        "max_discount_e2": "nullable|integer",
        "max_purchase_e2": "nullable|integer|min:1",
        "usable_in_promos": "boolean",
        "avoid_same_target_promos": "boolean",
        "users_registered_since": "date",
        "users_registered_until": "date",
        "min_purchase_count": "nullable|integer",
        "max_purchase_count": "nullable|integer",
        "last_purchase_min_days": "nullable|integer",
        "last_purchase_max_days": "nullable|integer",
        "join_last_purchase_count": "nullable|boolean",
        "only_deliveries": "boolean",
        "is_cashback": "boolean",
        "is_fixed": "boolean",
        "company_assumption_prc": "numeric|min:0|max:100",
        "days": "array",
        "hour_beg": "string",
        "hour_end": "string",
        "apply_for_unit": "boolean",
        "apply_after_tax": "boolean",
        "custom_discount_tag": "nullable|string|max:10",
        "source_whitelist": "array",
        "target_blacklist": "array",
        "purchase_condition_mode": "string|in:company,branch_group,branch",
        "collision_slot": "nullable|integer|min:0|max:999999",
        "fee_rules": [
            {
                "is_enabled": "boolean",
                "name": "required|string|max:32",
                "label": "string|max:32",
                "description": "string",
                "layer": "integer|min:0|max:255",
                "price_min_e2": "integer|min:0",
                "human_price_min_e2": "numeric|min:0.0",
                "price_max_e2": "integer",
                "human_price_max_e2": "numeric",
                "hour_beg": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "hour_end": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "conditions": "array",
                "payment_methods": [
                    "required|string"
                ],
                "payment_currencies": [
                    "required|string"
                ]
            }
        ]
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
EF301 400 El cupón no está en estado pending.
EF316 400 El cupón no admite ese target_type.
EF328 400 El cupón no puede tener a la vez descuento propio y descuentos por reglas.
EF333 400 Combinación de configuración no soportada.

Vincular Coupon

Vincular objetivo

Requiere: status=pending

Agrega un objetivo al cupón. Aplica a los target_type = branch_group,branch. Según el target_type, se debe especificar el targetId correspondiente a vincular. Por ejemplo, si se desea vincular un Branch id=12, el cupón debe tener target_type=branch y se dede consumir este endpoint usando como parámetro path {targetId}=12.

Método URI Cabeceras
PUT /companies/{companyId}/coupons/{couponId}/targets/{targetId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EF301 400 El cupón no está en estado pending.
EF316 400 El objetivo no es compatible con el target_type del cupón.

Desvincular Coupon

Desvincular objetivo

Requiere: status=pending

Quita un objetivo al cupón. Aplica a los target_type = branch_group,branch. Según el target_type, se debe especificar el targetId correspondiente a desvincular. Por ejemplo, si se desea desvincular un Branch id=12 vinculado, el cupón debe tener target_type=branch y se dede consumir este endpoint usando como parámetro path {targetId}=12.

Método URI Cabeceras
DELETE /companies/{companyId}/coupons/{couponId}/targets/{targetId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EF301 400 El cupón no está en estado pending.

Eliminar Coupon

Elimina un cupón

Requiere: status!=running

Si se desea eliminar un cupón en ejecución, hay que finalizarlo primero

Método URI Cabeceras
DELETE /companies/{companyId}/coupons/{couponId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EF304 400 El cupón está en ejecución; hay que finalizarlo primero.

Restaurar Coupon

Restaura un cupón eliminado.

Método URI Cabeceras
POST /companies/{companyId}/coupons/{couponId}/restore Authorization

Acciones de Coupon

Endpoint para comprobar si un PromoCode es válido.

Este endpoint verifica si el código promocional es válido para aplicarse en una Orden. En caso afirmativo, se devuelve el Cupón con los datos del mismo, lo que permite mostrar información de descuentos aplicables.

Método URI Cabeceras
POST /companies/{companyId}/coupons/check Authorization 
{
    "coupon_code": "required|string|min:5|max:20",
    "subtotal_e2": "required|integer|min:1",
    "subtotal_full_e2": "integer|min:0",
    "base_price_e2": "integer|min:1",
    "delivery_e2": "integer|min:0",
    "client_id": "integer",
    "items": [
        {
            "good_id": "required|integer|exists:goods,id",
            "quantity": "required|integer|min:1",
            "provider_id": "integer",
            "properties": [
                {
                    "property_id": "required|integer",
                    "value": "required|string"
                }
            ]
        }
    ],
    "goods": [
        "integer"
    ],
    "good_ids": {
        "string": true,
        "regex": "/^[0-9]+(,[0-9]+)*$/"
    },
    "time": {
        "string": true,
        "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "datetime": "date|after:now",
    "use_local_tz": "boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF312 400 El código no es válido o ya fue utilizado.
EF323 400 El código es de gift card; se canjea desde el perfil, no en el checkout.
EF309 400 El cupón agotó su límite de usos.
EF310 400 El subtotal supera el máximo permitido por el cupón.
EF311 400 El subtotal no alcanza el mínimo exigido por el cupón.
EF313 400 El cupón no es válido para ese comercio.
EF317 400 El cupón no se puede aplicar a productos que ya están en promoción.
EF322 400 El cliente no cumple una condición del cupón (compras previas, antigüedad, etc.).
EF324 400 El cupón no aplica a órdenes de retiro en tienda.
EF325 400 El cupón no aplica en el día seleccionado.
EF326 400 El cupón solo aplica dentro de una franja horaria.
EF327 400 El cliente no está en la lista de habilitados del cupón.
EF331 400 El origen de la orden no está permitido para el cupón.
EF332 400 El comercio está en la lista de exclusión del cupón.

Canjea un código de GiftCard.

En caso de un código de GiftCard válido, el monto de la Giftcard se convierte en Saldo dentro del App. Nótese que los código de tipo PromoCode usan su propio endpoint para su verificación.

Método URI Cabeceras
POST /companies/{companyId}/coupons/redeem Authorization 
{
    "coupon_code": "required|string|min:5|max:20",
    "redeem": "boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF312 400 El código no es válido o ya fue canjeado.

Comprueba el estado de validez de un código de cupón.

Este endpoint verifica si el código promocional es válido para aplicarse en una Orden del comercio especificado. En caso afirmativo, se devuelve el Cupón con los datos del mismo, lo que permite mostrar información de descuentos aplicables.

Método URI Cabeceras
POST /companies/{companyId}/branches/{branchId}/coupons/check Authorization 
{
    "coupon_code": "required|string|min:5|max:20",
    "subtotal_e2": "required|integer|min:1",
    "subtotal_full_e2": "integer|min:0",
    "base_price_e2": "integer|min:1",
    "delivery_e2": "integer|min:0",
    "client_id": "integer",
    "items": [
        {
            "good_id": "required|integer|exists:goods,id",
            "quantity": "required|integer|min:1",
            "provider_id": "integer",
            "properties": [
                {
                    "property_id": "required|integer",
                    "value": "required|string"
                }
            ]
        }
    ],
    "goods": [
        "integer"
    ],
    "good_ids": {
        "string": true,
        "regex": "/^[0-9]+(,[0-9]+)*$/"
    },
    "time": {
        "string": true,
        "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "datetime": "date|after:now",
    "use_local_tz": "boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF312 400 El código no es válido o ya fue utilizado.
EF313 400 El cupón no es válido para ese comercio.
EF309 400 El cupón agotó su límite de usos.
EF310 400 El subtotal supera el máximo permitido por el cupón.
EF311 400 El subtotal no alcanza el mínimo exigido por el cupón.
EF322 400 El cliente no cumple una condición del cupón.
EF325 400 El cupón no aplica en el día seleccionado.
EF326 400 El cupón solo aplica dentro de una franja horaria.
EF327 400 El cliente no está en la lista de habilitados del cupón.

Actualizar cupón running.

Requiere status=running

Modifica los parámetros del cupón cuando ya el cupón está running

Método URI Cabeceras
PATCH /companies/{companyId}/coupons/{couponId}/update-running Authorization 
{
    "name": "string|max:64",
    "ends_at": "date|after:starts_at|after:now",
    "timezone": {
        "string": true,
        "regex": "/^[\+\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "min_purchase_e2": "integer|min:0",
    "human_min_purchase_e2": "numeric|min:0.0",
    "whitelist": [
        "integer|exists:clients,id"
    ],
    "config": {
        "limit": "nullable|integer",
        "amount_limit_e2": "nullable|integer|min:1",
        "max_discount_e2": "nullable|integer",
        "max_purchase_e2": "nullable|integer|min:1",
        "usable_in_promos": "boolean",
        "avoid_same_target_promos": "boolean",
        "min_purchase_count": "nullable|integer",
        "max_purchase_count": "nullable|integer",
        "last_purchase_min_days": "nullable|integer",
        "last_purchase_max_days": "nullable|integer",
        "join_last_purchase_count": "nullable|boolean",
        "only_deliveries": "boolean",
        "company_assumption_prc": "numeric|min:0|max:100",
        "custom_discount_tag": "nullable|string|max:10",
        "source_whitelist": "array",
        "target_blacklist": "array",
        "purchase_condition_mode": "string|in:company,branch_group,branch",
        "fee_rules": [
            {
                "is_enabled": "boolean",
                "name": "required|string|max:32",
                "label": "string|max:32",
                "description": "string",
                "layer": "integer|min:0|max:255",
                "price_min_e2": "integer|min:0",
                "human_price_min_e2": "numeric|min:0.0",
                "price_max_e2": "integer",
                "human_price_max_e2": "numeric",
                "hour_beg": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "hour_end": {
                    "string": true,
                    "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
                },
                "conditions": "array",
                "payment_methods": [
                    "required|string"
                ],
                "payment_currencies": [
                    "required|string"
                ]
            }
        ]
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
EF305 400 El cupón no está en estado running.

Envío de cupones

Requiere: status=pending

Finaliza la configuración del cupón y lo prepara para su inicio. Este endpoint realiza las comprobaciones necesarias para garantizar que todos los parámetros establecidos son válidos.

Una vez enviado, un cupón no podrá volver a ser modificado. Su status para a ser "generating", en el cual se realizan las optimizaciones y cambios necesarios para aplicar el cupón en la fecha establecida. una vez terminada la fase de "generating", el cupón pasa automáticamente al status=ready, indicando que el cupón está listo para iniciar en la fecha programada. Llegado el momento, el cupón iniciará automáticamente con el status=running.

Método URI Cabeceras
POST /companies/{companyId}/coupons/{couponId}/set-ready Authorization 
{
    "starts_at": "date",
    "ends_at": "date|after:starts_at|after:now",
    "coupon_length": "integer|min:5|max:20",
    "timezone": {
        "string": true,
        "regex": "/^[\+\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
EF301 400 El cupón no está en estado pending.
EF308 400 El cupón no tiene un precio de descuento configurado.
EF315 400 El cupón no tiene objetivos (targets) configurados.
EF333 400 Combinación de configuración no soportada.

Lista de Códigos

Permite mostrar la lista de códigos de un cupón.

Los códigos de cupón son generados en la fase de "generating". Si se consume en una fase anterior, siempre devolverá vacío.

Método URI Cabeceras
GET /companies/{companyId}/coupons/{couponId}/codes Authorization

Cupones disponibles

{info} Soporta: Paginación Filters Carga dinámica

Muestra el listado de códigos de cupón disponibles para el canje. No aplica para type=promo

Método URI Cabeceras
GET /companies/{companyId}/coupons/{couponId}/available-tickets Authorization

Canjes

{info} Soporta: Paginación Filters Carga dinámica

Muestra el listado de canjes/usos de un cupón/promoción.

Método URI Cabeceras
GET /companies/{companyId}/coupons/{couponId}/used-tickets Authorization

Finaliza un cupón en ejecución.

Requiere: status=running

Permite finalizar un cupón antes de que expire, o cupones que no tienen una fecha de finalización especificada. Un cupón finalizado no podrá procesar más canjes.

Método URI Cabeceras
POST /companies/{companyId}/coupons/{couponId}/set-finished Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EF305 400 El cupón no está en estado running.

Relaciones