Solicite acesso antecipado

Informe seu nome e um e-mail ou número de telefone. Entraremos em contato com os detalhes de acesso à Tajo.

Nesta página

Links de instalação e deep links

Os links de instalação permitem distribuir o seu Stripe App fora do marketplace, enquanto os deep links levam os usuários direto a views específicas dentro do app já instalado. Os dois são essenciais para fluxos de integração e de onboarding tranquilos.

Links de instalação

Os links de instalação oferecem uma URL direta que os lojistas podem usar para instalar o seu app. Quando o usuário clica em um link de instalação, a Stripe cuida do fluxo de instalação e depois redireciona de volta para a URI que você indicou.

Pré-requisitos

Antes de usar links de instalação, configure allowed_redirect_uris no manifesto do seu app:

{
  "id": "com.tajo.brevo-integration",
  "allowed_redirect_uris": [
    "https://tajo.io/stripe/callback",
    "https://tajo.io/stripe/oauth/complete"
  ]
}

Formato do link de instalação

https://marketplace.stripe.com/oauth/v2/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&state=STATE_VALUE

Parâmetro	Obrigatório	Descrição
`client_id`	Sim	O ID do seu app (por exemplo, `com.tajo.brevo-integration`)
`redirect_uri`	Sim	Precisa coincidir com uma das suas `allowed_redirect_uris`
`state`	Recomendado	String aleatória para proteção contra CSRF

Parâmetros do redirecionamento

Depois de uma instalação bem-sucedida, a Stripe redireciona o usuário para a sua redirect_uri com estes parâmetros de consulta:

Parâmetro	Descrição
`user_id`	O ID de usuário da Stripe da conta que está instalando
`account_id`	O ID da conta Stripe (por exemplo, `acct_xxxxx`)
`state`	O valor de `state` que você enviou (para verificação de CSRF)
`install_signature`	Assinatura HMAC para verificar se a instalação é legítima

Exemplo de URL de redirecionamento:

https://tajo.io/stripe/callback
  ?user_id=usr_xxxxx
  &account_id=acct_xxxxx
  &state=abc123random
  &install_signature=sig_xxxxx

Proteção contra CSRF

Use sempre o parâmetro state para evitar ataques de falsificação de requisição entre sites:

import crypto from 'crypto';

// Generate a random state value and store it in the session
const generateInstallLink = (req, res) => {
  const state = crypto.randomBytes(32).toString('hex');

  // Store state in session for later verification
  req.session.stripeInstallState = state;

  const installUrl = new URL('https://marketplace.stripe.com/oauth/v2/authorize');
  installUrl.searchParams.set('client_id', 'com.tajo.brevo-integration');
  installUrl.searchParams.set('redirect_uri', 'https://tajo.io/stripe/callback');
  installUrl.searchParams.set('state', state);

  res.redirect(installUrl.toString());
};

// Handle the redirect callback
const handleInstallCallback = async (req, res) => {
  const { state, user_id, account_id, install_signature } = req.query;

  // Verify state matches what we stored
  if (state !== req.session.stripeInstallState) {
    return res.status(403).json({ error: 'Invalid state parameter' });
  }

  // Clear the stored state
  delete req.session.stripeInstallState;

  // Verify the install signature
  if (!verifyInstallSignature(install_signature, account_id)) {
    return res.status(403).json({ error: 'Invalid install signature' });
  }

  // Process the successful installation
  await processInstallation(user_id, account_id);

  res.redirect('/dashboard/stripe-connected');
};

Verificação da assinatura

Verifique a install_signature usando o signing secret do seu app:

import crypto from 'crypto';

const verifyInstallSignature = (signature, accountId) => {
  const signingSecret = process.env.STRIPE_APP_SIGNING_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(accountId)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};

Caution

Use sempre crypto.timingSafeEqual na comparação de assinaturas para evitar ataques de temporização. Nunca use igualdade simples de strings (===).

Signing secret

O signing secret do seu app fica disponível no Stripe Dashboard, nas configurações do app. Use-o para:

