> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/configuracao-administrador/configuracao/aplicativos.md).

# Aplicativos

{% hint style="warning" %}
**Disponível para o perfil: Administrador**
{% endhint %}

Os **Aplicativos** colocam no menu do Z-PRO os sistemas que a sua equipe usa no dia a dia: CRM, financeiro, relatórios, reservas, planilhas. Cada aplicativo é um endereço de site com nome e ícone, que abre dentro do painel ou numa nova aba, sem a equipe precisar sair do atendimento para procurar o link.

O aplicativo também pode abrir **direto do contato e do atendimento**, levando no endereço os dados do cliente (por exemplo, o telefone), para a ferramenta já abrir na ficha certa.

{% hint style="info" %}
**Pré-requisitos:**

* Z-PRO na versão **4.0.7** ou superior.
* O endereço (URL) de cada sistema que você quer colocar no menu.
* Para abrir **Dentro do painel**, o endereço precisa ser **https**.
  {% endhint %}

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2Fo7cAuaVELrwbt45YI8hy%2Fimage.png?alt=media&amp;token=32ad5c5e-f4f3-4e7f-b5f0-5cbfb69ba035" alt=""><figcaption></figcaption></figure>

***

### Como funciona

* Cada aplicativo é um **endereço de site com nome e ícone**, que aparece no menu lateral na categoria que você escolher.
* **Dentro do painel** abre o site no meio da tela, com o menu do Z-PRO ao lado. **Nova aba** abre o site em outra aba do navegador.
* Você define **quem vê** cada aplicativo: por perfil, perfil personalizado, usuário ou equipe.
* A empresa pode cadastrar até **50 aplicativos**. A ordem da lista é a ordem em que eles aparecem no menu.
* As mudanças chegam ao menu dos usuários **em alguns segundos**, sem precisar recarregar o sistema.

***

### Como acessar

No menu lateral, clique em **Configuração** e selecione **Aplicativos**.

A tela mostra o bloco **Aplicativos da empresa**, com o contador de cadastros (ex.: **0 de 50**) e o botão **Novo aplicativo** no canto superior direito. Enquanto não houver nenhum cadastrado, a tela mostra o resumo em três passos: cadastrar nome e endereço, escolher onde aparece e quem vê, testar e salvar.

***

### Como cadastrar um aplicativo

1. Clique em **Novo aplicativo**.
2. Preencha os campos abaixo e defina **Onde aparece**, **Como abre** e **Quem vê** (seções a seguir).
3. Clique em **Testar** para conferir se o site abre dentro do painel. O resultado aparece abaixo do endereço, em **Última conferência** (ex.: "Este site aceita ser aberto dentro do painel").
4. Clique em **Salvar**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FRxlakq8UKOisxL8TlTdz%2Fimage.png?alt=media&amp;token=0019a116-8150-407c-89cb-04bc32b5f8b6" alt="" width="375"><figcaption></figcaption></figure>

| Campo        | Descrição                                                                                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome**     | Nome que aparece no menu. Até 60 caracteres. Ex.: Reservas de Mesas                                                                                               |
| **Endereço** | Endereço do site, começando com `https://`. O botão **Inserir variável** acrescenta dados do contato, do atendimento ou de quem abre (veja Variáveis no endereço) |
| **Testar**   | Confere se o site aceita ser aberto dentro do painel                                                                                                              |
| **Ícone**    | Ícone exibido ao lado do nome no menu e no **Abrir em…**                                                                                                          |
| **Ativo**    | Desligado, o aplicativo some do menu de todos, sem perder o cadastro                                                                                              |

{% hint style="danger" %}
**Não coloque senha ou chave no endereço.** Quem vê o aplicativo vê o endereço completo.
{% endhint %}

***

### Onde aparece

Marque um ou mais lugares:

| Opção            | Onde o aplicativo aparece                                         |
| ---------------- | ----------------------------------------------------------------- |
| **Menu lateral** | No menu, na categoria escolhida em **Onde aparece no menu**       |
| **Contato**      | Na ação **Abrir em…** da lista de contatos e do perfil do contato |
| **Atendimento**  | Na ação **Abrir em…** do menu de opções do atendimento aberto     |

