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
/api/v1/admin/scriptsAdminLista paginada dos scripts
Parâmetros de consulta
extension_pointstringon_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_triggerFiltra por ponto de extensão (igualdade exata).
searchstringTexto contido no nome ou no ponto de extensão, sem diferenciar maiúsculas.
pageintegerpadrão: 1Página, a partir de 1.
per_pageintegerpadrão: 20Itens por página, de 1 a 100. Acima de 100 volta para 20.
Exemplo de requisição
Resposta
200Scripts
Campos da resposta
scriptsarrayOs scripts da página, com o
code completo.total / page / per_page / total_pagesintegerPaginação.
scripts[].iduuidId do script.
scripts[].extension_pointstringon_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_triggerOnde o script roda. Não muda depois de criado.
scripts[].namestringNome.
scripts[].descriptionstringDescrição. Ausente quando vazia.
scripts[].codestringCódigo JavaScript completo.
scripts[].versionintegerNúmero da versão. Começa em 1 e sobe a cada alteração do
code.scripts[].is_activebooleanSó scripts ativos são executados.
scripts[].created_byuuidQuem criou, quando informado. Ausente caso contrário.
scripts[].created_at / updated_atstringCriação e última alteração (RFC 3339, UTC).
scripts[].event_typesarraySó em scripts
on_event_trigger: os eventos da plataforma que disparam o script.Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 401 | Token ausente, inválido ou expirado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário administrador. | {"error":"admin access required"} |
| 403 | O usuário é administrador, mas não tem o privilégio exigido. | {"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]} |
| 500 | Falha ao consultar. | {"error":"failed to list scripts","detail":"..."} |
Consultar um script
/api/v1/admin/scripts/{id}AdminUm script pelo id
Parâmetros de caminho
iduuidobrigatórioId do script.
Exemplo de requisição
Resposta
200Script
Campos da resposta
iduuidId do script.
extension_pointstringon_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_triggerOnde o script roda. Não muda depois de criado.
namestringNome.
descriptionstringDescrição. Ausente quando vazia.
codestringCódigo JavaScript completo.
versionintegerNúmero da versão. Começa em 1 e sobe a cada alteração do
code.is_activebooleanSó scripts ativos são executados.
created_byuuidQuem criou, quando informado. Ausente caso contrário.
created_at / updated_atstringCriação e última alteração (RFC 3339, UTC).
event_typesarraySó em scripts
on_event_trigger: os eventos da plataforma que disparam o script.Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 401 | Token ausente, inválido ou expirado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário administrador. | {"error":"admin access required"} |
| 403 | O usuário é administrador, mas não tem o privilégio exigido. | {"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]} |
| 404 | Script não existe. | {"error":"script not found"} |
| 500 | id 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
/api/v1/admin/scriptsAdminCria um script
Corpo da requisição
extension_pointstringobrigatórioon_checkout_validateon_price_calculateon_shipping_filteron_payment_filteron_order_status_changeon_vendor_commissionon_product_displayon_custom_validationon_search_booston_event_triggerOnde o script roda. Obrigatório.
namestringobrigatórioNome. Obrigatório.
codestringobrigatórioCódigo JavaScript. Obrigatório. A sintaxe é verificada ao salvar (o código não é executado).
descriptionstringDescrição livre.
is_activebooleanpadrão: falseCria já ativo. Se omitido, o script nasce inativo.
event_typesarrayPara
on_event_trigger: eventos que disparam o script. Os valores não são validados na gravação.created_bystringId de quem criou, se quiser registrar.
Exemplo de requisição
Resposta
201Script criado
Campos da resposta
iduuidId do script.
demais campos-Os mesmos de Consultar um script.
Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 401 | Token ausente, inválido ou expirado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário administrador. | {"error":"admin access required"} |
| 403 | O usuário é administrador, mas não tem o privilégio exigido. | {"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]} |
| 400 | Corpo inválido, ou name, code ou extension_point ausente. | {"error":"extension_point is required"} |
| 500 | Ponto 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"} |
Alterar script
/api/v1/admin/scripts/{id}AdminAltera um script (parcial)
Parâmetros de caminho
iduuidobrigatórioId do script.
Corpo da requisição
namestringNovo nome.
descriptionstringNova descrição.
codestringNovo código. Valida a sintaxe, sobe
version em 1 e guarda a versão anterior no histórico.is_activebooleanLiga ou desliga o script.
event_typesarraySubstitui 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
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 401 | Token ausente, inválido ou expirado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário administrador. | {"error":"admin access required"} |
| 403 | O usuário é administrador, mas não tem o privilégio exigido. | {"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]} |
| 400 | Corpo não é JSON válido. | {"error":"invalid request body","detail":"..."} |
| 500 | Script inexistente, id inválido ou código com erro de sintaxe. | {"error":"failed to update script","detail":"script 5be3d1d8-... not found"} |
Excluir script
/api/v1/admin/scripts/{id}AdminExclui um script
Parâmetros de caminho
iduuidobrigatórioId do script.
Exemplo de requisição
Resposta
200Excluído
Campos da resposta
messagestringSempre
script deleted.Erros
| Status | Quando | Exemplo de corpo |
|---|---|---|
| 401 | Token ausente, inválido ou expirado. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário administrador. | {"error":"admin access required"} |
| 403 | O usuário é administrador, mas não tem o privilégio exigido. | {"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]} |
| 500 | Script inexistente (inclusive se já foi excluído) ou id inválido. | {"error":"failed to delete script","detail":"script 5be3d1d8-... not found"} |