PromotedBanner

Banner promocional para mostrar a los clientes.

action es la acción al hacer click (por ahora solo view: abrir la pantalla de detalles). target_type + target_id indican a qué pantalla ir:

  • company — Home de la app.
  • branch_group — un comercio; target_id es el id del grupo de comercios (target_id == branch.branch_group_id).
  • good — un producto; target_id es el good_id. Se resuelve el comercio con good.branch_group_id.
  • branch_category — una categoría de comercios; target_id es el id de la categoría.
  • city — una ciudad (fuera de admin y en producción se muestra como company).

Se programa por franja horaria (hour_from–hour_to, admite cruce de medianoche), rango de fechas (date_from–date_to) y días de la semana (days, bitmask oculto day_sunday.. day_saturday; 0 = todos). in_order fija la posición; enabled lo activa. Puede acotarse a comercios (branches) o a categorías de comercios (branchCategories).

Estructura de Datos

Atributo Tipo Descripción
id int
banner_url string URL del banner horizontal (imagen por defecto si no se sube)
action string Acción al hacer click (view)
target_type string Tipo de destino: company, branch_group, good, branch_category, city
target_id int Id del destino, según target_type
created_at datetime\|null
updated_at datetime\|null
company_id int {@link Company} dueña del banner (oculto)
in_order int Posición del banner en el carrusel
enabled bool Si el banner está activo
name string Nombre interno del banner
description string\|null Descripción interna del banner
hour_from string Hora de inicio de visualización (HH:MM)
hour_to string Hora de fin de visualización (HH:MM); si es menor que hour_from, cruza la medianoche
vertical_banner_url string URL del banner vertical (imagen por defecto si no se sube)
days int Bitmask de días de la semana en que se muestra (0 = todos; oculto)
date_from datetime\|null Inicio del rango de vigencia (opcional)
date_to datetime\|null Fin del rango de vigencia (opcional)
day_sunday bool BitMask (({@link self::days} & 0x1) !== 0)
day_monday bool BitMask (({@link self::days} & 0x2) !== 0)
day_tuesday bool BitMask (({@link self::days} & 0x4) !== 0)
day_wednesday bool BitMask (({@link self::days} & 0x8) !== 0)
day_thursday bool BitMask (({@link self::days} & 0x10) !== 0)
day_friday bool BitMask (({@link self::days} & 0x20) !== 0)
day_saturday bool BitMask (({@link self::days} & 0x40) !== 0)
allLogs ApiLog>
branchCategories BranchCategory> Categorías de comercios en las que se muestra el banner
branches Branch> Comercios en los que se muestra el banner
logs ApiLog>
resources UploadedResource> Archivos subidos del banner (imágenes)
target Model\|Eloquent Entidad de destino del banner 
{
    "id": 83,
    "banner_url": "http://127.0.0.1:8000/storage/companies/69/banner/banner_83_1724623630.jpg",
    "action": "view",
    "target_type": "branch_group",
    "target_id": 63,
    "created_at": "2021-03-12 17:30:52",
    "updated_at": "2025-02-17 18:23:07",
    "in_order": 2,
    "enabled": false,
    "name": "Mercado",
    "description": "Asdareghdtyjkuk",
    "hour_from": "15:00",
    "hour_to": "12:00",
    "vertical_banner_url": "http://127.0.0.1:8000/storage/companies/69/banner/banner_vertical_83_1631810497.jpg",
    "date_from": null,
    "date_to": null,
    "day_sunday": true,
    "day_monday": true,
    "day_tuesday": true,
    "day_wednesday": true,
    "day_thursday": true,
    "day_friday": true,
    "day_saturday": true
}

Endpoints

Insertar PromotedBanner

Crear banner promocional

Crea un PromotedBanner para la company: action, destino (target_type + target_id), in_order, enabled y la programación de horario/fechas/días. Las imágenes se suben con los endpoints upload-banner / upload-vertical-banner.