Com **Menu lateral** marcado, escolha a categoria em **Onde aparece no menu**: Ferramentas, Atendimento, Comunicação e Marketing, Gestão, Administração, Automação, Gestão Comercial ou Configuração. A categoria **Ferramentas** só aparece no menu quando tem pelo menos um aplicativo.

{% hint style="info" %}
Quem não tem acesso à categoria escolhida vê o aplicativo em **Ferramentas**.
{% endhint %}

***

### Como abre

| Opção                | Comportamento                                                      |
| -------------------- | ------------------------------------------------------------------ |
| **Dentro do painel** | Abre no meio da tela, com o menu ao lado. Exige endereço **https** |
| **Nova aba**         | Abre o site em outra aba do navegador. Aceita **http** e **https** |

Prefira **Nova aba** quando:

* o **Testar** mostrar que o site recusa ser aberto dentro de outro site;
* o sistema **pede login**: sistemas com login costumam não manter a sessão dentro do painel, em qualquer navegador;
* a ferramenta usa **câmera, microfone ou localização**, que não funcionam dentro do painel.

***

### Quem vê

Basta **uma** das regras abaixo para a pessoa ver o aplicativo.

| Regra                     | Como funciona                                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Perfis**                | Marque **Supervisor**, **Atendente** e/ou **Todos os perfis personalizados**. O **Administrador** sempre vê todos os aplicativos da empresa |
| **Perfis personalizados** | Clique em **Adicionar** e escolha perfis personalizados específicos                                                                         |
| **Usuários**              | Clique em **Adicionar** e escolha usuários específicos                                                                                      |
| **Equipes**               | Clique em **Adicionar** e escolha equipes                                                                                                   |

Exemplo: para liberar o sistema financeiro só para os supervisores e para a pessoa do financeiro, marque **Supervisor** em Perfis e adicione essa pessoa em **Usuários**.

***

### Lista de aplicativos

Depois de salvo, o aplicativo entra na lista **Aplicativos da empresa**, e o contador do canto mostra quantos já foram cadastrados (ex.: **1 de 50**).

| Coluna         | O que mostra                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Aplicativo** | Ícone, nome e domínio do endereço. Abaixo, as marcas de onde ele aparece: **Menu**, **Contato** e **Atendimento** |
| **Categoria**  | Categoria do menu escolhida em **Onde aparece no menu**                                                           |
| **Abre**       | **Dentro do painel** ou **Nova aba**                                                                              |
| **Quem vê**    | Perfis, usuários e equipes liberados. Sem nenhuma regra marcada, mostra só **Administrador**                      |
| **Situação**   | **Ativo** ou desativado                                                                                           |
| **Ações**      | Setas para mudar a ordem, lápis para editar e lixeira para excluir                                                |

#### Mudar a ordem no menu

Use as **setas** (para cima e para baixo) em **Ações**. A ordem da lista é a ordem em que os aplicativos aparecem no menu.

#### Editar ou excluir

* **Lápis:** abre o mesmo formulário do cadastro, para mudar qualquer campo.
* **Lixeira:** exclui o aplicativo. Para só tirar do menu e manter o cadastro, edite e desligue **Ativo**.

***

### Abrir pelo contato e pelo atendimento

Com **Contato** e/ou **Atendimento** marcados em **Onde aparece**, a equipe abre a ferramenta já com os dados daquele cliente:

* **No atendimento:** no menu de opções (**⋯**) do atendimento aberto, clique em **Abrir em…** e escolha o aplicativo.
* **Na lista de contatos:** na coluna **Ações**, clique no ícone de **Abrir em…** e escolha o aplicativo. O mesmo vale para o perfil do contato.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2F448q3zwBsXqZDQxvJCo8%2Fimage.png?alt=media&amp;token=35c5d42b-b0d0-45ab-938a-2a7a09a0c098" alt="" width="375"><figcaption></figcaption></figure>

Com **Dentro do painel**, o aplicativo abre num painel à direita, com o caminho de origem no topo (ex.: **Contato › Teste**) e os botões **Recarregar**, **Abrir em nova aba** e fechar. A lista de contatos ou o atendimento continuam visíveis ao lado.

***

### Variáveis no endereço

As variáveis levam no endereço os dados do contato, do atendimento ou de quem abre o aplicativo. Ao abrir, cada variável é trocada pelo dado de verdade.

