Integración por Lotes (Batch) de Categorías

Introducción

Esta sección describe la interfaz de carga de categorías para la integración por lotes (batch) en la TOL.

Las categorías definen la estructura de navegación del catálogo de productos en la tienda online. Se organizan en forma de árbol jerárquico donde cada categoría puede contener subcategorías, permitiendo una navegación multinivel.

Las categorías se pueden mantener desde el backoffice o mediante esta interfaz de carga por lotes.

Una categoría permite definir la siguiente información:

Código: identificador único de la categoría.
Categoría padre: categoría de la cual depende en el árbol jerárquico.
Orden: posición de visualización dentro de su categoría padre.
Descripciones: nombre, título, descripción y slug SEO en los diferentes idiomas.
Visibilidad: indica si la categoría es visible en la tienda online.
Tipo: tipo de categoría (estándar por defecto).

Reglas del árbol de categorías

Las categorías forman un árbol a través del campo parent:

Categoría raíz (obligatoria): categoría cuyo campo parent es igual a su propio code. Debe ser la primera entrada del array. Exactamente una categoría raíz por canal.
Categoría hija: categoría cuyo parent referencia el code de otra categoría existente en el fichero.
Anidamiento: no existe límite de profundidad. Una categoría hija puede ser padre de otras categorías.
Ordenación: dentro de un mismo padre, las categorías se ordenan por el campo order de forma ascendente.

Reglas de validación

Cada code debe ser único dentro del fichero.
Cada parent debe referenciar un code válido presente en el fichero (excepto la auto-referencia de la raíz).
No se permiten referencias circulares (salvo la auto-referencia de la categoría raíz).
El slug seo debe ser único entre todas las categorías, conteniendo solo letras minúsculas, números y guiones.
Debe existir exactamente una categoría raíz (donde parent es igual a su propio code).

Interface

Nomenclatura del fichero

Diariamente y según la planificación establecida, se ejecutará un proceso que recibirá un archivo JSON con la información de las categorías.

Este archivo tendrá el siguiente nombre: "prefijo_AAAAMMDDHHmmss.json", donde:

Prefijo: "categories"
AAAA: Año.
MM: Mes.
DD: Día.
HH: Hora.
mm: Minutos.
ss: Segundos.

El fichero deberá estar en formato UTF-8 sin BOM.

Adicionalmente se puede definir que la carga del archivo se ejecute teniendo en cuenta la existencia de un archivo de semáforo para asegurar que el archivo está completo.

El archivo de semáforo tendrá el siguiente nombre "clotprefijo_AAAAMMDDHHmmss.json"

Planificación del proceso

Según la planificación establecida, se ejecutará el proceso de carga que leerá los archivos JSON y cargará la información de las categorías en la BBDD.

El proceso se puede lanzar de forma manual desde el backoffice.

Formato del archivo JSON

El archivo JSON tendrá la estructura siguiente:

{
  "categories": [ ... ]
}

Campos de categoría

Campo "Nombre campo"	Descripción/Ejemplo	Formato	Oblig.
Canal "channel"	Identificador del canal de venta	Numérico entero	No
Código "code"	Identificador único de la categoría	Literal (string)	Sí
Orden "order"	Orden de visualización (menor = se muestra primero)	Numérico entero	No
Padre "parent"	Código de la categoría padre (ver Reglas del árbol)	Literal (string)	Sí
Tipo "type"	Tipo de categoría (`0` = estándar)	Numérico entero	No
Visible "visible"	Indica si la categoría es visible en la tienda online	Booleano	No
Orden carrito "cartOrder"	Posición de ordenación dentro del carrito de compra	Numérico entero	No
Días devolución "refundDays"	Ventana de devolución en días (`0` = política por defecto)	Numérico entero	No
Descripciones "descriptions"	Al menos una descripción localizada por idioma (ver Campos de descripción)	Lista	Sí

Campos de descripción

Cada entrada en descriptions representa una variante de idioma.

