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

Referência do App Manifest

O arquivo de manifesto stripe-app.json é a configuração central do seu Stripe App. Ele declara a identidade do app, as permissões, as views da interface, as políticas de segurança e o comportamento após a instalação.

Exemplo completo de manifesto

{
  "id": "com.tajo.brevo-integration",
  "version": "1.2.0",
  "name": "Tajo for Brevo",
  "icon": "./assets/icon.png",
  "distribution_type": "public",
  "sandbox_install_compatible": true,
  "stripe_api_access_type": "oauth",
  "allowed_redirect_uris": [
    "https://tajo.io/stripe/callback",
    "https://tajo.io/stripe/oauth/complete"
  ],
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Read customer profiles to sync with Brevo contacts"
    },
    {
      "permission": "customer_write",
      "purpose": "Update customer metadata with Brevo sync status"
    },
    {
      "permission": "charge_read",
      "purpose": "Access payment history for Brevo event tracking"
    },
    {
      "permission": "product_read",
      "purpose": "Sync product catalog to Brevo for personalized campaigns"
    },
    {
      "permission": "event_read",
      "purpose": "Subscribe to real-time events for Brevo automation triggers"
    },
    {
      "permission": "invoice_read",
      "purpose": "Track invoice lifecycle events in Brevo"
    }
  ],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.customer.detail",
        "component": "CustomerDetailView"
      },
      {
        "viewport": "stripe.dashboard.customer.list",
        "component": "CustomerListView"
      },
      {
        "viewport": "stripe.dashboard.home.overview",
        "component": "OverviewView"
      },
      {
        "viewport": "stripe.dashboard.drawer.default",
        "component": "DrawerView"
      },
      {
        "viewport": "stripe.dashboard.settings",
        "component": "SettingsView"
      },
      {
        "viewport": "stripe.dashboard.onboarding",
        "component": "OnboardingView"
      }
    ],
    "content_security_policy": {
      "connect-src": [
        "https://api.tajo.io",
        "https://api.brevo.com"
      ],
      "image-src": [
        "https://cdn.tajo.io",
        "https://assets.brevo.com"
      ],
      "purpose": "Connect to Tajo API for data sync and Brevo API for contact management"
    }
  },
  "post_install_action": {
    "type": "onboarding"
  },
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300"
  }
}

Referência do schema

Campos de nível superior

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador único do app em notação de domínio invertido (formato slug)
`version`	string	Sim	String de versão semântica (por exemplo, `"1.2.0"`)
`name`	string	Sim	Nome de exibição mostrado no marketplace (máximo de 35 caracteres)
`icon`	string	Sim	Caminho relativo do arquivo de ícone do app (PNG ou SVG de 300x300)
`distribution_type`	string	Sim	`"public"` para o marketplace ou `"private"` para uso interno
`sandbox_install_compatible`	boolean	Não	Define se o app pode ser instalado em modo sandbox/teste
`stripe_api_access_type`	string	Não	Método de acesso à API: `"oauth"` ou `"api_key"`
`allowed_redirect_uris`	string[]	Não	URIs de redirecionamento OAuth permitidas no fluxo de instalação
`permissions`	PermissionRequest[]	Sim	Array com as solicitações de permissão
`ui_extension`	UIExtensionManifest	Não	Configuração da extensão de interface
`post_install_action`	PostInstallAction	Não	Ação executada após a instalação do app
`constants`	object	Não	Pares de chave e valor acessíveis no app em tempo de execução

id

O identificador do app é uma string em formato slug, normalmente em notação de domínio invertido:

"id": "com.tajo.brevo-integration"

Precisa ser único globalmente entre todos os Stripe Apps
Use apenas letras minúsculas, números, hifens e pontos
Não pode ser alterado depois que o app é criado
Define a URL do app no marketplace

version

Segue o versionamento semântico:

"version": "1.2.0"

MAJOR: mudanças incompatíveis ou adição de recursos importantes
MINOR: novos recursos, com compatibilidade retroativa
PATCH: correções de bugs e melhorias pequenas
Precisa ser incrementado a cada upload

distribution_type

Controla quem pode instalar o seu app:

Valor	Descrição
`"public"`	Disponível no Stripe App Marketplace para todos os usuários
`"private"`	Só pode ser instalado pela sua própria conta Stripe

stripe_api_access_type

Determina como o seu app se autentica na API da Stripe:

Valor	Descrição
`"oauth"`	Usa o fluxo OAuth 2.0 para autenticação (recomendado para apps públicos)
`"api_key"`	Usa chaves de API restritas (indicado para apps privados)

PermissionRequest

Cada solicitação de permissão declara uma permissão específica da API da Stripe que o seu app precisa:

{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}

Campo	Tipo	Obrigatório	Descrição
`permission`	string	Sim	O identificador da permissão (veja a Referência de permissões)
`purpose`	string	Sim	Explicação legível de por que essa permissão é necessária