Verificar as assinaturas de instalação vindas dos callbacks de redirecionamento
Validar os payloads de webhook enviados pela Stripe
Autenticar as requisições entre o seu backend e a Stripe

Guarde o signing secret com segurança:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Nunca deixe signing secrets fixos no código-fonte nem os envie para o controle de versão.

Deep links

Os deep links levam os usuários direto a uma view específica dentro do Stripe App instalado. Use-os para conduzir os usuários de comunicações externas (e-mails, notificações, páginas de suporte) até o contexto certo do app.

Formato da URL de deep link

https://dashboard.stripe.com/MODE/acct_ID/PAGE?apps[APP_ID][TARGET]=VIEWPORT_ID

Componente	Descrição	Exemplo
`MODE`	`live` ou `test`	`live`
`acct_ID`	ID da conta Stripe de destino	`acct_1234567890`
`PAGE`	Caminho da página do Dashboard	`customers/cus_xxxxx`
`APP_ID`	O ID do seu app	`com.tajo.brevo-integration`
`TARGET`	`drawer` ou `modal`	`drawer`
`VIEWPORT_ID`	O viewport que será aberto	`stripe.dashboard.customer.detail`

Alvo	Comportamento	Caso de uso
`drawer`	Abre o app no painel lateral (drawer)	Interação padrão com o app, contexto ao lado da página
`modal`	Abre o app em uma sobreposição modal de tela cheia	Fluxos que exigem foco, onboarding, formulários complexos

Exemplos de deep link

Abrir a view de detalhe do cliente no drawer

https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail

https://dashboard.stripe.com/live/acct_xxxxx/settings
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.settings

Abrir o fluxo de onboarding

https://dashboard.stripe.com/live/acct_xxxxx/dashboard
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.onboarding

Abrir a view de detalhe do pagamento em modo de teste

https://dashboard.stripe.com/test/acct_xxxxx/payments/pi_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.payment.detail

Gerar deep links de forma programática

const generateDeepLink = ({
  accountId,
  mode = 'live',
  page,
  appId = 'com.tajo.brevo-integration',
  target = 'drawer',
  viewport,
}) => {
  const baseUrl = `https://dashboard.stripe.com/${mode}/${accountId}/${page}`;
  const params = new URLSearchParams();
  params.set(`apps[${appId}][${target}]`, viewport);

  return `${baseUrl}?${params.toString()}`;
};

// Generate a link to view a customer's Brevo profile
const customerLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'customers/cus_xxxxx',
  viewport: 'stripe.dashboard.customer.detail',
});

// Generate a link to app settings
const settingsLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'settings',
  viewport: 'stripe.dashboard.settings',
  target: 'modal',
});

Usar deep links nas suas comunicações

Os deep links são especialmente úteis em:

Notificações por e-mail: “Veja o status de sincronização com a Brevo deste cliente”
Respostas de suporte: “Clique aqui para conferir as configurações da sua integração”
E-mails de onboarding: “Conclua a configuração da Brevo”
Alertas de erro: “Revise o problema de sincronização do cliente X”

<!-- Example in an email template -->
<a href="https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail">
  View Brevo Profile in Stripe
</a>

Combinar links de instalação e deep links

Para a melhor experiência de onboarding, combine os links de instalação com deep links pós-instalação:

O usuário clica em um link de instalação no seu site ou em um e-mail
O usuário instala o app e é redirecionado para a sua URL de callback
O seu callback processa a instalação e redireciona o usuário para um deep link que abre o viewport de onboarding

const handleInstallCallback = async (req, res) => {
  const { account_id, install_signature, state } = req.query;

  // Verify state and signature
  // ... (verification code)

  // Process installation
  await processInstallation(account_id);

  // Redirect to the app's onboarding view via deep link
  const onboardingLink = generateDeepLink({
    accountId: account_id,
    page: 'dashboard',
    viewport: 'stripe.dashboard.onboarding',
    target: 'modal',
  });

  res.redirect(onboardingLink);
};

Tip

Teste sempre os links de instalação e os deep links em modo live e em modo de teste, para garantir que funcionem corretamente em todos os ambientes.