API legada/Referência completa/Blocos e idiomas

Blocos: escrita

Cria um bloco em um layout, atualiza um bloco existente e o exclui.

Três operações para manter os blocos de um layout. Todas pedem usuário administrador e exigem o layout_id (número inteiro) do layout em que o bloco está: no corpo para criar, no corpo ou na URL para atualizar, e só na URL (?layout_id=) para excluir. Para descobrir o layout_id e o block_id use Blocos: consulta.

As mudanças valem na hora para quem visita a vitrine. Não há rascunho nem desfazer.

Criar um bloco

POST/api/v1.0/blocksAdmin

Criar um bloco em um layout

O bloco é adicionado ao fim da lista do layout e nasce visível.

Corpo da requisição

layout_idintegerobrigatório

Id do layout. Precisa ser um número JSON (11). Texto como "11" é tratado como ausente.

typestringobrigatório

Tipo do bloco (logo, search_bar...). Define o que a vitrine desenha.

namestring

Título do bloco.

positionstringpadrão: main

Zona da página (header, main, footer...).

orderintegerpadrão: 0

Posição dentro da zona.

contentobject|string

Configuração do bloco. Aceita um objeto ou uma string que contenha JSON. Texto que não é JSON válido é ignorado e o bloco fica com configuração vazia.

POST/api/blocksAdmin

Alias de POST /api/v1.0/blocks

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/blocks. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Atualizar um bloco

PUT/api/v1.0/blocks/{id}Admin

Atualizar um bloco

Atualiza só os campos enviados; o resto fica como estava. O content enviado substitui a configuração inteira do bloco (não mescla com a anterior).

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Parâmetros de consulta

layout_idinteger

Id do layout, como alternativa ao campo do corpo. Se vierem os dois, vale a URL.

Corpo da requisição

layout_idinteger

Id do layout do bloco (número). Obrigatório aqui ou na URL.

namestring

Novo título.

typestring

Novo tipo.

positionstring

Nova zona.

orderinteger

Nova posição na zona.

contentobject|string

Nova configuração completa (objeto ou string JSON).

statusstring

AD

A torna o bloco visível. Qualquer outro valor o oculta.

PUT/api/blocks/{id}Admin

Alias de PUT /api/v1.0/blocks/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/blocks/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Excluir um bloco

DELETE/api/v1.0/blocks/{id}Admin

Excluir um bloco

Remove o bloco do layout e reajusta a ordem dos blocos restantes de cada zona. A exclusão é definitiva e a resposta não tem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Parâmetros de consulta

layout_idintegerobrigatório

Id do layout do bloco.

DELETE/api/blocks/{id}Admin

Alias de DELETE /api/v1.0/blocks/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/blocks/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

# Criar
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/blocks" \
  -H "Content-Type: application/json" \
  -d '{"layout_id":11,"type":"search_bar","name":"Busca","position":"header","order":1,"content":{"placeholder":"Buscar produtos"}}'

# Atualizar
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/blocks/$BLOCK_ID?layout_id=11" \
  -H "Content-Type: application/json" \
  -d '{"name":"Busca principal","status":"A"}'

# Excluir
curl -u "$EMAIL:$API_KEY" -X DELETE "$BASE_URL/api/v1.0/blocks/$BLOCK_ID?layout_id=11"

Resposta

201Bloco criado

json

{ "block_id": "5d79e395-3eb6-45e7-a368-dd832e6bd679" }

200Bloco atualizado

json

{ "block_id": "5d79e395-3eb6-45e7-a368-dd832e6bd679" }

204Bloco excluído

Sem corpo.

Campos da resposta

block_iduuid

Id do bloco criado ou atualizado. Na URL sem v1.0, um inteiro que não funciona de volta no caminho.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"message": "Invalid JSON", "status": 400}`
400	`layout_id` ausente ou não numérico no `POST`	`{"message": "Field 'layout_id' is required", "status": 400}`
400	`type` ausente no `POST`	`{"message": "Field 'type' is required", "status": 400}`
400	`layout_id` ausente no `PUT`	`{"message": "Field or query param 'layout_id' is required", "status": 400}`
400	`layout_id` ausente no `DELETE`	`{"message": "Query param 'layout_id' is required", "status": 400}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
403	Usuário que não é administrador	`{"message": "Forbidden: admin scope required", "status": 403}`
500	Layout inexistente	`{"message": "layout not found", "status": 500}`
500	Bloco inexistente no layout (`PUT` e `DELETE`)	`{"message": "block not found", "status": 500}`