Diretrizes para o purpose:

Escreva explicações claras e específicas que os lojistas consigam entender
Explique para que a permissão é usada, não apenas o que ela concede
Mantenha as descrições curtas (uma frase)
Evite jargão técnico

UIExtensionManifest

Configura os componentes de interface do seu app:

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}

Campo	Tipo	Obrigatório	Descrição
`views`	ViewManifest[]	Sim	Array com as declarações de view
`content_security_policy`	CSPRequest	Não	Content Security Policy para recursos externos

ViewManifest

Cada view associa um componente React a um viewport do Stripe Dashboard:

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}

Campo	Tipo	Obrigatório	Descrição
`viewport`	string	Sim	O local do Dashboard onde essa view é renderizada (veja a Referência de viewports)
`component`	string	Sim	Nome do componente React a ser renderizado (precisa coincidir com o nome do componente exportado)

Um único app pode declarar várias views para viewports diferentes:

"views": [
  {
    "viewport": "stripe.dashboard.customer.detail",
    "component": "CustomerDetailView"
  },
  {
    "viewport": "stripe.dashboard.payment.detail",
    "component": "PaymentDetailView"
  },
  {
    "viewport": "stripe.dashboard.home.overview",
    "component": "OverviewView"
  }
]

CSPRequest

A Content Security Policy controla a quais domínios externos o seu app pode se conectar:

{
  "content_security_policy": {
    "connect-src": [
      "https://api.tajo.io",
      "https://api.brevo.com"
    ],
    "image-src": [
      "https://cdn.tajo.io"
    ],
    "purpose": "Connect to Tajo API for data sync and load images from CDN"
  }
}

Campo	Tipo	Obrigatório	Descrição
`connect-src`	string[]	Não	Domínios para os quais o app pode fazer requisições de rede
`image-src`	string[]	Não	Domínios de onde o app pode carregar imagens
`purpose`	string	Sim	Explicação de por que essas conexões externas são necessárias

Caution

Inclua apenas os domínios aos quais o seu app realmente precisa se conectar. Entradas demais na CSP podem gerar uma análise mais rigorosa.

PostInstallAction

Configura o que acontece logo depois que um usuário instala o seu app:

{
  "post_install_action": {
    "type": "onboarding"
  }
}

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	O tipo de ação (veja abaixo)
`url`	string	Condicional	URL para ações do tipo `external`

Tipos de ação

Tipo	Comportamento
`"onboarding"`	Abre a view de onboarding do app no Dashboard
`"settings"`	Abre a view de configurações do app no Dashboard
`"external"`	Redireciona o usuário para uma URL externa (exige o campo `url`)

Exemplos:

// Open onboarding flow
{
  "post_install_action": {
    "type": "onboarding"
  }
}

// Open settings page
{
  "post_install_action": {
    "type": "settings"
  }
}

// Redirect to external setup
{
  "post_install_action": {
    "type": "external",
    "url": "https://app.tajo.io/stripe/setup"
  }
}

Veja o guia de ações pós-instalação para conhecer os padrões de implementação em detalhe.

Constants

Defina pares estáticos de chave e valor acessíveis em tempo de execução no seu app:

{
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}

Todos os valores precisam ser strings
As constantes são embutidas no app no momento do build
Use constantes para configurações que mudam entre ambientes
Nunca guarde segredos ou chaves de API como constantes, use a Secret Store API no lugar

Acesse as constantes no código do seu app:

import { constants } from '@stripe/ui-extension-sdk/constants';

const apiUrl = constants.API_BASE_URL;

Manifesto estendido para desenvolvimento

Durante o desenvolvimento local, há campos adicionais disponíveis:

{
  "id": "com.tajo.brevo-integration",
  "version": "0.1.0",
  "name": "Tajo for Brevo (Dev)",
  "icon": "./assets/icon-dev.png",
  "distribution_type": "private",
  "sandbox_install_compatible": true,
  "dev": {
    "hot_reload": true,
    "port": 4242
  }
}

A seção dev é removida nos builds de produção e nos uploads do app. Use-a apenas para configurações que facilitam o desenvolvimento local.

Validação

Valide o seu manifesto antes de fazer o upload:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Erros de validação comuns:

Erro	Causa	Correção
`Invalid permission`	Identificador de permissão desconhecido	Consulte a Referência de permissões
`Invalid viewport`	Identificador de viewport desconhecido	Consulte a Referência de viewports
`Missing purpose`	Permissão sem o campo purpose	Adicione uma string de purpose a cada permissão
`Invalid version`	String de versão fora do padrão semver	Use o formato `MAJOR.MINOR.PATCH`
`Icon not found`	O caminho do ícone não é resolvido	Confirme se o arquivo de ícone existe no caminho indicado