---
title: "Referência do App Manifest | Tajo"
description: "Referência completa do schema do arquivo de manifesto stripe-app.json usado para configurar Stripe Apps"
url: https://tajo.io/pt/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/pt/docs/stripe-apps/app-manifest.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.

# Referência do App Manifest

[Set Noa](https://tajo.io/pt/set-noa/)

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.

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.

## Exemplo completo de manifesto

```json
{
  "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": "Read 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.example.com",
        "https://api.brevo.com"
      ],
      "image-src": [
        "https://cdn.example.com",
        "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.example.com/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:

```json
"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:

```json
"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:

```json
{
  "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](https://tajo.io/pt/docs/stripe-apps/permissions)) |
| `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:

```json
{
  "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:

```json
{
  "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](https://tajo.io/pt/docs/stripe-apps/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:

```json
"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:

```json
{
  "content_security_policy": {
    "connect-src": [
      "https://api.example.com",
      "https://api.brevo.com"
    ],
    "image-src": [
      "https://cdn.example.com"
    ],
    "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:

```json
{
  "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:

```json
// 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](https://tajo.io/pt/docs/stripe-apps/post-install) 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:

```json
{
  "constants": {
    "API_BASE_URL": "https://api.example.com/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:

```typescript
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:

```json
{
  "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:

```bash
# 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](https://tajo.io/pt/docs/stripe-apps/permissions) |
| `Invalid viewport` | Identificador de viewport desconhecido | Consulte a [Referência de viewports](https://tajo.io/pt/docs/stripe-apps/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 |