API atual/Referência completa/Layouts avançados

Contêineres e linhas

Alterna a herança de um contêiner e cria, edita, exclui e reordena linhas.

Cada página tem quatro contêineres: top_panel, header, content e footer. Dentro de cada um ficam as linhas (rows), que empilham de cima para baixo. Os contêineres são criados com a página; você não os cria nem exclui, só muda a herança (uses_default) e o estilo. Os contêineres compartilhados (top_panel, header e footer) de uma página comum nascem herdando os da página padrão do layout, para o cabeçalho e o rodapé serem editados uma única vez.

Atualizar contêiner

uses_default: true faz o contêiner usar o da página padrão; false faz a página ter o seu próprio, mantendo as linhas que já tinha (alternar não apaga nada). Envie pelo menos um dos campos.

PATCH/api/v1/admin/advanced-layouts/containers/{id}Admin

Atualizar herança ou estilo do contêiner

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do contêiner.

Corpo da requisição

uses_defaultboolean

true herda da página padrão; false usa linhas próprias. No content e na página padrão o valor é sempre false.

designobject

Camada de estilo universal (fundo, espaçamento, borda, sombra, tipografia, tamanho, efeitos), com sobrescritas por breakpoint em base, tablet e mobile. O formato dos campos vem de Esquema de design. Substitui o objeto inteiro quando enviado; envie {} para limpar.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/advanced-layouts/containers/11054" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uses_default": false
  }'

Resposta

200Contêiner atualizado

json

{
  "id": 11054,
  "page_id": 2929,
  "position": "top_panel",
  "sort_order": 0,
  "uses_default": false,
  "rows": []
}

Campos da resposta

idinteger

Id do contêiner.

page_idinteger

Página dona.

positionstring

top_panel, header, content ou footer.

sort_orderinteger

Ordem entre os contêineres.

uses_defaultboolean

Herda da página padrão.

designobject

Camada de estilo universal.

rowsarray

Linhas do contêiner, com colunas e blocos.

Erros

