Coupon

Representa a un Cupón, Promoción o Descuento dentro de la plataforma.

  • name: Nombre para identificar al cupón.
  • promo_code: Código de canje para el cupón. Sólo aplica a Cupones de tipo batch.
  • type: Define el comportamiento del cupón. Valores admitidos: personal,batch,promo
  • status: Estado actual del cupón: pending,generating,ready,running,finished.
    • pending: El cupón está creado, pero aún está en su fase de configuración.
    • generating: El cupón fue enviado. En este punto no se pueden hacer modificaciones en los parámetros del cupón. Los parámetros configurados están siendo aplicados.
    • ready: El cupón está listo para ser iniciado en la fecha programada.
    • running: El cupón ha iniciado y puede ser consumido.
    • finished: EL cupón ha expirado y ya no puede ser consumido.
  • price_e2: Tarifa de descuento plana.
  • price_prc: Porcentaje de descuento.
  • min_purchase_e2: Compra mínima para aplicar el cupón.
  • total_count: Cantidad máxima permitida de canje.
  • spent_count: Cantidad actual de canjes.
  • starts_at: Fecha en la cual se programó el inicio.
  • ends_at: Fecha en la cual se programó el final. Se puede obviar para que nunca finalice.
  • applies_to: Define a qué aplica el descuento: subtotal,service,delivery
  • target_type: Define cómo se agregaran los objetivos de la promoción: company,branch_group,branch

Modelo Coupon

{
    "id": 1,
    "name": "Prueba Local",
    "promo_code": null,
    "type": "personal",
    "status": "ready",
    "price_e2": 500,
    "price_prc": 0,
    "min_purchase_e2": 500,
    "total_count": 100000,
    "starts_at": "2020-08-12 00:00:00",
    "ends_at": "2021-09-01 00:00:00",
    "created_at": "2020-08-11 17:20:20",
    "updated_at": "2020-12-22 19:53:10",
    "deleted_at": null,
    "branch_id": null,
    "applies_to": "subtotal",
    "target_type": "company",
    "branch_group_id": null,
    "config": {
        "limit": null,
        "usable_in_promos": true,
        "users_registered_since": null,
        "users_registered_until": null,
        "only_first_purchase": false
    },
    "human_price_e2": 5,
    "human_price_prc": 0,
    "human_min_purchase_e2": 5
}

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.
Método URI Cabeceras
POST /companies/{companyId}/coupons Authorization 
{
    "name": "required|string|max:64",
    "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",
    "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,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",
    "config": {
        "limit": "integer",
        "usable_in_promos": "boolean",
        "users_registered_since": "date",
        "users_registered_until": "date",
        "only_first_purchase": "boolean"
    }
}

Insertar Coupon de BranchGroup

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/coupons Authorization 
{
    "name": "required|string|max:64",
    "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",
    "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,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",
    "config": {
        "limit": "integer",
        "usable_in_promos": "boolean",
        "users_registered_since": "date",
        "users_registered_until": "date",
        "only_first_purchase": "boolean"
    }
}

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:64",
    "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,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",
    "config": {
        "limit": "integer",
        "usable_in_promos": "boolean",
        "users_registered_since": "date",
        "users_registered_until": "date",
        "only_first_purchase": "boolean"
    }
}

Vincular Coupon

Vincular Target

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

Desvincular Coupon

Desvincular Target

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

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

Restaurar Coupon

Restaura un cupón eliminado.

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

Acciones de Coupon

Check

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"
}

Check Code

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

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"
}

Set Ready

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|after:2021-08-18 13:58:35",
    "ends_at": "date|after:starts_at|after:2021-08-18 13:58:35",
    "coupon_length": "integer|min:5|max:20",
    "timezone": {
        "string": true,
        "regex": "/^[\\+\\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    }
}

Show Codes

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

Show Available

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

Cupones disponibles

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

Show Used

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

Canjes

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

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

Set Finished

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

Enlaces de Coupon