VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Scripts da loja

Gerenciar scripts

Lista, consulta, cria, altera e exclui os scripts JavaScript da loja.

Um script é um pedacinho de JavaScript que a loja instala em um ponto de extensão: um momento definido do funcionamento da plataforma (validar o checkout, filtrar fretes, reagir a um evento...). Todas as rotas desta página exigem o privilégio manage_scripts ou manage_settings. Veja os pontos de extensão e as regras de execução na home da seção.

Listar scripts

GET/api/v1/admin/scriptsAdmin

Lista paginada dos scripts

Parâmetros de consulta

extension_pointstring
on_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_trigger
Filtra por ponto de extensão (igualdade exata).
searchstring
Texto contido no nome ou no ponto de extensão, sem diferenciar maiúsculas.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Acima de 100 volta para 20.

Exemplo de requisição

Resposta

200Scripts

Campos da resposta

scriptsarray
Os scripts da página, com o code completo.
total / page / per_page / total_pagesinteger
Paginação.
scripts[].iduuid
Id do script.
scripts[].extension_pointstring
on_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_trigger
Onde o script roda. Não muda depois de criado.
scripts[].namestring
Nome.
scripts[].descriptionstring
Descrição. Ausente quando vazia.
scripts[].codestring
Código JavaScript completo.
scripts[].versioninteger
Número da versão. Começa em 1 e sobe a cada alteração do code.
scripts[].is_activeboolean
Só scripts ativos são executados.
scripts[].created_byuuid
Quem criou, quando informado. Ausente caso contrário.
scripts[].created_at / updated_atstring
Criação e última alteração (RFC 3339, UTC).
scripts[].event_typesarray
Só em scripts on_event_trigger: os eventos da plataforma que disparam o script.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}
500Falha ao consultar.{"error":"failed to list scripts","detail":"..."}
Respostas grandes

Cada item traz o código inteiro. Em lojas com muitos scripts, use per_page pequeno.

Consultar um script

GET/api/v1/admin/scripts/{id}Admin

Um script pelo id

Parâmetros de caminho

iduuidobrigatório
Id do script.

Exemplo de requisição

Resposta

200Script

Campos da resposta

iduuid
Id do script.
extension_pointstring
on_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_trigger
Onde o script roda. Não muda depois de criado.
namestring
Nome.
descriptionstring
Descrição. Ausente quando vazia.
codestring
Código JavaScript completo.
versioninteger
Número da versão. Começa em 1 e sobe a cada alteração do code.
is_activeboolean
Só scripts ativos são executados.
created_byuuid
Quem criou, quando informado. Ausente caso contrário.
created_at / updated_atstring
Criação e última alteração (RFC 3339, UTC).
event_typesarray
Só em scripts on_event_trigger: os eventos da plataforma que disparam o script.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}
404Script não existe.{"error":"script not found"}
500id não é um UUID válido (a mensagem vem em português). Em vários endpoints, um UUID válido porém inexistente também responde 500.{"error":"failed to get script","detail":"o valor \"abc\" não é um uuid válido..."}

Criar script

POST/api/v1/admin/scriptsAdmin

Cria um script

Corpo da requisição

extension_pointstringobrigatório
on_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_trigger
Onde o script roda. Obrigatório.
namestringobrigatório
Nome. Obrigatório.
codestringobrigatório
Código JavaScript. Obrigatório. A sintaxe é verificada ao salvar (o código não é executado).
descriptionstring
Descrição livre.
is_activebooleanpadrão: false
Cria já ativo. Se omitido, o script nasce inativo.
event_typesarray
Para on_event_trigger: eventos que disparam o script. Os valores não são validados na gravação.
created_bystring
Id de quem criou, se quiser registrar.

Exemplo de requisição

Resposta

201Script criado

Campos da resposta

iduuid
Id do script.
demais campos-
Os mesmos de Consultar um script.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}
400Corpo inválido, ou name, code ou extension_point ausente.{"error":"extension_point is required"}
500Ponto de extensão inexistente ou erro de sintaxe no código (apesar de ser culpa do chamador, o status é 500).{"error":"failed to create script","detail":"validation failed: invalid extension point: bogus"}
Teste antes de ativar

Crie com is_active falso e rode o código com dados de exemplo em Testar a seco. Só ative quando o resultado estiver certo.

Alterar script