1. No campo **Endereço**, deixe o cursor onde a variável deve entrar.
2. Clique em **Inserir variável**. Abre a lista de variáveis, agrupadas por tipo.
3. Clique na variável. Ela entra no endereço, no ponto do cursor.
4. Clique em **Concluir** para fechar a lista.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FxmDX40hrbj66TJ6v1Xn4%2Fimage.png?alt=media&amp;token=0523f043-b4a3-44b9-b316-1740679377be" alt="" width="375"><figcaption></figcaption></figure>

#### Variáveis do contato

Preenchidas ao abrir pelo **contato** ou pelo **atendimento**. Abrindo pelo menu, ficam vazias.

| Variável           | Dado                     | Onde pode ir no endereço     |
| ------------------ | ------------------------ | ---------------------------- |
| `{{contactId}}`    | ID do contato            | No caminho ou nos parâmetros |
| `{{phoneNumber}}`  | Telefone do contato      | No caminho ou nos parâmetros |
| `{{name}}`         | Nome do contato          | Só depois do `?` ou do `#`   |
| `{{firstName}}`    | Primeiro nome do contato | Só depois do `?` ou do `#`   |
| `{{lastName}}`     | Sobrenome do contato     | Só depois do `?` ou do `#`   |
| `{{email}}`        | E-mail do contato        | Só depois do `?` ou do `#`   |
| `{{businessName}}` | Empresa do contato       | Só depois do `?` ou do `#`   |

#### Variáveis do atendimento

Preenchidas **só ao abrir pelo atendimento**.

| Variável       | Dado                     | Onde pode ir no endereço     |
| -------------- | ------------------------ | ---------------------------- |
| `{{ticketId}}` | ID do atendimento        | No caminho ou nos parâmetros |
| `{{protocol}}` | Protocolo do atendimento | No caminho ou nos parâmetros |

#### Variáveis de quem abre e da empresa

Preenchidas sempre, inclusive pelo menu. **Quem abre** é o usuário do painel que clicou para abrir; **empresa** é a empresa dele.

| Variável               | Dado                | Onde pode ir no endereço     |
| ---------------------- | ------------------- | ---------------------------- |
| `{{currentUserId}}`    | ID de quem abre     | No caminho ou nos parâmetros |
| `{{currentUserName}}`  | Nome de quem abre   | Só depois do `?` ou do `#`   |
| `{{currentUserEmail}}` | E-mail de quem abre | Só depois do `?` ou do `#`   |
| `{{tenantId}}`         | ID da empresa       | No caminho ou nos parâmetros |

Exemplos:

```
https://sistema.suaempresa.com.br/clientes/{{phoneNumber}}
https://sistema.suaempresa.com.br/clientes?telefone={{phoneNumber}}&nome={{name}}
https://sistema.suaempresa.com.br/chamados/{{ticketId}}?atendente={{currentUserName}}
```

{% hint style="warning" %}
**Nomes e e-mails só podem ir depois do `?` ou do `#`** do endereço. No caminho (antes do `?`), use só os IDs, o telefone e o protocolo.
{% endhint %}

#### Cuidados com os dados no endereço

* **Não coloque senha ou chave no endereço:** quem vê o aplicativo vê o endereço.
* O endereço com os dados pode ficar gravado no **registro de acesso da ferramenta**. O que vem **depois do `#`** não chega ao servidor dela.
* Para **usuário restrito** e com o **modo apresentação** ligado, o endereço leva **só os números de identificação**: nome, telefone, e-mail e empresa do contato vão vazios.
* Com variáveis, o **Testar** e a conferência ao salvar usam **valores de exemplo**, nunca dados de clientes.
* Cada abertura pelo contato ou pelo atendimento fica registrada no Log de Auditoria.

***

### Ficha assinada

A **ficha assinada** (`{{token}}`) deixa a sua ferramenta reconhecer quem abriu o aplicativo **sem pedir senha**. Ela leva quem abriu, a empresa e, conforme o lugar de onde abriu, o contato e o atendimento, com uma assinatura que a ferramenta confere com a **chave pública** do aplicativo.

{% hint style="info" %}
A ficha só funciona se a ferramenta de destino for preparada para conferir a assinatura. Use quando você (ou o fornecedor da ferramenta) consegue mexer no código dela.
{% endhint %}

#### Como ativar

