--- title: "Links de instalação e deep links | Tajo" description: "Gere URLs de instalação para distribuir o app e deep links para levar os usuários a views específicas do app" url: https://tajo.io/pt/docs/stripe-apps/install-links/ markdown: https://tajo.io/pt/docs/stripe-apps/install-links.md lang: pt-BR author: "Set Noa" author_url: https://tajo.io/pt/set-noa/ robots: noindex --- Solicite acesso antecipado Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo. # Links de instalação e deep links [Set Noa](https://tajo.io/pt/set-noa/) 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. Caution **Status: planejado, não construído.** A Tajo não tem um Stripe App, então nada nesta seção pode ser instalado hoje. Os identificadores de app, URLs e credenciais desta página são exemplos ilustrativos, não endpoints reais. ## 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: ```json { "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: ```javascript 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: ```javascript 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: ```bash # 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` | ### Alvos drawer e modal | 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 ``` #### Abrir as configurações em modal ``` 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 ```javascript 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” ```html View Brevo Profile in Stripe ``` ## 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: 1. O usuário clica em um **link de instalação** no seu site ou em um e-mail 2. O usuário instala o app e é redirecionado para a sua URL de callback 3. O seu callback processa a instalação e redireciona o usuário para um **deep link** que abre o viewport de onboarding ```javascript 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.