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

POSTEditar design com a VI

Envia um retrato da página e um pedido em linguagem natural e recebe operações de edição estruturadas.

É o "Pedir para a VI" do editor de design. Você manda o pedido ("deixe o fundo do banner azul-escuro e o texto branco") junto com um retrato leve dos blocos, linhas e colunas da página; a Venddor Intelligence (VI) devolve uma lista de operações que seu cliente aplica depois com as rotas normais de bloco, linha e coluna. A rota não grava nada na loja.

A VI só ajusta estilo e configuração: nunca adiciona, remove nem move blocos, linhas ou colunas. Cada operação mira exatamente um alvo (block_id, row_id ou column_id). Operações inválidas (sem alvo, com mais de um alvo, tipo desconhecido, caminho que o bloco não suporta) são descartadas antes da resposta, então a lista pode vir menor do que a VI propôs.

POST/api/v1/admin/advanced-layouts/design-ai-editAdmin

Gerar operações de edição de design

Requer o privilégio manage_layouts. O retorno depende de a loja ter a VI habilitada.

Corpo da requisição

requeststringobrigatório

O pedido em linguagem natural. Obrigatório e não vazio.

dispatchstring

Tela que está sendo editada, por exemplo index.index.

selected_block_idinteger

Bloco selecionado no editor. Permite pedidos como "deste bloco".

selected_row_idinteger

Linha selecionada.

selected_column_idinteger

Coluna selecionada.

blocksobject[]

Retrato dos blocos (máximo 80; o excedente é cortado). Cada um: id, type, type_label, name, title_text, aliases[], config, design, custom_css (cortado em 1.800 caracteres), custom_class, column_id, row_id.

rowsobject[]

Retrato das linhas (máximo 60). Cada uma: id, section, full_width, bg_color, bg_image, spacing, display_mode, custom_class, custom_css (cortado em 1.200), visibility, design, column_ids[].

columnsobject[]

Retrato das colunas (máximo 80). Cada uma: id, row_id, width_desktop, width_tablet, width_mobile, custom_class, visibility, design, block_ids[].

settings_by_typeobject

Mapa block_type para a lista de settings (do catálogo) dos tipos presentes na página.

elements_by_typeobject

Mapa block_type para sub-elementos estilizáveis: id, label_pt, selector.

catalogobject

categories[] com id, name e slug (até 200), para a VI traduzir "categoria Calçados" em um id real.

ui_hintsstring[]

Dicas curtas do editor.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/design-ai-edit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Deixe o fundo deste bloco azul-escuro e o texto branco",
    "dispatch": "index.index",
    "selected_block_id": 11081,
    "blocks": [
      {
        "id": 11081,
        "type": "banner_slider",
        "name": "Main Banner",
        "config": {
          "autoplay": true
        }
      }
    ]
  }'

Resposta

200Operações propostas

json

{
  "summary_pt": "Fundo azul-escuro e texto branco no banner.",
  "ops": [
    {
      "kind": "set",
      "block_id": 11081,
      "path": "design.base.background.type",
      "value": "color"
    },
    {
      "kind": "set",
      "block_id": 11081,
      "path": "design.base.background.color",
      "value": "#0f172a"
    },
    {
      "kind": "set",
      "block_id": 11081,
      "path": "design.base.typography.text_color",
      "value": "#ffffff"
    }
  ]
}

200Resposta não interpretável (sem operações)

json

{
  "summary_pt": "Não consegui interpretar a resposta da VI. Tente reformular o pedido.",
  "ops": [],
  "raw": "..."
}

Campos da resposta

summary_ptstring

Frase curta, em português, do que a VI fez.

opsobject[]

Operações a aplicar.

kindstring

setcss

set grava um valor no caminho; css grava declarações CSS para um sub-elemento de bloco (ou para a linha).

block_idinteger

Alvo bloco. Exatamente um entre block_id, row_id, column_id.

row_idinteger

Alvo linha.

column_idinteger

Alvo coluna. Colunas não aceitam css.

pathstring

Só em set: caminho do campo, por exemplo config.bar_bg, design.base.background.color, bg_color, width_desktop ou custom_css.

valueany

Só em set: o valor. Cores em #rrggbb ou rgba().

element_idstring

Só em css de bloco: id do sub-elemento (do elements_by_type).

cssobject

Só em css: mapa propriedade para valor.

rawstring

