Blocos e idiomas
Como a Venddor 1.0 expunha os blocos de layout da vitrine e a lista de idiomas, e como a plataforma atual responde a esse contrato.
Na plataforma antiga (Venddor 1.0), a aparência de cada página da loja era montada com blocos: o logotipo, a barra de busca, um carrossel de banners, uma grade de produtos. Integradores e apps antigos leem e editam esses blocos por /api/blocks. Esta seção documenta esse contrato, mais a lista de idiomas (/api/languages) que acompanhava a configuração da loja.
São rotas de compatibilidade, mantidas para quem já integrou o layout da loja pelo contrato da 1.0.
Como funciona
A leitura percorre os layouts da loja (até 250) e devolve os blocos de todos eles numa lista única, cada bloco com o layout_id a que pertence. Guarde esse layout_id: ele é obrigatório para atualizar e excluir.
| Campo do bloco | Significado |
|---|---|
block_id | Id do bloco (UUID na URL /api/v1.0). |
name | Título do bloco. |
type | Tipo do bloco, por exemplo logo, search_bar. Define o que a vitrine desenha. |
position | Zona da página onde o bloco fica (header, main, footer...). Novo bloco sem posição entra em main. |
order | Posição dentro da zona, a partir de 0. |
content | A configuração do bloco, como texto JSON (string), não como objeto. |
layout_id | Id inteiro do layout dono. |
company_id | Sempre 0. Mantido por compatibilidade. |
status | A visível, D oculto. |
Conceitos-chave
content é uma string
Na resposta, content é o JSON do bloco serializado em texto ("{\"max_height\":60}"). Para criar e atualizar você pode mandar tanto uma string JSON quanto um objeto; a plataforma aceita os dois.
Duas URLs, dois formatos de id
Como nas demais rotas de compatibilidade, /api/v1.0/... usa UUID e /api/... troca UUIDs por inteiros derivados. No caso dos blocos a troca quebra o ciclo: a lista em /api/blocks devolve block_id numérico, mas GET /api/blocks/{numérico} responde 404 e DELETE responde 500. Só o UUID funciona no caminho. Resolva usando /api/v1.0/blocks.
Erros
Erros vêm como {"message": "...", "status": 400}. Atenção: bloco ou layout inexistente nas escritas responde 500, não 404 (veja as páginas de leitura e escrita).
Endpoints
| Método e caminho | Para que serve | Autenticação | Página |
|---|---|---|---|
GET /api/v1.0/blocks e /api/blocks | Lista blocos de todos os layouts | Qualquer usuário autenticado | Blocos: consulta |
GET /api/v1.0/blocks/{id} e /api/blocks/{id} | Lê um bloco | Qualquer usuário autenticado | Blocos: consulta |
POST /api/v1.0/blocks e /api/blocks | Cria um bloco em um layout | Administrador | Blocos: escrita |
PUT /api/v1.0/blocks/{id} e /api/blocks/{id} | Atualiza um bloco | Administrador | Blocos: escrita |
DELETE /api/v1.0/blocks/{id} e /api/blocks/{id} | Exclui um bloco | Administrador | Blocos: escrita |
GET /api/v1.0/languages | Lista os idiomas | Qualquer usuário autenticado | Idiomas |
GET /api/v1.0/languages/{id} | Lê um idioma | Qualquer usuário autenticado | Idiomas |
Erros comuns
- Mandar
layout_idcomo texto."layout_id": "11"é tratado como ausente e a resposta é400 Field 'layout_id' is required. Envie o número11. - Esquecer o
layout_idna exclusão. ODELETEpede?layout_id=na URL e responde 400 sem ele. - Usar o id numérico de
/api/blocksno caminho. Não é traduzido de volta. Use/api/v1.0/blocks. - Esperar 404 ao editar bloco inexistente. O erro vem como 500 com
block not foundoulayout not found. - Ler
contentcomo objeto. É uma string JSON; façaJSON.parse. - Achar que
/api/v1.0/languageslista os idiomas da loja. A lista é fixa empteen.