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

bash
curl "$BASE_URL/api/v1/admin/scripts?extension_point=on_shipping_filter&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Scripts
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
}

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

bash
curl "$BASE_URL/api/v1/admin/scripts/5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Script
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"
}

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

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}'

Resposta

201Script criado
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"
}

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

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;"}'

Resposta

200Script atualizado
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"
}

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

bash
curl -X DELETE "$BASE_URL/api/v1/admin/scripts/5be3d1d8-44b9-49d2-83be-e1fd9bec2ce7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído
json
{
  "message": "script deleted"
}

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