Status	Quando	Corpo de exemplo
400	O id de container no caminho não é um inteiro.	`{"error":"invalid container id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Contêiner não existe.	`{"error":"container not found","detail":"11054"}`
500	Nenhum campo enviado (`no fields to update`) ou falha de banco.	`{"error":"failed to update container","detail":"no fields to update"}`

Criar linha

Adiciona uma linha vazia ao contêiner. Em seguida crie colunas nela e blocos nas colunas.

POST/api/v1/admin/advanced-layouts/containers/{id}/rowsAdmin

Criar uma linha no contêiner

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do contêiner.

Corpo da requisição

sort_orderintegerpadrão: 0

Posição da linha no contêiner.

full_widthbooleanpadrão: false

Largura total da tela.

bg_colorstring

Cor de fundo simples (prefira design).

bg_imagestring

Imagem de fundo simples.

spacingstringpadrão: normal

nonetightnormalloose

Espaçamento vertical.

display_modestringpadrão: normal

normaltabs

Como as colunas aparecem.

visibilityobject

Visibilidade por dispositivo. Chaves desktop, tablet e mobile, valores booleanos. Se omitido na criação, vale true nos três.

usergroup_idsstring[]

Restringe a visibilidade a grupos de compradores. Vazio (padrão) mostra a todos. Aceita os atalhos guest (visitante anônimo) e registered (logado), além de UUIDs de grupos.

custom_classstring

Classe CSS extra.

custom_cssstring

CSS livre da linha.

designobject

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/containers/11056/rows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_width": true,
    "spacing": "loose"
  }'

Resposta

201Linha criada

json

{
  "id": 8029,
  "container_id": 11056,
  "sort_order": 0,
  "full_width": false,
  "spacing": "normal",
  "display_mode": "normal",
  "visibility": {
    "desktop": true,
    "tablet": true,
    "mobile": true
  }
}

Campos da resposta

idinteger

Id da linha.

container_idinteger

Id do contêiner dono da linha.

sort_orderinteger

Posição da linha dentro do contêiner, a partir de 0.

full_widthboolean

true faz a linha ocupar a largura inteira da tela, sem o limite de largura do tema.

spacingstring

Espaçamento vertical: none, tight, normal ou loose.

display_modestring

normal (colunas lado a lado) ou tabs (cada coluna vira uma aba).

visibilityobject

Visibilidade por dispositivo.

bg_colorstring

Cor de fundo simples, quando definida. O fundo de design tem prioridade.

bg_imagestring

Imagem de fundo simples, quando definida.

usergroup_idsstring[]

Grupos de compradores que veem a linha. Ausente quando vazio.

custom_classstring

Classe CSS extra aplicada à linha.

custom_cssstring

CSS livre da linha (tags <script> e @import são removidos ao gravar).

designobject

Camada de estilo universal. Ausente quando vazia.

columnsarray

Colunas da linha (só vem quando a linha é carregada com filhos).

Erros

Status	Quando	Corpo de exemplo
400	O id de container no caminho não é um inteiro.	`{"error":"invalid container id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to create row","detail":"..."}`

Atualizar linha

Altera só os campos enviados. visibility é enviado como objeto completo; usergroup_ids enviado como lista substitui a lista inteira.

PUT/api/v1/admin/advanced-layouts/rows/{id}Admin

Atualizar uma linha

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico da linha.

Corpo da requisição

sort_orderinteger

Posição.

full_widthboolean

Largura total.

bg_colorstring

Cor de fundo simples.

bg_imagestring

Imagem de fundo simples.

spacingstring

nonetightnormalloose

Espaçamento vertical.

display_modestring

normaltabs

Modo das colunas.

visibilityobject

Visibilidade por dispositivo. Chaves desktop, tablet e mobile, valores booleanos. Se omitido, o valor atual é mantido. Se enviado, substitui o objeto inteiro.

usergroup_idsstring[]

Restringe a visibilidade a grupos de compradores. Vazio (padrão) mostra a todos. Aceita os atalhos guest (visitante anônimo) e registered (logado), além de UUIDs de grupos.

custom_classstring

Classe CSS extra.

custom_cssstring

CSS livre.

designobject

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/rows/8029" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_mode": "tabs",
    "visibility": {
      "desktop": true,
      "tablet": true,
      "mobile": false
    }
  }'

Resposta

200Linha atualizada

json

{
  "id": 8029,
  "container_id": 11056,
  "sort_order": 0,
  "full_width": false,
  "spacing": "normal",
  "display_mode": "tabs",
  "visibility": {
    "desktop": true,
    "tablet": true,
    "mobile": false
  }
}

Campos da resposta

idinteger

Id da linha.

container_idinteger

Id do contêiner dono da linha.

sort_orderinteger

Posição da linha dentro do contêiner, a partir de 0.

full_widthboolean

true faz a linha ocupar a largura inteira da tela, sem o limite de largura do tema.

spacingstring

Espaçamento vertical: none, tight, normal ou loose.

display_modestring

normal (colunas lado a lado) ou tabs (cada coluna vira uma aba).

visibilityobject

Visibilidade por dispositivo.

bg_colorstring

Cor de fundo simples, quando definida. O fundo de design tem prioridade.

bg_imagestring

Imagem de fundo simples, quando definida.

usergroup_idsstring[]

Grupos de compradores que veem a linha. Ausente quando vazio.

custom_classstring

Classe CSS extra aplicada à linha.

custom_cssstring

CSS livre da linha (tags <script> e @import são removidos ao gravar).

designobject

Camada de estilo universal. Ausente quando vazia.

columnsarray

Colunas da linha (só vem quando a linha é carregada com filhos).

Erros

Status	Quando	Corpo de exemplo
400	O id de row no caminho não é um inteiro.	`{"error":"invalid row id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to update row","detail":"..."}`

Excluir linha

Remove a linha e, em cascata, suas colunas e blocos.

DELETE/api/v1/admin/advanced-layouts/rows/{id}Admin

Excluir uma linha

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico da linha.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/advanced-layouts/rows/8029" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída

json

{
  "message": "row deleted"
}

Erros

Status	Quando	Corpo de exemplo
400	O id de row no caminho não é um inteiro.	`{"error":"invalid row id","detail":"id must be an integer"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Linha não existe.	`{"error":"row not found","detail":"8029"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to delete row","detail":"..."}`

Reordenar linhas

Define a nova ordem: a linha na posição 0 do array vira a primeira, e assim por diante. Ids que não pertencem ao contêiner são ignorados em silêncio.

PUT/api/v1/admin/advanced-layouts/containers/{id}/rows/reorderAdmin

Reordenar as linhas de um contêiner

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do contêiner.

Corpo da requisição

row_idsinteger[]obrigatório

Ids das linhas na ordem desejada. Não pode ser vazio.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/containers/11056/rows/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "row_ids": [
      8031,
      8029,
      8030
    ]
  }'