1. No **Endereço** (precisa ser **https**), clique em **Inserir variável** e escolha **Ficha assinada**, no grupo **Identificação**. Prefira colocar depois do `#`, por exemplo: `https://sistema.suaempresa.com.br/#t={{token}}`
2. Clique em **Salvar**. A chave é criada ao salvar.
3. Abra o cadastro de novo (lápis) e role até **Chave da ficha assinada**.
4. Copie a **chave pública** e passe para quem cuida da ferramenta, junto com as instruções de **Como a ferramenta confere a ficha**, que aparecem logo abaixo da chave.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FfhyGASYjhjaxoRvOgXzB%2Fimage.png?alt=media&amp;token=70d1ff88-50f8-4413-9f03-43b45016fed4" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="warning" %}
**Trocar o domínio do endereço gera uma chave nova.** A ferramenta precisa receber a chave nova, senão deixa de reconhecer as fichas.
{% endhint %}

#### Como a ferramenta confere a ficha

Esta parte é para quem cuida da ferramenta de destino. O cadastro do aplicativo traz as mesmas instruções e exemplos prontos em **Node.js** e **PHP**, já com o endereço da ferramenta e o do seu painel. Copie de lá.

A ficha chega no endereço, no lugar de `{{token}}`, e tem duas partes separadas por um ponto: os dados e a assinatura.

1. Confira a assinatura (**Ed25519**) da 1ª parte, exatamente como chegou, com a chave pública. Se não conferir, recuse a ficha.
2. Abra a 1ª parte (base64url com um texto JSON) e confira os campos:

| Campo | Regra                                                                                            |
| ----- | ------------------------------------------------------------------------------------------------ |
| `typ` | Precisa ser `app-launch`                                                                         |
| `aud` | Precisa ser o endereço da sua ferramenta (ex.: `https://sistema.suaempresa.com.br`)              |
| `iss` | Precisa ser um endereço do seu painel Z-PRO. Acrescente os outros endereços do painel, se houver |
| `exp` | Horário em que a ficha vence, em segundos. Aceite até 60 segundos de diferença de relógio        |
| `iat` | Recuse se estiver mais de 60 segundos no futuro                                                  |
| `jti` | Opcional: recuse uma ficha que já foi usada                                                      |

O que a ficha traz:

| Campo       | Conteúdo                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `user`      | Quem abriu: id, nome, e-mail, perfil e se é usuário restrito                                                       |
| `tenant`    | A empresa: id e nome                                                                                               |
| `contact`   | O contato, ao abrir pelo contato ou pelo atendimento: id e, sem a marca `masked`, nome, telefone, e-mail e empresa |
| `ticket`    | O atendimento, ao abrir pelo atendimento: id e protocolo                                                           |
| `placement` | De onde abriu: `menu`, `contact` ou `ticket`                                                                       |
| `masked`    | Verdadeiro quando o usuário é restrito ou o painel está no modo apresentação: seguem só os ids                     |

{% hint style="danger" %}
**Para reconhecer a pessoa, use o `user.id` junto com o `tenant.id` e o `iss`.** O nome e o e-mail servem só para mostrar, porque quem administra o painel pode trocá-los.
{% endhint %}

#### Manter a sessão dentro do painel

* Prefira receber a ficha **depois do `#`** (ex.: `#t={{token}}`) e ler pelo navegador: essa parte não vai ao servidor da ferramenta nem ao registro de acesso dela.
* Depois de conferir, guarde a sessão de um jeito que funcione dentro do painel: em `sessionStorage`, no próprio endereço ou num cookie com `SameSite=None; Secure; Partitioned`. Cookie comum costuma não funcionar dentro de outro site.
* Tire a ficha do endereço depois de ler (por exemplo, com `history.replaceState`), para ela não ficar no histórico do navegador.
* Com `masked` verdadeiro, os dados do contato não vêm: não use campo vazio como filtro de busca, senão a ferramenta mostraria a lista inteira.

***

### Aplicativos do provedor

O provedor do sistema pode disponibilizar aplicativos para a sua empresa (veja Aplicativos globais). No menu, os aplicativos da sua empresa aparecem primeiro e os do provedor logo depois, na mesma categoria.

Quando o provedor libera algum para a sua empresa, a tela **Aplicativos** mostra o bloco **Aplicativos do provedor**, abaixo da lista da empresa. Cada um aparece com o nome, a categoria do menu e como abre (ex.: Ferramentas · Nova aba).

