Documentação

Guia de instalação

Conecte a loja main e as destinos, instale o snippet e ative sua primeira rota.

Visão geral

Route Payments instala dois pequenos snippets Liquid: um loader na loja main, que decide para qual destino enviar o visitante, e um receptor em cada loja destino, que confirma a chegada e monta o carrinho antes do checkout.

A configuração de rota é buscada de um endpoint de borda, cacheável e sem autenticação de usuário, para não adicionar latência perceptível ao clique.

Importante: Route Payments não é um app da Shopify App Store. A política da Shopify proíbe apps públicos que desviem o checkout, então cada lojista conecta suas lojas com um custom app criado no próprio admin.

1. Conectar as lojas

Conecte a loja main primeiro, depois cada loja destino. Há dois métodos de autenticação; o Dev Dashboard é o recomendado.

App do Dev DashboardRecomendado

Acesse dev.shopify.com/dashboard e crie um novo app.
Defina os escopos exigidos (lista abaixo) e instale o app na loja.
Copie o Client ID e o Client Secret gerados.
Cole ambos no passo "Conectar loja" do onboarding.
A API troca as credenciais por um token via client_credentials, válido por 24h e renovado automaticamente.

Vantagem: sem token de uso único, revogação simples e escopos ajustáveis a qualquer momento.

Token de custom app (alternativo)

No admin da loja: Configurações → Apps e canais de vendas → Desenvolver apps.
Clique em "Criar app" e configure os escopos de Admin API.
Instale o app na loja.
Copie o token shpat_… gerado — ele só é exibido uma vez.

Escopos exigidos

Independente do método, o app precisa destes escopos (alguns só se aplicam a lojas destino):

read_products
write_products
read_orders
read_themes
write_themes
read_inventory
write_inventory
read_price_rules
read_discounts
read_locales
read_markets

write_products, write_inventory e write_themes são usados apenas nas lojas destino e para instalar o snippet.

Ao colar o token ou concluir o app, validamos a conexão (loja, escopos instalados) e mostramos o que falta, com um botão "Verificar de novo". O token nunca é exibido de novo depois de salvo.

2. Como o snippet funciona

O snippet é versionado e instalado automaticamente pelo painel, com backup dos arquivos de tema alterados.

O painel lista os temas de cada loja e pré-seleciona o publicado.
sections.snippet.flow.f2
Verificamos a instalação buscando a home da loja e procurando o marcador do snippet.
O status por loja é: não instalado, instalado, desatualizado ou quebrado (marcador sumiu, por exemplo após troca de tema).
Prefere não conceder write_themes? Use a instalação manual descrita abaixo.

Configuração de borda

O loader busca a configuração da rota por uma chave pública, cacheável por 60 segundos:

GET /v1/edge/config/:publicKeyjson

GET https://api.routepayment.com/v1/edge/config/pk_live_9f2c…

{
  "v": 3,
  "route": { "id": "rt_01H…", "status": "active", "mode": "weighted",
             "sticky": true, "productAction": "buy_now",
             "noHealthy": "native_checkout", "ttl": 60 },
  "destinations": [
    { "id": "st_A", "url": "https://8emrup-yp.myshopify.com", "weight": 70, "healthy": true },
    { "id": "st_B", "url": "https://mxc1y4-8x.myshopify.com", "weight": 30, "healthy": true }
  ],
  "countryRules": { "BR": "st_A" }
}

Beacon de eventos

O receptor confirma a chegada com um beacon, que é a unidade de cobrança quando deduplicado em 30 minutos:

POST /v1/edge/eventshttp

POST https://api.routepayment.com/v1/edge/events
Content-Type: application/json

{ "key": "pk_live_…", "type": "handoff.landed", "handoffId": "hf_01H…",
  "sid": "s_…", "destination": "st_A", "items": 2, "ms": 412, "test": false }

Nunca perde uma venda: se a API cair, o loader usa a última configuração em cache; sem cache, o visitante segue para o checkout nativo da loja.

3. Instalação manual

Para quem prefere não conceder o escopo write_themes, o snippet pode ser colado manualmente no editor de tema.

Crie os arquivos de snippet

snippets/rp-loader.liquidliquid

{% comment %} snippets/rp-loader.liquid (main store) {% endcomment %}
<script>
  window.__rp = { key: "pk_live_9f2c…", v: 3 };
</script>
<script src="https://cdn.routepayment.com/v3/loader.js" async></script>

snippets/rp-receiver.liquidliquid

{% comment %} snippets/rp-receiver.liquid (destination stores) {% endcomment %}
<script>
  window.__rp = { key: "pk_live_9f2c…", role: "receiver" };
</script>
<script src="https://cdn.routepayment.com/v3/receiver.js" async></script>

Renderize o snippet no layout

layout/theme.liquidliquid

{% comment %} theme.liquid — right after <body> {% endcomment %}
{% render 'rp-loader' %}

Cole essa linha logo após a tag <body> em layout/theme.liquid. Na loja destino, use rp-receiver no lugar de rp-loader.

Verifique

Volte ao painel e clique em "Verificar de novo" — buscamos a home da loja e confirmamos que o marcador __rp está presente.

4. Visão geral da API

A API pública (plano Scale) usa a mesma base da API do painel, autenticada por token no lugar de cookie.

Autenticaçãobash

curl https://api.routepayment.com/v1/routes \
  -H "Authorization: Bearer rp_live_…" \
  -H "X-Workspace-Id: ws_01H…"

Gere uma chave em Configurações → API e webhooks. Toda chamada precisa do cabeçalho X-Workspace-Id.

Formato de erro

Todo erro segue o mesmo formato, com um código estável para tratamento programático:

json

{ "code": "route_not_found", "message": "Route rt_01H… does not exist", "details": { "id": "rt_01H…" } }

Recursos principais

Recurso	Rotas
Lojas	`GET, POST /v1/stores · GET, DELETE /v1/stores/:id`
Snippets	`GET /v1/stores/:id/themes · POST …/snippet/install`
Rotas	`GET, POST /v1/routes · PATCH, DELETE /v1/routes/:id`
Handoffs	`GET /v1/handoffs · GET /v1/handoffs/export.csv`
Uso	`GET /v1/usage · GET /v1/usage/history`
Catálogo	`GET /v1/catalog/parity · POST /v1/catalog/sync`
Analytics	`GET /v1/analytics/overview · /funnel · /destinations`
Eventos	`GET /v1/events/stream (SSE)`

Exemplo: atualizar pesos de uma rota

Os pesos são normalizados pela API; envie os valores relativos que fizerem sentido para você.

json

PUT /v1/routes/rt_01H…/destinations
[
  { "storeId": "st_A", "weight": 70, "priority": 1 },
  { "storeId": "st_B", "weight": 30, "priority": 2 }
]

A API pública está disponível no plano Scale. Veja os detalhes em Preços.