API de componentes customizados

Use a API oficial quando sua integração gerencia os arquivos de componentes fora do editor ou fora do Build Kit.

Endereços

Ambiente	Base	Endpoint
Staging	https://api.sandbox.vnda.com.br	/maker/component-external
Produção	https://api.vnda.com.br	/maker/component-external

Autenticação e headers

Envie estes headers em todas as requisições:

Authorization: Bearer <seu_token>
X-Shop-Code: sua_loja
Content-Type: application/json

Operações

Operação	Método	Endpoint
Criar	POST	/maker/component-external
Listar	GET	/maker/component-external
Detalhar	GET	/maker/component-external/{id}
Atualizar	PATCH	/maker/component-external/{id}
Excluir	DELETE	/maker/component-external/{id}

A listagem aceita page, pageSize e search. Ela retorna metadados; busque o detalhe antes de editar para obter todos os arquivos atuais.

Criar, atualizar e disponibilizar

1. Envie POST /maker/component-external para criar o componente.
2. Guarde o id e o name retornados na resposta.
3. A criação disponibiliza o componente no catálogo, mas não o seleciona, configura ou publica automaticamente.
4. Antes de alterar um componente existente, consulte GET /maker/component-external/{id}.
5. Envie PATCH /maker/component-external/{id} com a lista completa de files; arquivos omitidos são removidos.
6. Depois de criar ou atualizar, selecione o componente na área compatível, configure-o, valide a prévia e publique a loja. Veja Validação e publicação.

Exemplo de criação em staging

O comando abaixo cria uma seção de home com um arquivo Liquid principal:

curl --request POST \
  --url https://api.sandbox.vnda.com.br/maker/component-external \
  --header "Authorization: Bearer $VNDA_API_TOKEN" \
  --header "X-Shop-Code: sua_loja" \
  --header "Content-Type: application/json" \
  --data '{
    "component": {
      "name": "banner_home",
      "title": "Banner de Home",
      "description": "Banner institucional da página inicial.",
      "componentTypeId": "home_sections",
      "active": true,
      "schema": {
        "title": "Banner de Home",
        "description": "Banner institucional da página inicial.",
        "component_config": {
          "settings": {},
          "content": {
            "title": {
              "type": "string",
              "title": "Título",
              "default": "Conheça nossa coleção"
            }
          }
        }
      }
    },
    "files": [
      {
        "fileTypeId": "liquid",
        "isMain": true,
        "logicalName": "banner_home",
        "fileContent": "<section class=\"banner-home\"><h2>{{ component_configs.content.title }}</h2></section>"
      }
    ]
  }'

Em produção, substitua a base por https://api.vnda.com.br.

Payload de escrita

POST e PATCH usam component e files na raiz.

{
  "component": {
    "name": "banner_home",
    "title": "Banner de Home",
    "description": "",
    "componentTypeId": "home_sections",
    "active": true,
    "schema": {
      "title": "Banner de Home",
      "description": "",
      "component_config": {
        "settings": {},
        "content": {}
      }
    }
  },
  "files": [
    {
      "fileTypeId": "liquid",
      "isMain": true,
      "logicalName": "banner_home",
      "fileContent": "<section>Banner</section>"
    }
  ]
}

Campo de component	Obrigatório	Regra
name	Sim	Identificador estável em snake_case. Não pode mudar após a criação.
title	Sim	Nome público, com pelo menos três caracteres.
componentTypeId	Sim	Tipo do componente. Não pode mudar após a criação.
active	Sim	Booleano que permite ou impede nova seleção.
schema	Sim	Objeto. Para buttons e icons, use { "component_config": {} }; nos demais, use title, description, settings e content.
description	Não	Descrição pública.
authorName	Sim	Nome da agência ou desenvolvedor responsável pelo componente.
authorContact	Sim	E-mail ou URL de contato do autor.
thumbImage	Não	URL da miniatura do catálogo.
componentSubType	Não	Agrupamento no catálogo da loja. Preencha sempre que possível - facilita a navegação do lojista quando há muitos componentes cadastrados.

logicalName é o identificador técnico do arquivo dentro do componente. Cada item de files tem este formato:

Campo de files	Obrigatório	Regra
fileTypeId	Sim	liquid, scss ou js, desde que permitido pelo tipo de componente.
isMain	Sim	true para o único principal daquele tipo de arquivo; false para auxiliar.
logicalName	Sim	Identificador em snake_case, sem extensão. O principal usa o mesmo name do componente.
fileContent	Sim	Conteúdo não vazio do arquivo.

Cada tipo de arquivo presente exige exatamente um principal. Consulte Arquivos e subarquivos.

Guarde o id e o name retornados na resposta de criação. O id identifica as operações posteriores. Não altere name ou componentTypeId depois da criação.

Respostas

Uma criação ou atualização bem-sucedida retorna 201 ou 200 com o componente e sua identificação:

{
  "message": "Componente cadastrado com sucesso.",
  "component": {
    "id": "uuid",
    "name": "minha_loja_banner_home",
    "title": "Banner de Home",
    "componentTypeId": "home_sections",
    "active": true,
    "files": [
      {
        "id": "uuid-do-arquivo",
        "fileTypeId": "liquid",
        "isMain": true,
        "logicalName": "minha_loja_banner_home",
        "fileContent": "<section>Banner</section>"
      }
    ]
  },
  "filesCount": 2
}

A listagem retorna uma coleção paginada. Os itens da lista trazem metadados; consulte o detalhe pelo id antes de montar uma atualização.

{
  "items": [
    {
      "id": "uuid",
      "name": "minha_loja_banner_home",
      "title": "Banner de Home",
      "componentTypeId": "home_sections",
      "active": true,
      "files": []
    }
  ]
}

Atualização e exclusão

PATCH substitui a lista inteira de arquivos. Antes de atualizar, faça GET /{id}, mantenha todos os arquivos desejados e envie a lista completa. Um arquivo omitido é removido.

DELETE retorna 204 quando o componente pode ser excluído. Se ele ainda estiver selecionado ou em edição na loja, a operação retorna 409; remova a referência antes de tentar novamente. Depois de excluído, ele deixa o catálogo e não pode permanecer em uma configuração válida da loja.

Respostas de erro

Status	Significado comum
400	Header, payload, schema, arquivos ou tipo inválidos.
401	Token ausente ou inválido.
403	Token sem acesso à loja.
404	Loja ou componente não encontrado.
409	Nome em conflito ou componente ainda em uso.

O corpo de erro pode conter uma mensagem e uma lista de detalhes por campo. Use os detalhes para corrigir o payload antes de reenviar.