* Para tirar um aplicativo do provedor do menu, ligue **Ocultar nesta empresa**. Oculto, ele some do menu de todos os usuários da empresa. Para mostrar de novo, desligue.
* Você não edita nem exclui aplicativos do provedor: só oculta.
* Aplicativos do provedor abrem **só pelo menu**, não pelo contato nem pelo atendimento.

***

### Resumo

| Quero…                                    | Onde                                                                   |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| Cadastrar um sistema no menu              | **Configuração → Aplicativos → Novo aplicativo**                       |
| Escolher a categoria do menu              | **Onde aparece no menu**                                               |
| Abrir pelo contato ou atendimento         | **Onde aparece → Contato / Atendimento**                               |
| Mandar dados do cliente para a ferramenta | **Endereço → Inserir variável**                                        |
| Liberar para perfis, usuários ou equipes  | **Quem vê**                                                            |
| Tirar do menu sem apagar                  | Desligar **Ativo**                                                     |
| Mudar a ordem no menu                     | Setas em **Ações**                                                     |
| Editar ou excluir                         | Lápis ou lixeira em **Ações**                                          |
| Identificar quem abriu sem senha          | **Inserir variável → Ficha assinada**, salvar e copiar a chave pública |
| Esconder aplicativo do provedor           | **Aplicativos do provedor → Ocultar nesta empresa**                    |

***

### Possíveis erros e soluções

#### O site não abre dentro do painel (tela em branco ou recusada)

**Causa:** alguns sites proíbem ser abertos dentro de outro site. **Solução:** clique em **Testar** no cadastro. Se aparecer o aviso "Este site não aceita ser aberto dentro de outro site. Escolha 'Nova aba' para ele.", mude **Como abre** para **Nova aba**.

#### O sistema pede login toda vez ou não mantém a sessão

**Causa:** sistemas com login costumam não manter a sessão dentro do painel, em qualquer navegador. **Solução:** use **Nova aba**.

#### Câmera, microfone ou localização não funcionam

**Causa:** esses recursos não funcionam dentro do painel. **Solução:** use **Nova aba**.

#### Um usuário não vê o aplicativo no menu

**Causa:** nenhuma regra de **Quem vê** inclui essa pessoa (na lista, a coluna **Quem vê** mostra só **Administrador**), o aplicativo está com **Ativo** desligado, ou só **Contato/Atendimento** está marcado em **Onde aparece**. **Solução:** confira as regras de **Quem vê**, o **Ativo** e se **Menu lateral** está marcado. Se a pessoa não tiver acesso à categoria escolhida, procure em **Ferramentas**.

#### O aplicativo não aparece no Abrir em…

**Causa:** **Contato** ou **Atendimento** não está marcado em **Onde aparece**, ou a pessoa não está em nenhuma regra de **Quem vê**. **Solução:** edite o aplicativo e marque o lugar certo em **Onde aparece**.

#### As variáveis do contato ou do atendimento chegam vazias

**Causa:** as variáveis do contato só são preenchidas ao abrir pelo contato ou pelo atendimento, e as do atendimento só pelo atendimento. Pelo menu lateral, as duas ficam vazias. **Solução:** abra pelo **Abrir em…** do lugar certo.

#### A ferramenta parou de reconhecer a ficha assinada

**Causa:** o domínio do endereço foi trocado, o que gera uma chave pública nova. Ou a ficha passou dos 5 minutos, ou o relógio do servidor da ferramenta está adiantado ou atrasado mais de 60 segundos. **Solução:** abra o cadastro, copie a chave pública atual e atualize na ferramenta. Confira o relógio do servidor dela.

#### Não aparece a Chave da ficha assinada no cadastro

**Causa:** a chave só é criada depois de salvar com `{{token}}` num endereço https. **Solução:** salve o aplicativo e abra o cadastro de novo pelo lápis.

#### O endereço abre sem o nome, telefone ou e-mail do contato

**Causa:** quem abriu é usuário restrito ou está com o modo apresentação ligado, e nesses casos seguem só os códigos internos. Ou a variável de nome, e-mail ou empresa foi colocada antes do `?` ou do `#`. **Solução:** confira o perfil de quem abriu e mova essas variáveis para depois do `?` ou do `#`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ajuda.zdg.com.br/configuracao-administrador/configuracao/aplicativos.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
