BranchGroup

Grupo de sucursales. Reúne varias Branch bajo una misma marca/administración: sirve para dar privilegios a grupos de administradores de una sola vez y define la ficha común de la marca en el storefront (logo, portada, descripción, dominio, destacado, plantilla y colores).

  • display_unavailable_goods: mostrar a los compradores los productos no disponibles.
  • display_spent_goods: mostrar los productos agotados (inventario en cero).
  • enable_shoppers: las compras las atienden Shoppers.
  • is_market: comercio tipo mercado; la plataforma optimiza para un gran número de SKU.
  • is_digital: los productos son digitales; el comercio es visible sin importar la distancia.
  • promo_label: texto promocional a mostrar cuando el comercio no tiene promociones activas.
  • is_featured: el comercio aparece en la lista de destacados.
  • enable_pool: las órdenes pueden ir al pool de repartidores (si el pool está habilitado).
  • keywords: palabras clave para mejorar las búsquedas.

Calificación

rating_sum / rating_count acumulan las BranchRating; rating_e2 es el promedio (0–500). A los usuarios no administradores se les devuelve public_rating_e2 (escala 4–5) en rating_e2 cuando hay al menos una calificación.

settings

Ajustes del grupo, gestionados con el sub-recurso branch-groups/{id}/settings. Claves visibles y editables:

