VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Módulos

Instalar, configurar e remover

Instala um módulo na loja, liga ou desliga, remove, e liga ou desliga vários de uma vez.

Instalar um módulo cria a instalação na sua loja; ligar é um passo à parte (is_enabled). Instalar já liga o módulo e também liga os módulos de que ele depende. Todas as rotas exigem manage_modules ou manage_settings. Os ids dos caminhos são os do catálogo central, obtidos em Catálogo de módulos.

Instalar

POST/api/v1/admin/modules/{moduleId}/installAdmin

Instalar um módulo

Parâmetros de caminho

moduleIduuidobrigatório
Id do módulo no catálogo central (campo id de Catálogo de módulos). Não é o slug.

Corpo da requisição

configobject
Configuração inicial, conforme o config_schema do módulo. Corpo vazio também é aceito (instala sem configuração).

Exemplo de requisição (instalar)

bash
curl -X POST "$BASE_URL/api/v1/admin/modules/f72a3022-fcbd-4b2e-a516-8de94828357e/install" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config": {}}'

Resposta (instalar)

201Módulo instalado
json
{
  "id": "cb14bf5e-44ba-4134-b4e5-cdeab08a8276",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "module_id": "f72a3022-fcbd-4b2e-a516-8de94828357e",
  "module_name": "Configuração de métricas",
  "module_slug": "metrics-config",
  "is_enabled": true,
  "config": {},
  "settings": {},
  "installed_at": "2026-10-11T21:18:36.184951Z",
  "updated_at": "2026-10-11T21:18:36.184951Z"
}

Campos da resposta

iduuid
Id da instalação (diferente do id do módulo).
tenant_iduuid
Loja.
module_iduuid
Id do módulo no catálogo central.
module_namestring
Nome do módulo.
module_slugstring
Slug do módulo.
is_enabledboolean
Se está ligado na loja. Instalado não significa ligado.
configobject
Configuração da instalação.
settingsobject
Ajustes próprios do módulo (veja Ajustes do módulo).
installed_atstring
Quando foi instalado.
updated_atstring
Última alteração.

