Scripts da loja

Scripts permitem personalizar o comportamento da loja sem pedir uma alteração na plataforma. Você escreve uma função curta em JavaScript, escolhe em que momento ela deve rodar (o ponto de extensão) e ativa. Exemplos: esconder o frete expresso em carrinhos pequenos, bloquear o checkout sob uma regra própria, filtrar formas de pagamento, reagir a um pedido pago.

Como funciona

O ciclo de vida típico:

1. Escrever e testar
   Use Testar a seco com dados de exemplo até o resultado ficar certo.
2. Criar
   Crie o script inativo, com o ponto de extensão correto.
3. Ativar
   Ligue quando estiver pronto.
4. Evoluir
   Altere o código; se algo der errado, reverta.

Pontos de extensão disponíveis:

Conceitos principais

Como o script recebe e devolve dados

O script recebe os dados do momento na variável global input e devolve o resultado na variável global result (ou, se não houver, no valor da última expressão). O formato de input e do resultado esperado depende do ponto de extensão. Exemplo para on_shipping_filter: var result = input.rates.filter(function (r) { return r.type !== "express" || input.cart.total >= 5000; });

Sandbox

O código roda isolado: sem rede, sem arquivos, sem require, fetch, setTimeout ou eval. Passou de 100 ms ou 10 MB, a execução é interrompida.

Eventos

Um script on_event_trigger informa em event_types quais eventos o disparam: order.created, order.statusChanged, order.paid, order.cancelled, product.created, product.updated, product.deleted, customer.registered, customer.updated, cart.abandoned, review.created, vendor.registered, vendor.approved.

Endpoints

Erros comuns

• Esperar que POST /admin/scripts ative o script: sem is_active: true ele nasce desligado.
• Checar só o status HTTP do teste a seco: erro no código volta 200 com success: false.
• Tentar trocar o extension_point com PUT: o campo é ignorado; crie outro script.
• Usar duration como milissegundos: vem em nanossegundos.
• Esperar que on_price_calculate altere preços: o ponto está declarado, mas nenhum fluxo da plataforma o executa hoje.
• Esperar 404 em ids inexistentes: várias rotas respondem 500 com a mensagem no campo detail.

Próximos passos