Modelo mental
Cuatro ideas. Si las tienes claras, el resto de la referencia se lee sola.
1. Una llamada trae la página entera
Sección titulada «1. Una llamada trae la página entera»No hay un endpoint por tipo de sección. Pides una página y recibes todas las
secciones que el comerciante configuró ahí, de todos los tipos, mezcladas en un
mismo objeto sections.
La consecuencia práctica: trae una vez por página y filtra en memoria. Si tu tema tiene tres secciones custom, las tres comparten el mismo fetch. Hacer una llamada por sección multiplica la latencia sin traer nada nuevo.
// Una sola promesa compartida por toda la página.window.__sectionfy ??= fetch(`${API}/${TOKEN}/product/${productId}`).then((r) => r.json());
// Cada sección del tema la reutiliza.const bundle = await window.__sectionfy;2. El bundle es un almacén, no una lista de render
Sección titulada «2. El bundle es un almacén, no una lista de render»Esta es la que más sorprende. La respuesta incluye secciones que el comerciante ocultó y secciones que archivó. Estar en el bundle no significa “muéstrame”.
Cada sección trae un estado:
"estado": { "lifecycle": "active", "storefrontVisible": true }La regla, sin excepciones:
const visible = (s) => s.estado.lifecycle === 'active' && s.estado.storefrontVisible;Se diseñó así para que el comerciante pueda apagar y encender contenido sin perderlo, y para que un tema pueda previsualizar contenido oculto si lo decide explícitamente. Pero el default correcto es filtrar.
3. Un tipo puede aparecer varias veces
Sección titulada «3. Un tipo puede aparecer varias veces»Un producto puede tener dos bloques de FAQ distintos, o tres carruseles. Cada
instancia es una entrada propia en sections, con el mismo kind y distinto
blockId.
{ "faq-product-333-cmqic4kt5000ieq2bk3hbiat3": { "titulo": "Envíos", "orden": 0 }, "faq-product-333-cmqxb91mn0007ab1c9dk4mz2p": { "titulo": "Garantía", "orden": 2 }}Quedarte solo con la primera coincidencia descarta contenido silenciosamente.
Itera todas, ordénalas por orden, y si necesitas distinguirlas usa indice
(presente solo cuando hay dos o más del mismo tipo en el mismo alcance).
4. Estructura en inglés, contenido en español
Sección titulada «4. Estructura en inglés, contenido en español»Las claves que definen la forma de la respuesta están en inglés: sections,
page, product_id, estado, lifecycle, storefrontVisible.
Las claves que llevan contenido del comerciante están en español: titulo,
texto, imagen, items, pregunta, respuesta, enlace, boton, orden.
No es inconsistencia: el contenido lo escribe un comerciante hispanohablante y las claves espejan las etiquetas que ve en el panel. Una vez que lo sabes, puedes predecir el nombre de un campo sin mirar la referencia.
Dos consecuencias que valen oro
Sección titulada «Dos consecuencias que valen oro»items siempre es un array. Aunque esté vacío. Nunca es null, así que
puedes hacer .map() sin guardar.
Las imágenes pueden ser null. Solo se incluyen los assets que terminaron de
procesarse. Un imagen: null es un estado normal, no un error — guarda siempre
antes de leer imagen.url.
const src = item.imagen?.url;if (!src) return; // omitir, no romper