Clave Descripción
template Plantilla visual del storefront (food_1, ...).
market_type Subtipo de mercado.
color_primary / color_accent Colores primario y de acento de la marca (#rrggbb).
is_venture Marca el grupo como emprendimiento ("venture").
is_food_vendor El grupo vende comida.
int_sku_enabled Habilita SKU internacional.
enable_auto_image_search Búsqueda automática de imágenes de producto.
image_search_servers Servidores usados para la búsqueda de imágenes.
enable_shopper_validation Exige validar las órdenes antes de marcarlas como preparadas.
special_instructions_placeholder Texto de ayuda del campo de instrucciones especiales.
linked_branches Sucursales enlazadas ({id, alias}).
taxes Impuestos/tasas aplicables al grupo.
add_rating_sum / add_rating_count Ajuste manual que se suma a la calificación acumulada.
import_config Configuración de la importación de productos del grupo.

Notas y gotchas

  • Al crear se asigna un domain autogenerado (b<timestamp>), logo por defecto y keywords con el nombre; los colores se heredan de la compañía.
  • logo_url, logo_alt_url y cover_url se resuelven a URLs absolutas y vuelven a la imagen por defecto si se dejan vacíos; se suben con sus endpoints dedicados.
  • No se puede pasar is_digital a true si el grupo tiene productos no digitales (EA218).

Estructura de Datos

Atributo Tipo Descripción
id int
name string Nombre del grupo/marca.
created_at datetime\|null Fecha de creación.
updated_at datetime\|null Fecha de última modificación.
company_id int Compañía dueña del grupo (oculto en la respuesta).
display_unavailable_goods bool Mostrar a los compradores los productos no disponibles.
enable_shoppers bool Las compras del grupo las atienden Shoppers.
is_market bool Comercio tipo mercado (optimizado para muchos SKU).
logo_url string URL del logo del grupo; imagen por defecto si no se define.
is_featured bool\|null true si el grupo aparece en la lista de destacados.
in_order int Posición del grupo en los listados.
promo_label string\|null Texto promocional a mostrar cuando no hay promociones activas.
enable_pool bool Permite enviar las órdenes del grupo al pool de repartidores.
rating_e2 int Calificación promedio del grupo (0–500).
rating_sum int Suma acumulada de las calificaciones.
rating_count int Número de calificaciones recibidas.
display_spent_goods bool Mostrar los productos agotados (inventario en cero).
domain string\|null Subdominio del storefront del grupo.
custom_domain string\|null Dominio propio del storefront, si se configuró uno.
logo_alt_url string URL del logo alternativo del grupo; imagen por defecto si no se define.
is_digital bool Los productos del grupo son digitales (visible sin importar la distancia).
description string Descripción del comercio.
keywords array\|null Palabras clave para mejorar las búsquedas.
cover_url string URL de la imagen de portada del grupo; imagen por defecto si no se define.
group_description string\|null Descripción interna del grupo.
setting_add_rating_sum int Atajo del ajuste add_rating_sum.
setting_add_rating_count int Atajo del ajuste add_rating_count.
setting_import_config array Atajo del ajuste import_config.
setting_template string Atajo del ajuste template.
setting_color_primary string Atajo del ajuste color_primary.
setting_color_accent string Atajo del ajuste color_accent.
setting_is_venture bool Atajo del ajuste is_venture.
setting_int_sku_enabled bool Atajo del ajuste int_sku_enabled.
setting_enable_auto_image_search bool Atajo del ajuste enable_auto_image_search.
setting_image_search_servers array Atajo del ajuste image_search_servers.
setting_enable_shopper_validation bool Atajo del ajuste enable_shopper_validation.
setting_is_food_vendor bool Atajo del ajuste is_food_vendor.
setting_special_instructions_placeholder string\|null Atajo del ajuste special_instructions_placeholder.
setting_linked_branches array\|null Atajo del ajuste linked_branches ({id, alias}).
setting_taxes array\|null Atajo del ajuste taxes.
allLogs ApiLog> Registros de auditoría de la API, incluidos los internos.
allSettings BranchGroupSetting> Todos los ajustes del grupo (oculto en la respuesta).
allowed_settings array Claves de ajuste visibles para el rol actual.
branchCategories BranchCategory> Categorías de marketplace a las que está asignado el grupo.
branches Branch> Sucursales del grupo.
company Company Compañía dueña del grupo.
deliveryVehicles DeliveryVehicle> Vehículos de reparto asignados al grupo.
editable_settings array Claves de ajuste editables por el rol actual.
public_rating_e2 int Calificación pública del grupo en escala 4–5 (×100).
logs ApiLog> Registros de auditoría de la API visibles.
resources UploadedResource> Archivos subidos asociados al grupo.
settings array Ajustes del grupo visibles para el rol actual.
visibleBranches Branch> Sucursales visibles del grupo. 
{
    "id": 1,
    "name": "default",
    "created_at": "2020-04-17 01:07:30",
    "updated_at": "2020-12-18 03:44:08",
    "display_unavailable_goods": false,
    "enable_shoppers": false,
    "is_market": false,
    "logo_url": "http://127.0.0.1:8000/storage/static/default/branch_logo.png",
    "is_featured": false,
    "in_order": 65535,
    "promo_label": null,
    "enable_pool": true,
    "rating_e2": 500,
    "rating_sum": 0,
    "rating_count": 0,
    "display_spent_goods": true,
    "domain": "b1",
    "custom_domain": null,
    "logo_alt_url": "http://127.0.0.1:8000/storage/static/default/branch_logo.png",
    "is_digital": false,
    "description": "Store",
    "keywords": [
        "default"
    ],
    "cover_url": "http://127.0.0.1:8000/storage/static/default/cover_company.png",
    "group_description": null,
    "settings": {
        "template": "food_1",
        "color_primary": "/docs/3/branch_group#aaaaaa",
        "color_accent": "/docs/3/branch_group#777777",
        "is_venture": false,
        "is_food_vendor": false,
        "special_instructions_placeholder": null
    }
}

Endpoints

Insertar BranchGroup

Crear un grupo de comercios

Crea un BranchGroup (name, descripción, flags de visualización, domain, ...). Los colores se heredan de la compañía y se asigna un domain autogenerado.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups Authorization 
{
    "name": "required|string|max:64",
    "description": "nullable|max:360|string",
    "group_description": "nullable|max:512|string",
    "keywords": [
        "string|max:64"
    ],
    "display_unavailable_goods": "boolean",
    "display_spent_goods": "boolean",
    "enable_shoppers": "boolean",
    "enable_pool": "boolean",
    "is_market": "boolean",
    "is_digital": "boolean",
    "in_order": "integer|min:1",
    "promo_label": "string|max:32",
    "domain": "required|max:32|domain",
    "custom_domain": "max:255|url",
    "settings": {
        "add_rating_sum": "integer|min:0",
        "add_rating_count": "integer|min:0",
        "import_config": "array",
        "color_primary": "string|regex:/^#(?:[0-9a-fA-F]{3}){1,2}$/",
        "color_accent": "string|regex:/^#(?:[0-9a-fA-F]{3}){1,2}$/",
        "is_venture": "boolean",
        "int_sku_enabled": "boolean",
        "enable_auto_image_search": "boolean",
        "image_search_servers": [
            "string|url|max:255|regex:/^.*{0}.*$/"
        ],
        "enable_shopper_validation": "boolean",
        "is_food_vendor": "boolean",
        "special_instructions_placeholder": "nullable|string",
        "linked_branches": [
            {
                "id": "required|integer|min:1",
                "alias": "required|string|max:24"
            }
        ],
        "template": "string|in:store_1,food_1,market_1,digital_1",
        "market_type": "nullable|string|in:long_tail,mid_tail,key_account",
        "taxes": [
            {
                "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"
                ]
            }
        ]
    }
}

Listar BranchGroup

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

Listar grupos de comercios

Devuelve los BranchGroup de la compañía, paginados. Filtro active_only=1 limita a los que tienen al menos una sucursal visible.

Método URI Cabeceras
GET /companies/{companyId}/branch-groups N/A

Ver los ajustes de un grupo de comercios

Devuelve los settings del BranchGroup visibles para el rol actual.