Método URI Cabeceras
POST /companies/{companyId}/promoted-banners Authorization 
{
    "action": "required|string|in:view",
    "target_type": "required|string|in:company,branch_group,good,branch_category,city",
    "target_id": "required|integer",
    "in_order": "integer",
    "enabled": "boolean",
    "name": "string|max:64",
    "description": "string|max:255",
    "hour_from": {
        "string": true,
        "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "hour_to": {
        "string": true,
        "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "tz": {
        "string": true,
        "regex": "/^[\+\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "date_from": "sometimes|nullable|date",
    "date_to": "sometimes|nullable|date|after:date_from",
    "day_sunday": "nullable|boolean",
    "day_monday": "nullable|boolean",
    "day_tuesday": "nullable|boolean",
    "day_wednesday": "nullable|boolean",
    "day_thursday": "nullable|boolean",
    "day_friday": "nullable|boolean",
    "day_saturday": "nullable|boolean"
}

Listar PromotedBanner

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

Listar banners promocionales

Devuelve los PromotedBanner de la company, ordenados por in_order.

Método URI Cabeceras
GET /companies/{companyId}/promoted-banners N/A

Mostrar PromotedBanner

{info} Soporta: Carga dinámica

Mostrar banner promocional

Devuelve el PromotedBanner por su id, con su destino.

Método URI Cabeceras
GET /companies/{companyId}/promoted-banners/{promotedBannerId} N/A

Actualizar PromotedBanner

Actualizar banner promocional

Modifica el destino, action, in_order, enabled, name, description y la programación del PromotedBanner.

Método URI Cabeceras
PATCH /companies/{companyId}/promoted-banners/{promotedBannerId} Authorization 
{
    "action": "string|in:view",
    "target_type": "string|in:company,branch_group,good,branch_category,city",
    "target_id": "integer",
    "in_order": "integer",
    "enabled": "boolean",
    "name": "string|max:64",
    "description": "string|max:255",
    "hour_from": {
        "string": true,
        "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "hour_to": {
        "string": true,
        "regex": "/^([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "tz": {
        "string": true,
        "regex": "/^[\+\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    },
    "date_from": "sometimes|nullable|date",
    "date_to": "sometimes|nullable|date|after:date_from",
    "day_sunday": "nullable|boolean",
    "day_monday": "nullable|boolean",
    "day_tuesday": "nullable|boolean",
    "day_wednesday": "nullable|boolean",
    "day_thursday": "nullable|boolean",
    "day_friday": "nullable|boolean",
    "day_saturday": "nullable|boolean"
}

Vincular PromotedBanner

Vincular PromotedBanner de BranchCategory

Asignar banner a una categoría de comercios

Vincula el PromotedBanner a la BranchCategory indicada, para que se muestre dentro de esa categoría.

Método URI Cabeceras
PUT /companies/{companyId}/branch-categories/{branchCategoryId}/promoted-banners/{promotedBannerId} Authorization

Desvincular PromotedBanner

Desvincular PromotedBanner de BranchCategory

Quitar banner de una categoría de comercios

Desvincula el PromotedBanner de la BranchCategory indicada.

Método URI Cabeceras
DELETE /companies/{companyId}/branch-categories/{branchCategoryId}/promoted-banners/{promotedBannerId} Authorization

Eliminar PromotedBanner

Eliminar banner promocional

Borra el PromotedBanner y sus imágenes.

Método URI Cabeceras
DELETE /companies/{companyId}/promoted-banners/{promotedBannerId} Authorization

Acciones de PromotedBanner

Subir banner horizontal

Sube la imagen del banner horizontal (banner_url) del PromotedBanner.

Método URI Cabeceras
POST /companies/{companyId}/promoted-banners/{promotedBannerId}/upload-banner Authorization 
{
    "image": "required|image|mimes:jpeg,png,bmp|max:8192|dimensions:min_width=868,min_height=868"
}

Subir banner vertical

Sube la imagen del banner vertical (vertical_banner_url) del PromotedBanner.

Método URI Cabeceras
POST /companies/{companyId}/promoted-banners/{promotedBannerId}/upload-vertical-banner Authorization 
{
    "image": "required|image|mimes:jpeg,png,bmp|max:8192|dimensions:min_width=868,min_height=868"
}

Relaciones