Resposta

200Reordenadas

json

{
  "message": "rows reordered"
}

Erros

Status	Quando	Corpo de exemplo
400	O id de container no caminho não é um inteiro.	`{"error":"invalid container id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`row_ids` vazio ou ausente.	`{"error":"row_ids is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to reorder rows","detail":"..."}`

Veja também

API atual/Referência completa/Layouts avançados

Contêineres e linhas

Alterna a herança de um contêiner e cria, edita, exclui e reordena linhas.

Atualizar contêiner

uses_default: true faz o contêiner usar o da página padrão; false faz a página ter o seu próprio, mantendo as linhas que já tinha (alternar não apaga nada). Envie pelo menos um dos campos.

PATCH/api/v1/admin/advanced-layouts/containers/{id}Admin

Atualizar herança ou estilo do contêiner

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do contêiner.

Corpo da requisição

uses_defaultboolean

true herda da página padrão; false usa linhas próprias. No content e na página padrão o valor é sempre false.

designobject

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/advanced-layouts/containers/11054" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uses_default": false
  }'

Resposta

200Contêiner atualizado

json

{
  "id": 11054,
  "page_id": 2929,
  "position": "top_panel",
  "sort_order": 0,
  "uses_default": false,
  "rows": []
}

Campos da resposta

idinteger

Id do contêiner.

page_idinteger

Página dona.

positionstring

top_panel, header, content ou footer.

sort_orderinteger

Ordem entre os contêineres.

uses_defaultboolean

Herda da página padrão.

designobject

Camada de estilo universal.

rowsarray

Linhas do contêiner, com colunas e blocos.

Erros

Status	Quando	Corpo de exemplo
400	O id de container no caminho não é um inteiro.	`{"error":"invalid container id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Contêiner não existe.	`{"error":"container not found","detail":"11054"}`
500	Nenhum campo enviado (`no fields to update`) ou falha de banco.	`{"error":"failed to update container","detail":"no fields to update"}`

Criar linha

Adiciona uma linha vazia ao contêiner. Em seguida crie colunas nela e blocos nas colunas.

POST/api/v1/admin/advanced-layouts/containers/{id}/rowsAdmin

Criar uma linha no contêiner

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do contêiner.

Corpo da requisição

sort_orderintegerpadrão: 0

Posição da linha no contêiner.

full_widthbooleanpadrão: false

Largura total da tela.

bg_colorstring

Cor de fundo simples (prefira design).

bg_imagestring

Imagem de fundo simples.

spacingstringpadrão: normal

nonetightnormalloose

Espaçamento vertical.

display_modestringpadrão: normal

normaltabs

Como as colunas aparecem.

visibilityobject

Visibilidade por dispositivo. Chaves desktop, tablet e mobile, valores booleanos. Se omitido na criação, vale true nos três.

usergroup_idsstring[]

Restringe a visibilidade a grupos de compradores. Vazio (padrão) mostra a todos. Aceita os atalhos guest (visitante anônimo) e registered (logado), além de UUIDs de grupos.

custom_classstring

Classe CSS extra.

custom_cssstring

CSS livre da linha.

designobject

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/containers/11056/rows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_width": true,
    "spacing": "loose"
  }'

Resposta

201Linha criada

json

{
  "id": 8029,
  "container_id": 11056,
  "sort_order": 0,
  "full_width": false,
  "spacing": "normal",
  "display_mode": "normal",
  "visibility": {
    "desktop": true,
    "tablet": true,
    "mobile": true
  }
}

Campos da resposta

idinteger

Id da linha.

container_idinteger

Id do contêiner dono da linha.

sort_orderinteger

Posição da linha dentro do contêiner, a partir de 0.

full_widthboolean

true faz a linha ocupar a largura inteira da tela, sem o limite de largura do tema.

spacingstring

Espaçamento vertical: none, tight, normal ou loose.

display_modestring

normal (colunas lado a lado) ou tabs (cada coluna vira uma aba).

visibilityobject

Visibilidade por dispositivo.

bg_colorstring

Cor de fundo simples, quando definida. O fundo de design tem prioridade.

bg_imagestring

Imagem de fundo simples, quando definida.

usergroup_idsstring[]

Grupos de compradores que veem a linha. Ausente quando vazio.

custom_classstring

Classe CSS extra aplicada à linha.

custom_cssstring

CSS livre da linha (tags <script> e @import são removidos ao gravar).

designobject