Método URI Cabeceras
GET /companies/{companyId}/branch-groups/{branchGroupId}/settings Authorization

Listar BranchGroup de BranchCategory

{info} Soporta: Paginación Filters

Listar los grupos de comercios de una categoría

Devuelve los BranchGroup asignados a la BranchCategory indicada.

Método URI Cabeceras
GET /companies/{companyId}/branch-categories/{branchCategoryId}/branch-groups N/A

Mostrar BranchGroup

{info} Soporta: Carga dinámica

Ver un grupo de comercios

Devuelve el BranchGroup indicado.

Método URI Cabeceras
GET /companies/{companyId}/branch-groups/{branchGroupId} N/A

Actualizar BranchGroup

Actualizar un grupo de comercios

Modifica el BranchGroup indicado.

Método URI Cabeceras
PATCH /companies/{companyId}/branch-groups/{branchGroupId} Authorization 
{
    "name": "string|max:64",
    "description": "max:360|string",
    "group_description": "nullable|max:512|string",
    "keywords": [
        "string|max:64"
    ],
    "display_unavailable_goods": "boolean",
    "display_spent_goods": "boolean",
    "enable_shoppers": "boolean",
    "enable_pool": "boolean",
    "is_market": "boolean",
    "is_digital": "boolean",
    "in_order": "integer|min:1",
    "promo_label": "string|max:32",
    "domain": "max:32|domain",
    "custom_domain": "max:255|url"
}

Errores de negocio

Código HTTP Cuándo ocurre
EA218 400 No se puede convertir el grupo en digital porque tiene productos no digitales.

Actualizar los ajustes de un grupo de comercios

Modifica los settings editables del BranchGroup (plantilla, colores, taxes, linked_branches, etc.).

Método URI Cabeceras
PATCH /companies/{companyId}/branch-groups/{branchGroupId}/settings Authorization 
{
    "add_rating_sum": "integer|min:0",
    "add_rating_count": "integer|min:0",
    "import_config": "array",
    "color_primary": "string|regex:/^#(?:[0-9a-fA-F]{3}){1,2}$/",
    "color_accent": "string|regex:/^#(?:[0-9a-fA-F]{3}){1,2}$/",
    "is_venture": "boolean",
    "int_sku_enabled": "boolean",
    "enable_auto_image_search": "boolean",
    "image_search_servers": [
        "string|url|max:255|regex:/^.*{0}.*$/"
    ],
    "enable_shopper_validation": "boolean",
    "is_food_vendor": "boolean",
    "special_instructions_placeholder": "nullable|string",
    "linked_branches": [
        {
            "id": "required|integer|min:1",
            "alias": "required|string|max:24"
        }
    ],
    "template": "string|in:store_1,food_1,market_1,digital_1",
    "market_type": "nullable|string|in:long_tail,mid_tail,key_account",
    "taxes": [
        {
            "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"
            ]
        }
    ]
}

Eliminar BranchGroup

Eliminar un grupo de comercios

Borra el BranchGroup indicado.

Método URI Cabeceras
DELETE /companies/{companyId}/branch-groups/{branchGroupId} Authorization

Acciones de BranchGroup

Crear un grupo de comercios con su primera sucursal

Alta guiada: crea el BranchGroup junto con una Branch inicial (dirección desde un enlace de Google Maps, horario, accesos de administrador).

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/by-forwarder Authorization

Ver Json

Subir el logo de un grupo de comercios

Guarda el archivo como logo_url del BranchGroup.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/upload-logo Authorization 
{
    "image": "required|image|mimes:jpeg,png,bmp|max:8192|dimensions:min_width=600,ratio=1/1"
}

Subir el logo alternativo de un grupo de comercios

Guarda el archivo como logo_alt_url del BranchGroup.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/upload-logo-alt Authorization 
{
    "image": "required|image|mimes:jpeg,png,bmp|max:8192|dimensions:min_width=600,ratio=2/1"
}

Subir la portada de un grupo de comercios

Guarda el archivo como cover_url del BranchGroup.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/upload-cover Authorization 
{
    "image": "required|image|mimes:jpeg,png,bmp|max:8192|dimensions:min_width=868,min_height=868"
}

Destacar un grupo de comercios

Pone is_featured = true en el BranchGroup.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/set-featured-enabled Authorization

Quitar de destacados un grupo de comercios

Pone is_featured = false en el BranchGroup.

Método URI Cabeceras
POST /companies/{companyId}/branch-groups/{branchGroupId}/set-featured-disabled Authorization

Ver los ajustes editables de un grupo de comercios

Devuelve las claves de settings que el rol actual puede modificar, con sus reglas.

Método URI Cabeceras
GET /companies/{companyId}/branch-groups/{branchGroupId}/allowed-settings Authorization

Relaciones