Só quando a resposta da VI não pôde ser interpretada: o texto bruto.

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido.	`{"error":"invalid_body","detail":"..."}`
400	`request` vazio.	`{"error":"request_required","detail":"request text is required"}`
400	Nenhum bloco, linha ou coluna no retrato.	`{"error":"snapshot_required","detail":"at least one block, row, or column snapshot 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"}`
502	A VI falhou ao responder.	`{"error":"completion_failed","detail":"..."}`
503	A VI não está configurada ou disponível para a loja.	`{"error":"intelligence_unavailable","detail":"..."}`

Veja também

POSTEditar design com a VI

Envia um retrato da página e um pedido em linguagem natural e recebe operações de edição estruturadas.

POST/api/v1/admin/advanced-layouts/design-ai-editAdmin

Gerar operações de edição de design

Requer o privilégio manage_layouts. O retorno depende de a loja ter a VI habilitada.

Corpo da requisição

requeststringobrigatório

O pedido em linguagem natural. Obrigatório e não vazio.

dispatchstring

Tela que está sendo editada, por exemplo index.index.

selected_block_idinteger

Bloco selecionado no editor. Permite pedidos como "deste bloco".

selected_row_idinteger

Linha selecionada.

selected_column_idinteger

Coluna selecionada.

blocksobject[]

rowsobject[]

columnsobject[]

Retrato das colunas (máximo 80). Cada uma: id, row_id, width_desktop, width_tablet, width_mobile, custom_class, visibility, design, block_ids[].

settings_by_typeobject

Mapa block_type para a lista de settings (do catálogo) dos tipos presentes na página.

elements_by_typeobject

Mapa block_type para sub-elementos estilizáveis: id, label_pt, selector.

catalogobject

categories[] com id, name e slug (até 200), para a VI traduzir "categoria Calçados" em um id real.

ui_hintsstring[]

Dicas curtas do editor.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/design-ai-edit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Deixe o fundo deste bloco azul-escuro e o texto branco",
    "dispatch": "index.index",
    "selected_block_id": 11081,
    "blocks": [
      {
        "id": 11081,
        "type": "banner_slider",
        "name": "Main Banner",
        "config": {
          "autoplay": true
        }
      }
    ]
  }'

Resposta

200Operações propostas

json

{
  "summary_pt": "Fundo azul-escuro e texto branco no banner.",
  "ops": [
    {
      "kind": "set",
      "block_id": 11081,
      "path": "design.base.background.type",
      "value": "color"
    },
    {
      "kind": "set",
      "block_id": 11081,
      "path": "design.base.background.color",
      "value": "#0f172a"
    },
    {
      "kind": "set",
      "block_id": 11081,
      "path": "design.base.typography.text_color",
      "value": "#ffffff"
    }
  ]
}

200Resposta não interpretável (sem operações)

json

{
  "summary_pt": "Não consegui interpretar a resposta da VI. Tente reformular o pedido.",
  "ops": [],
  "raw": "..."
}

Campos da resposta

summary_ptstring

Frase curta, em português, do que a VI fez.

opsobject[]

Operações a aplicar.

kindstring

setcss

set grava um valor no caminho; css grava declarações CSS para um sub-elemento de bloco (ou para a linha).

block_idinteger

Alvo bloco. Exatamente um entre block_id, row_id, column_id.

row_idinteger

Alvo linha.

column_idinteger

Alvo coluna. Colunas não aceitam css.

pathstring

Só em set: caminho do campo, por exemplo config.bar_bg, design.base.background.color, bg_color, width_desktop ou custom_css.

valueany

Só em set: o valor. Cores em #rrggbb ou rgba().

element_idstring

Só em css de bloco: id do sub-elemento (do elements_by_type).

cssobject

Só em css: mapa propriedade para valor.

rawstring

Só quando a resposta da VI não pôde ser interpretada: o texto bruto.

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido.	`{"error":"invalid_body","detail":"..."}`
400	`request` vazio.	`{"error":"request_required","detail":"request text is required"}`
400	Nenhum bloco, linha ou coluna no retrato.	`{"error":"snapshot_required","detail":"at least one block, row, or column snapshot 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"}`
502	A VI falhou ao responder.	`{"error":"completion_failed","detail":"..."}`
503	A VI não está configurada ou disponível para a loja.	`{"error":"intelligence_unavailable","detail":"..."}`