Camada de estilo universal. Ausente quando vazia.

columnsarray

Colunas da linha (só vem quando a linha é carregada com filhos).

Erros

Status	Quando	Corpo de exemplo
400	O id de container no caminho não é um inteiro.	`{"error":"invalid container id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to create row","detail":"..."}`

Atualizar linha

Altera só os campos enviados. visibility é enviado como objeto completo; usergroup_ids enviado como lista substitui a lista inteira.

PUT/api/v1/admin/advanced-layouts/rows/{id}Admin

Atualizar uma linha

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico da linha.

Corpo da requisição

sort_orderinteger

Posição.

full_widthboolean

Largura total.

bg_colorstring

Cor de fundo simples.

bg_imagestring

Imagem de fundo simples.

spacingstring

nonetightnormalloose

Espaçamento vertical.

display_modestring

normaltabs

Modo das colunas.

visibilityobject

Visibilidade por dispositivo. Chaves desktop, tablet e mobile, valores booleanos. Se omitido, o valor atual é mantido. Se enviado, substitui o objeto inteiro.

usergroup_idsstring[]

Restringe a visibilidade a grupos de compradores. Vazio (padrão) mostra a todos. Aceita os atalhos guest (visitante anônimo) e registered (logado), além de UUIDs de grupos.

custom_classstring

Classe CSS extra.

custom_cssstring

CSS livre.

designobject

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/rows/8029" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_mode": "tabs",
    "visibility": {
      "desktop": true,
      "tablet": true,
      "mobile": false
    }
  }'

Resposta

200Linha atualizada

json

{
  "id": 8029,
  "container_id": 11056,
  "sort_order": 0,
  "full_width": false,
  "spacing": "normal",
  "display_mode": "tabs",
  "visibility": {
    "desktop": true,
    "tablet": true,
    "mobile": false
  }
}

Campos da resposta

idinteger

Id da linha.

container_idinteger

Id do contêiner dono da linha.

sort_orderinteger

Posição da linha dentro do contêiner, a partir de 0.

full_widthboolean

true faz a linha ocupar a largura inteira da tela, sem o limite de largura do tema.

spacingstring

Espaçamento vertical: none, tight, normal ou loose.

display_modestring

normal (colunas lado a lado) ou tabs (cada coluna vira uma aba).

visibilityobject

Visibilidade por dispositivo.

bg_colorstring

Cor de fundo simples, quando definida. O fundo de design tem prioridade.

bg_imagestring

Imagem de fundo simples, quando definida.

usergroup_idsstring[]

Grupos de compradores que veem a linha. Ausente quando vazio.

custom_classstring

Classe CSS extra aplicada à linha.

custom_cssstring

CSS livre da linha (tags <script> e @import são removidos ao gravar).

designobject

Camada de estilo universal. Ausente quando vazia.

columnsarray

Colunas da linha (só vem quando a linha é carregada com filhos).

Erros

Status	Quando	Corpo de exemplo
400	O id de row no caminho não é um inteiro.	`{"error":"invalid row id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to update row","detail":"..."}`

Excluir linha

Remove a linha e, em cascata, suas colunas e blocos.

DELETE/api/v1/admin/advanced-layouts/rows/{id}Admin

Excluir uma linha

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico da linha.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/advanced-layouts/rows/8029" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída

json

{
  "message": "row deleted"
}

Erros

Status	Quando	Corpo de exemplo
400	O id de row no caminho não é um inteiro.	`{"error":"invalid row id","detail":"id must be an integer"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Linha não existe.	`{"error":"row not found","detail":"8029"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to delete row","detail":"..."}`

Reordenar linhas

Define a nova ordem: a linha na posição 0 do array vira a primeira, e assim por diante. Ids que não pertencem ao contêiner são ignorados em silêncio.

PUT/api/v1/admin/advanced-layouts/containers/{id}/rows/reorderAdmin

Reordenar as linhas de um contêiner

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do contêiner.

Corpo da requisição

row_idsinteger[]obrigatório

Ids das linhas na ordem desejada. Não pode ser vazio.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/containers/11056/rows/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "row_ids": [
      8031,
      8029,
      8030
    ]
  }'

Resposta

200Reordenadas

json

{
  "message": "rows reordered"
}

Erros

Status	Quando	Corpo de exemplo
400	O id de container no caminho não é um inteiro.	`{"error":"invalid container id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`row_ids` vazio ou ausente.	`{"error":"row_ids is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to reorder rows","detail":"..."}`