Erros (instalar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_modules nem manage_settings (basta um dos dois).{"error":"insufficient privileges","privilege_required_any":["manage_modules","manage_settings"]}
400moduleId não é um UUID (por exemplo, o slug foi enviado no lugar do id).{"error":"invalid moduleId","detail":"moduleId must be a valid UUID"}
400Corpo inválido, ou o módulo é privado de outra loja.{"error":"failed to install module","detail":"..."}
404Nenhum módulo do catálogo tem esse id. Nada é gravado.{"error":"module not found","detail":"nenhum módulo do catálogo central tem o id ..."}

Ligar ou configurar

PUT/api/v1/admin/modules/{moduleId}/configAdmin

Ligar, desligar ou reconfigurar

Parâmetros de caminho

moduleIduuidobrigatório
Id do módulo no catálogo central (campo id de Catálogo de módulos). Não é o slug.

Corpo da requisição

is_enabledbooleanobrigatório
true liga, false desliga. Se omitido, vale false: o módulo é desligado.
configobject
Nova configuração. Substitui a anterior inteira.

Exemplo de requisição (configurar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/modules/f72a3022-fcbd-4b2e-a516-8de94828357e/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": true, "config": {}}'

Resposta (configurar)

200Instalação atualizada
json
{
  "id": "cb14bf5e-44ba-4134-b4e5-cdeab08a8276",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "module_id": "f72a3022-fcbd-4b2e-a516-8de94828357e",
  "module_name": "Configuração de métricas",
  "module_slug": "metrics-config",
  "is_enabled": false,
  "config": {},
  "settings": {},
  "installed_at": "2026-10-11T21:18:36.184951Z",
  "updated_at": "2026-10-11T21:18:36.184951Z"
}

Campos da resposta

iduuid
Id da instalação (diferente do id do módulo).
tenant_iduuid
Loja.
module_iduuid
Id do módulo no catálogo central.
module_namestring
Nome do módulo.
module_slugstring
Slug do módulo.
is_enabledboolean
Se está ligado na loja. Instalado não significa ligado.
configobject
Configuração da instalação.
settingsobject
Ajustes próprios do módulo (veja Ajustes do módulo).
installed_atstring
Quando foi instalado.
updated_atstring
Última alteração.

Erros (configurar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_modules nem manage_settings (basta um dos dois).{"error":"insufficient privileges","privilege_required_any":["manage_modules","manage_settings"]}
400Corpo que não é JSON válido.{"error":"invalid request body","detail":"..."}
400moduleId não é UUID.{"error":"invalid moduleId","detail":"moduleId must be a valid UUID"}
404O módulo não está instalado nesta loja.{"error":"module not installed on this storefront"}
500Falha ao gravar.{"error":"failed to update module config"}

Remover

DELETE/api/v1/admin/modules/{moduleId}Admin

Remover um módulo da loja

Parâmetros de caminho

moduleIduuidobrigatório
Id do módulo no catálogo central (campo id de Catálogo de módulos). Não é o slug.

Exemplo de requisição (remover)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/modules/f72a3022-fcbd-4b2e-a516-8de94828357e" \
  -H "Authorization: Bearer $TOKEN"

Resposta (remover)

200Módulo removido
json
{
  "message": "module uninstalled"
}

Campos da resposta

messagestring
Texto fixo de confirmação, em inglês.

Erros (remover)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_modules nem manage_settings (basta um dos dois).{"error":"insufficient privileges","privilege_required_any":["manage_modules","manage_settings"]}
400moduleId não é UUID, o módulo não existe ou outros módulos instalados dependem dele.{"error":"failed to uninstall module","detail":"cannot uninstall: modules [payout-batches] depend on this module"}

Ligar ou desligar em lote

POST/api/v1/admin/modules/bulk-toggleAdmin

Ligar ou desligar vários módulos

Corpo da requisição

module_idsarrayobrigatório
Ids de módulos (do catálogo central) de módulos já instalados.
is_enabledbooleanobrigatório
true liga, false desliga.
simulatebooleanpadrão: false
true não aplica nada: devolve a prévia do que mudaria e um confirm_token válido por cerca de uma hora.
filterobject
Em vez de module_ids, um critério de seleção. Veja a nota abaixo.
confirm_tokenstring
Token de uma simulação anterior, para aplicar exatamente aquela seleção.

Exemplo de requisição (lote)

bash
curl -X POST "$BASE_URL/api/v1/admin/modules/bulk-toggle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"module_ids": ["f72a3022-fcbd-4b2e-a516-8de94828357e"], "is_enabled": true}'

Resposta (lote)

200Aplicado
json
{
  "toggled": 1,
  "total": 1
}
200Simulação (`simulate: true`)
json
{
  "simulate": true,
  "action": "enable",
  "description": "Ligar módulos",
  "total": 1,
  "sample": [ { "id": "f72a3022-fcbd-4b2e-a516-8de94828357e", "name": "Configuração de métricas", "before": false, "after": true } ],
  "confirm_token": "eyJ0Ijoi...",
  "expires_at": "2026-10-11T22:28:36Z",
  "async": false,
  "by": "filter"
}

Campos da resposta

toggledinteger
Módulos para os quais a ligação foi executada. Conta também ids que não estão instalados (veja a nota).
totalinteger
Ids recebidos.
simulateboolean
Só na simulação.
samplearray
Só na simulação: amostra com id, name, before e after.
confirm_tokenstring
Só na simulação.
expires_atstring
Só na simulação: validade do token.

Erros (lote)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_modules nem manage_settings (basta um dos dois).{"error":"insufficient privileges","privilege_required_any":["manage_modules","manage_settings"]}
400Corpo que não é JSON válido.{"error":"invalid request body","detail":"..."}
400Pedido por critério ou simulação sem is_enabled.{"error":"is_enabled (true liga, false desliga) é obrigatório"}
500Falha ao aplicar.{"error":"failed to bulk toggle modules"}
Ligar também liga as dependências

Instalar ou ligar um módulo liga em cadeia os módulos que ele declara como dependência. Desligar ou remover não faz o inverso: remover um módulo de que outros dependem é recusado (400). Confira antes em Dependências.

`toggled` pode contar ids que não existem

A rota em lote conta cada id que não deu erro, mesmo quando ele não corresponde a uma instalação (nesse caso nada muda). Um id inventado também devolve toggled: 1. Confira o resultado com Módulos instalados.

Simulação antes de aplicar

Com simulate: true a rota só mostra o que mudaria. Para aplicar a mesma seleção, reenvie o corpo com o confirm_token recebido. Uma lista de module_ids simples, sem simulate, é aplicada na hora.

Ligar um módulo muda a barra lateral

Instalar ou ligar também alinha o interruptor de funcionalidade correspondente da plataforma, para que as telas do módulo apareçam no painel na hora, sem outro passo. O cache de módulos da loja é limpo a cada gravação.

Veja também

  • Catálogo de módulos
  • Dependências
  • Ajustes do módulo
Anterior
Catálogo de módulos
Próxima
Dependências e extensões
Nesta página
  • Instalar
  • Exemplo de requisição (instalar)
  • Resposta (instalar)
  • Erros (instalar)
  • Ligar ou configurar
  • Exemplo de requisição (configurar)
  • Resposta (configurar)
  • Erros (configurar)
  • Remover
  • Exemplo de requisição (remover)
  • Resposta (remover)
  • Erros (remover)
  • Ligar ou desligar em lote
  • Exemplo de requisição (lote)
  • Resposta (lote)
  • Erros (lote)
  • Veja também