Veja também

API legada/Referência completa/Blocos e idiomas

Blocos: escrita

Cria um bloco em um layout, atualiza um bloco existente e o exclui.

As mudanças valem na hora para quem visita a vitrine. Não há rascunho nem desfazer.

Criar um bloco

POST/api/v1.0/blocksAdmin

Criar um bloco em um layout

O bloco é adicionado ao fim da lista do layout e nasce visível.

Corpo da requisição

layout_idintegerobrigatório

Id do layout. Precisa ser um número JSON (11). Texto como "11" é tratado como ausente.

typestringobrigatório

Tipo do bloco (logo, search_bar...). Define o que a vitrine desenha.

namestring

Título do bloco.

positionstringpadrão: main

Zona da página (header, main, footer...).

orderintegerpadrão: 0

Posição dentro da zona.

contentobject|string

Configuração do bloco. Aceita um objeto ou uma string que contenha JSON. Texto que não é JSON válido é ignorado e o bloco fica com configuração vazia.

POST/api/blocksAdmin

Alias de POST /api/v1.0/blocks

Mesmo corpo, mesma resposta e mesmo comportamento de POST /api/v1.0/blocks. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Atualizar um bloco

PUT/api/v1.0/blocks/{id}Admin

Atualizar um bloco

Atualiza só os campos enviados; o resto fica como estava. O content enviado substitui a configuração inteira do bloco (não mescla com a anterior).

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Parâmetros de consulta

layout_idinteger

Id do layout, como alternativa ao campo do corpo. Se vierem os dois, vale a URL.

Corpo da requisição

layout_idinteger

Id do layout do bloco (número). Obrigatório aqui ou na URL.

namestring

Novo título.

typestring

Novo tipo.

positionstring

Nova zona.

orderinteger

Nova posição na zona.

contentobject|string

Nova configuração completa (objeto ou string JSON).

statusstring

AD

A torna o bloco visível. Qualquer outro valor o oculta.

PUT/api/blocks/{id}Admin

Alias de PUT /api/v1.0/blocks/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de PUT /api/v1.0/blocks/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Excluir um bloco

DELETE/api/v1.0/blocks/{id}Admin

Excluir um bloco

Remove o bloco do layout e reajusta a ordem dos blocos restantes de cada zona. A exclusão é definitiva e a resposta não tem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Parâmetros de consulta

layout_idintegerobrigatório

Id do layout do bloco.

DELETE/api/blocks/{id}Admin

Alias de DELETE /api/v1.0/blocks/{id}

Mesmo corpo, mesma resposta e mesmo comportamento de DELETE /api/v1.0/blocks/{id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

# Criar
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/blocks" \
  -H "Content-Type: application/json" \
  -d '{"layout_id":11,"type":"search_bar","name":"Busca","position":"header","order":1,"content":{"placeholder":"Buscar produtos"}}'

# Atualizar
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/blocks/$BLOCK_ID?layout_id=11" \
  -H "Content-Type: application/json" \
  -d '{"name":"Busca principal","status":"A"}'

# Excluir
curl -u "$EMAIL:$API_KEY" -X DELETE "$BASE_URL/api/v1.0/blocks/$BLOCK_ID?layout_id=11"

Resposta

201Bloco criado

json

{ "block_id": "5d79e395-3eb6-45e7-a368-dd832e6bd679" }

200Bloco atualizado

json

{ "block_id": "5d79e395-3eb6-45e7-a368-dd832e6bd679" }

204Bloco excluído

Sem corpo.

Campos da resposta

block_iduuid

Id do bloco criado ou atualizado. Na URL sem v1.0, um inteiro que não funciona de volta no caminho.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"message": "Invalid JSON", "status": 400}`
400	`layout_id` ausente ou não numérico no `POST`	`{"message": "Field 'layout_id' is required", "status": 400}`
400	`type` ausente no `POST`	`{"message": "Field 'type' is required", "status": 400}`
400	`layout_id` ausente no `PUT`	`{"message": "Field or query param 'layout_id' is required", "status": 400}`
400	`layout_id` ausente no `DELETE`	`{"message": "Query param 'layout_id' is required", "status": 400}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
403	Usuário que não é administrador	`{"message": "Forbidden: admin scope required", "status": 403}`
500	Layout inexistente	`{"message": "layout not found", "status": 500}`
500	Bloco inexistente no layout (`PUT` e `DELETE`)	`{"message": "block not found", "status": 500}`