Blocos

Blocos são os componentes modulares que formam o layout da loja; a API de Blocks permite gerenciá-los por código.

Um bloco é uma peça da sua loja virtual: um menu de navegação, um banner, uma lista de produtos, um formulário de busca ou um trecho de HTML personalizado. Os administradores organizam os blocos nos layouts para dar forma às páginas da loja, e a API de Blocks permite fazer o mesmo trabalho por código, para integrações sob medida e para a personalização automatizada da loja.

Toda chamada usa as credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY) e o endereço da sua loja ($BASE_URL), então os endpoints abaixo aparecem como $BASE_URL/api/blocks.

Como funciona

Olhe um bloco existente
O jeito mais fácil de saber quais propriedades um bloco precisa é criar um no painel de administração e lê-lo de volta com Obter um bloco.
Crie o bloco
Envie um POST com o type, o name e as properties (incluindo o template). Veja Criar um bloco.
Mantenha o bloco
Altere-o com Atualizar um bloco e remova-o com Excluir um bloco.

A visão geral desta seção não descreve uma chamada que liste todos os blocos.

Conceitos principais

Tipos comuns de bloco

Tipo de bloco	Descrição	Usos comuns
Menus de navegação	Oferece links de navegação para as várias áreas da loja	Navegação do cabeçalho, do rodapé e da lateral
Blocos de banner	Exibe conteúdo promocional, imagens ou chamadas para ação	Carrosséis da página inicial, avisos promocionais
Blocos de produtos	Mostra produtos em vários formatos e agrupamentos	Produtos em destaque, lançamentos, itens relacionados
Formulários de busca	Permite aos clientes buscar no catálogo de produtos	Busca no cabeçalho, páginas de busca avançada
Blocos de conteúdo	Exibe HTML, texto ou mídia personalizados	Informações sobre a empresa, textos de políticas, histórias da marca
Elementos interativos	Oferece funcionalidade de interação com o usuário	Formulários de contato, cadastro de newsletter, feed social

Como é um bloco

A visão geral mostra este objeto de bloco.

json

{
  "block_id": "12345",
  "type": "products",
  "name": "Featured Products",
  "status": "A",
  "position": 10,
  "properties": {
    "template": "blocks/product_grid.tpl",
    "item_number": 4
  }
}

A página Detalhes do bloco descreve cada campo e traz um exemplo para cada tipo comum.

Endpoints

Método	Caminho	Finalidade	Autenticação
GET	`/api/blocks/{block_id}`	Obter um bloco específico	Administrador
POST	`/api/blocks`	Criar um bloco	Administrador
PUT	`/api/blocks/{block_id}`	Atualizar um bloco	Administrador
DELETE	`/api/blocks/{block_id}`	Excluir um bloco	Administrador

Erros comuns

Criar um bloco sem properties. O type, o name e as properties (com o template) são obrigatórios.
Adivinhar as propriedades de um tipo de bloco. Crie o bloco antes no painel de administração e leia-o com um GET.
Atualizar sem o type. O campo type é obrigatório na atualização.
Sobrescrever o objeto content inteiro quando você só quer mudar um campo. Leia o bloco primeiro e altere só o que for preciso.
Excluir um bloco que ainda é usado por um layout ou página, o que pode quebrar a exibição dessa página.

Próximos passos

Obter um bloco

Leia um bloco e entenda os campos dele.

Detalhes do bloco

Todos os campos, as propriedades comuns e a estrutura do conteúdo.

Criar um bloco

Os parâmetros, os tipos aceitos e dois exemplos.

Atualizar um bloco

Mude o tipo, o nome ou as propriedades de um bloco.