PUT/api/v1/admin/scripts/{id}Admin

Altera um script (parcial)

Parâmetros de caminho

iduuidobrigatório
Id do script.

Corpo da requisição

namestring
Novo nome.
descriptionstring
Nova descrição.
codestring
Novo código. Valida a sintaxe, sobe version em 1 e guarda a versão anterior no histórico.
is_activeboolean
Liga ou desliga o script.
event_typesarray
Substitui a lista de eventos. Enviar [] limpa a lista; omitir mantém.

Exemplo de requisição

Resposta

200Script atualizado

Campos da resposta

campos-
Os mesmos de Consultar um script, com os novos valores.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}
400Corpo não é JSON válido.{"error":"invalid request body","detail":"..."}
500Script inexistente, id inválido ou código com erro de sintaxe.{"error":"failed to update script","detail":"script 5be3d1d8-... not found"}
Só campos enviados mudam

A atualização é parcial. O extension_point não pode ser trocado: crie outro script.

Excluir script

DELETE/api/v1/admin/scripts/{id}Admin

Exclui um script

Parâmetros de caminho

iduuidobrigatório
Id do script.

Exemplo de requisição

Resposta

200Excluído

Campos da resposta

messagestring
Sempre script deleted.

Erros

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}
500Script inexistente (inclusive se já foi excluído) ou id inválido.{"error":"failed to delete script","detail":"script 5be3d1d8-... not found"}
Exclusão definitiva

Para só parar de executar, use Ligar e desligar.

Veja também

  • Testar e ligar
  • Versões e reversão
Anterior
Scripts da loja
Próxima
Testar e ligar
Nesta página
  • Listar scripts
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um script
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar script
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar script
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir script
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/scripts?extension_point=on_shipping_filter&per_page=20" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/scripts/5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/scripts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"extension_point": "on_shipping_filter", "name": "Esconder frete expresso em carrinho pequeno", "description": "Remove o frete expresso quando o carrinho tem menos de R$ 50,00", "code": "var result = input.rates.filter(function (r) { return r.type !== \"express\" || input.cart.total >= 5000; });", "is_active": false}'
bash
curl -X PUT "$BASE_URL/api/v1/admin/scripts/5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "var result = input.rates;"}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/scripts/5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "scripts": [
    {
      "id": "5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7",
      "extension_point": "on_shipping_filter",
      "name": "Esconder frete expresso em carrinho pequeno",
      "description": "Remove o frete expresso quando o carrinho tem menos de R$ 50,00",
      "code": "var result = input.rates.filter(function (r) { return r.type !== \"express\" || input.cart.total >= 5000; });",
      "version": 1,
      "is_active": false,
      "created_at": "2026-10-11T21:05:23.555076Z",
      "updated_at": "2026-10-11T21:05:23.555076Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
json
{
  "id": "5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7",
  "extension_point": "on_shipping_filter",
  "name": "Esconder frete expresso em carrinho pequeno",
  "description": "Remove o frete expresso quando o carrinho tem menos de R$ 50,00",
  "code": "var result = input.rates.filter(function (r) { return r.type !== \"express\" || input.cart.total >= 5000; });",
  "version": 1,
  "is_active": false,
  "created_at": "2026-10-11T21:05:23.555076Z",
  "updated_at": "2026-10-11T21:05:23.555076Z"
}
json
{
  "id": "5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7",
  "extension_point": "on_shipping_filter",
  "name": "Esconder frete expresso em carrinho pequeno",
  "description": "Remove o frete expresso quando o carrinho tem menos de R$ 50,00",
  "code": "var result = input.rates.filter(function (r) { return r.type !== \"express\" || input.cart.total >= 5000; });",
  "version": 1,
  "is_active": false,
  "created_at": "2026-10-11T21:05:23.555076Z",
  "updated_at": "2026-10-11T21:05:23.555076Z"
}
json
{
  "id": "5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7",
  "extension_point": "on_shipping_filter",
  "name": "Esconder frete expresso em carrinho pequeno",
  "description": "Remove o frete expresso quando o carrinho tem menos de R$ 50,00",
  "code": "var result = input.rates;",
  "version": 2,
  "is_active": false,
  "created_at": "2026-10-11T21:05:23.555076Z",
  "updated_at": "2026-10-11T21:05:23.786239Z"
}
json
{
  "message": "script deleted"
}