Campo "Nombre campo"	Descripción/Ejemplo	Formato	Oblig.
Idioma "language"	Código de idioma ISO 639-1 (ej. `es`, `en`). Solo necesario si hay múltiples idiomas	Literal (2 caracteres máx.)	No
Nombre "name"	Nombre interno/corto de la categoría	Literal (string)	Sí
Título "title"	Título mostrado a los clientes en la tienda	Literal (string)	No
Descripción "description"	Descripción de la categoría para la página de listado	Literal (string)	No
H2 "h2"	Encabezado secundario / descripción extendida	Literal (string)	No
Seo "seo"	Slug para la URL (minúsculas, sin espacios, sin acentos)	Literal (1024 caracteres máx.)	No
Icono "icon"	Identificador o URL del icono	Literal (string)	No

ANEXOS. Ejemplos JSON

Ejemplo árbol completo (raíz + padre + hijo)

Ejemplo de carga con una categoría raíz, una categoría de primer nivel y una subcategoría:

Root (1238)
├── Frescos (2812) [seo: frescos]
│   └── Carnicería (2148) [seo: carniceria]

{
  "categories": [
    {
      "channel": 1,
      "code": "1238",
      "order": 10,
      "parent": "1238",
      "type": 0,
      "visible": true,
      "cartOrder": 1,
      "refundDays": 0,
      "descriptions": [
        {
          "language": "es",
          "name": "Root",
          "title": "Raiz",
          "description": "",
          "h2": "",
          "seo": "raiz",
          "icon": ""
        }
      ]
    },
    {
      "channel": 1,
      "code": "2812",
      "order": 8970,
      "parent": "1238",
      "type": 0,
      "visible": true,
      "cartOrder": 2,
      "refundDays": 0,
      "descriptions": [
        {
          "language": "es",
          "name": "Frescos",
          "title": "Frescos",
          "description": "Los mejores frescos preparados a tu gusto",
          "h2": "",
          "seo": "frescos",
          "icon": ""
        }
      ]
    },
    {
      "channel": 1,
      "code": "2148",
      "order": 8990,
      "parent": "2812",
      "type": 0,
      "visible": true,
      "cartOrder": 1,
      "refundDays": 0,
      "descriptions": [
        {
          "language": "es",
          "name": "Carnicería",
          "title": "Carnicería",
          "description": "En la sección de carnicería tienes un amplio surtido de ternera, cerdo, cordero y aves.",
          "h2": "En la sección de carnicería tienes un amplio surtido de ternera, cerdo, cordero y aves. Indícanos cómo quieres que te lo preparemos en las observaciones del producto",
          "seo": "carniceria",
          "icon": ""
        }
      ]
    }
  ]
}

Ejemplo categoría raíz mínima

Ejemplo con solo los campos obligatorios para una categoría raíz:

{
  "categories": [
    {
      "code": "1000",
      "parent": "1000",
      "descriptions": [
        {
          "name": "Root"
        }
      ]
    }
  ]
}

Ejemplo multi-idioma

Ejemplo de una categoría con descripciones en español e inglés:

{
  "categories": [
    {
      "code": "1000",
      "parent": "1000",
      "order": 10,
      "descriptions": [
        {
          "language": "es",
          "name": "Root",
          "title": "Raiz",
          "seo": "raiz"
        },
        {
          "language": "en",
          "name": "Root",
          "title": "Root",
          "seo": "root"
        }
      ]
    },
    {
      "channel": 1,
      "code": "2001",
      "order": 100,
      "parent": "1000",
      "type": 0,
      "visible": true,
      "cartOrder": 1,
      "refundDays": 0,
      "descriptions": [
        {
          "language": "es",
          "name": "Bebidas",
          "title": "Bebidas",
          "description": "Todo tipo de bebidas",
          "h2": "",
          "seo": "bebidas",
          "icon": ""
        },
        {
          "language": "en",
          "name": "Beverages",
          "title": "Beverages",
          "description": "All kinds of beverages",
          "h2": "",
          "seo": "beverages",
          "icon": ""
        }
      ]
    }
  ]
}

Gestión de versiones

Versión	Cambios
26.1	Importación inicial