> 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-superadmin/tenants-e-licenca/ia-da-plataforma.md).

# IA da plataforma

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

A tela **IA da plataforma** permite que você, dono da instalação, ofereça IA às empresas (tenants) da sua base sem que cada uma precise ter a própria chave de um provedor. Você conecta um serviço de IA com a **sua chave**, escolhe quais modelos vender e com qual margem, e cada empresa consome de um **saldo pré-pago** que ela mesma recarrega.

Neste artigo você vai configurar as cinco abas da tela, **Conexão**, **Modelos**, **Preços**, **Margens** e **Venda**, e depois liberar o recurso para as empresas. Para saber como a empresa acompanha o saldo e recarrega, veja Como usar os Créditos de IA.

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

* Acesso de **Superadministrador** na instalação do Z-PRO.
* Uma conta com saldo em um serviço de IA **compatível com a API da OpenAI** (ex: OpenRouter, OpenAI ou um servidor próprio no mesmo padrão) e a **chave de acesso** desse serviço.
* Um meio de pagamento configurado em **Planos** (Asaas ou Stripe; Mercado Pago e Pagar.me exigem um meio de pagamento reserva), para as empresas conseguirem recarregar o saldo. Veja Planos.
* O **plano** de cada empresa que vai usar o recurso precisa incluir os Créditos de IA.
  {% endhint %}

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FLhnqQY4eWkyLnPGmho4h%2Fimage.png?alt=media&amp;token=565fb5bd-b9c6-4800-aef5-77c233d4822a" alt=""><figcaption></figcaption></figure>

***

### Como funciona

1. Você conecta o serviço de IA na aba **Conexão**. Todo o consumo das empresas é feito com a sua chave e cobrado na sua conta do serviço.
2. O custo de cada resposta vem do serviço em dólar e inclui tudo o que a resposta usou: entrada (mensagem, histórico, instruções e imagens), saída e o raciocínio dos modelos que "pensam". O Z-PRO converte para reais pela **cotação fixa** que você definir e aplica a **margem** sobre esse custo total:

   `custo em US$ × cotação × (1 + margem)`, arredondado para cima.

   Áudio segue a mesma lógica: a **transcrição** é cobrada por minuto e a **voz** pela quantidade de caracteres.
3. A empresa vê só o **preço final** e paga com o saldo que recarregou. Ela nunca vê o seu custo nem a sua margem. A margem entra **em cada uso**, não na recarga: quem paga R$ 100 recebe R$ 100 de saldo.
4. A empresa escolhe, em cada recurso de IA, se usa a **chave própria** ou a **IA da plataforma** (agente de IA, robô ChatGPT da conexão, bloco ChatGPT do fluxo e Copiloto). Só o que estiver na IA da plataforma desconta do saldo.
5. Quando o saldo acaba, a IA **termina a resposta em andamento** e o atendimento vai para a fila. O saldo só fica negativo até o **limite de saldo negativo**. A IA nunca passa a usar a chave própria da empresa no lugar.

{% hint style="warning" %}
**Atenção:** o custo no serviço de IA é seu. Mantenha saldo na conta do serviço; se ela ficar sem crédito, a IA para para todas as empresas, mesmo que elas tenham saldo no Z-PRO.
{% endhint %}

***

### Etapa 1: Conectar o serviço de IA (aba Conexão)

1. No painel Superadmin, acesse **Tenants e Licenciamento > Financeiro > IA da plataforma** e fique na aba **Conexão**.
2. Preencha os campos:

| Campo                             | O que informar                                                                                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Endereço do serviço**           | URL da API do serviço, no padrão OpenAI. Ex: `https://openrouter.ai/api/v1`.                                                                           |
| **Chave de acesso**               | A chave gerada no painel do serviço de IA.                                                                                                             |
| **Cotação do dólar (R$)**         | Valor fixo usado para converter o custo em reais. Ele não acompanha o câmbio sozinho: atualize quando quiser reajustar.                                |
| **Limite de tokens por resposta** | Tamanho máximo de cada resposta da IA. Protege contra respostas muito longas (e caras). Padrão: `4000`.                                                |
| **Limite de saldo negativo (R$)** | Até quanto o saldo da empresa pode ficar negativo antes de a IA parar. Serve para a IA não cortar uma resposta no meio do atendimento. Padrão: `5,00`. |

3. Clique em **Salvar**.
4. Clique em **Testar conexão**. Se houver falha, a mensagem explica o motivo (conta sem crédito, modelo padrão não escolhido, chave recusada e outros).
5. Se for usar voz, clique em **Testar voz** depois de escolher o modelo de voz na Etapa 2.
6. Quando tudo estiver configurado, ligue a chave **IA da plataforma ligada** e salve.

{% hint style="info" %}
Com a chave **IA da plataforma ligada** desligada, nenhuma empresa consome créditos. Deixe-a desligada enquanto configura e testa as outras abas.
{% endhint %}

***

### Etapa 2: Escolher os modelos (aba Modelos)

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2Fl3jLSLfNGaDHHiR1dtSI%2Fimage.png?alt=media&amp;token=eff1d82c-2a84-4b6d-b04a-1f944024462f" alt=""><figcaption></figcaption></figure>

1. Abra a aba **Modelos** e clique em **Sincronizar modelos**. O Z-PRO busca a lista direto do serviço; nada é gravado até você salvar.
2. Na lista, **marque os modelos que você quer vender**. Só os modelos marcados ficam disponíveis para as empresas.
3. Escolha os modelos de uso geral:

| Campo                     | Para que serve                                                      |
| ------------------------- | ------------------------------------------------------------------- |
| **Modelo padrão**         | Usado quando o modelo escolhido pela empresa não está na lista.     |
| **Modelo de transcrição** | Transcreve áudios recebidos.                                        |
| **Modelo de voz**         | Gera respostas em áudio. Precisa aceitar as vozes padrão da OpenAI. |

4. Clique em **Salvar**.

{% hint style="danger" %}
**Importante:** escolha um **Modelo padrão**. Sem ele, o **Testar conexão** acusa falha.
{% endhint %}

***

### Etapa 3: Definir se haverá margem (aba Preços)

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2F8HTnsVjo1J1kQsvA3haJ%2Fimage.png?alt=media&amp;token=d561c889-0cd5-4b8c-990a-9ffd4b491b08" alt=""><figcaption></figcaption></figure>

1. Abra a aba **Preços**.
2. Defina a chave **Cobrar dos clientes**:
   * **Desligada:** a empresa paga o **custo**, sem margem. Cada uso desconta do saldo o custo do modelo em dólar vezes a sua cotação. Não fica de graça; você só não ganha nada em cima.
   * **Ligada:** aplica as margens da aba **Margens**.
3. Clique em **Salvar**.
4. Confira a tabela de preços. Os valores aparecem **por 1 milhão de tokens de saída**, calculados com a configuração salva (cotação + margem). Esse número é só uma **referência para comparar os modelos**: a cobrança real usa o custo total de cada resposta.

{% hint style="info" %}
**Modelo sem preço no serviço**, como os de servidor próprio, pode ser vendido com o preço que você digitar nesta tabela.
{% endhint %}

***

### Etapa 4: Configurar as margens (aba Margens)

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2Fjaw64DkZit5vfVrGksxB%2Fimage.png?alt=media&amp;token=2aa3e4c2-e8f0-479c-be7d-4ee932951e27" alt=""><figcaption></figcaption></figure>

A margem é aplicada sobre o **custo total** de cada resposta (entrada + saída). Você pode definir uma regra geral por faixa de custo e criar exceções.

#### Margem por faixa de custo

Cada faixa vale para os modelos cujo **preço de saída** vai **até** o valor informado (em US$ por 1 milhão de tokens). O preço de saída só define em qual faixa o modelo cai; o percentual é aplicado sobre o custo total da resposta.

1. Em **Até (US$/1M)**, informe o teto da faixa e, em **Margem (%)**, a margem dela.
2. Clique em **Adicionar faixa** para criar outras.
3. A última linha, **Sem limite**, vale para tudo o que fica acima da última faixa. Preencha a margem dela também.

Se o modelo não se encaixar em nenhuma faixa, a margem é **0**.

Exemplo: margem de 50% para modelos que custam até US$ 1/1M e de 30% para os mais caros. Assim os modelos baratos rendem mais por resposta, sem deixar os caros pesados demais para o cliente.

#### Exceções por provedor

Para dar uma margem diferente a todos os modelos de um provedor, informe o nome em **Provedor**, a **Margem (%)** e clique em **Adicionar**.

#### Exceções por modelo

Para um modelo específico, escolha-o em **Modelo**, informe a **Margem (%)** e clique em **Adicionar**.

Clique em **Salvar** ao terminar.

{% hint style="warning" %}
**Ordem de prioridade:** a exceção por modelo vence a do provedor, que vence a faixa de custo.
{% endhint %}

***

### Etapa 5: Definir como as empresas compram saldo (aba Venda)

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2F7JLkMtaPnw36mItffdsc%2Fimage.png?alt=media&amp;token=1f84e241-ed8e-4f81-acf2-dfb460eb2f59" alt=""><figcaption></figcaption></figure>

1. Abra a aba **Venda** e escolha o **Modo de venda**:
   * **Valor livre:** a empresa escolhe quanto quer adicionar.
   * **Pacotes:** a empresa escolhe entre pacotes que você cria, e você pode dar **bônus** em cada um. Clique em **Adicionar pacote** para criá-los.
2. Preencha:

| Campo                                | O que informar                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Recarga mínima (R$)**              | Menor valor aceito numa recarga. Padrão: `20,00`.                                                             |
| **Aviso de saldo baixo padrão (R$)** | Saldo a partir do qual a empresa é avisada de que está acabando. Padrão: `10,00`.                             |
| **Meio de pagamento reserva**        | Usado quando o plano da empresa é cobrado por um meio sem cobrança avulsa (**Mercado Pago** ou **Pagar.me**). |

3. Clique em **Salvar**.

#### Como a recarga é cobrada

* Plano cobrado pelo **Asaas** ou pela **Stripe**: a recarga usa o mesmo meio e a mesma conta do plano (a chave da empresa ou, se ela não tiver uma, a chave geral).
* Plano cobrado pelo **Mercado Pago** ou pelo **Pagar.me**: a recarga usa o **Meio de pagamento reserva**.
* Empresa sem meio de pagamento próprio no plano: usa o meio geral da instalação.
* O saldo só é creditado **depois que o pagamento é confirmado**. Gerar a cobrança não credita nada.
* Em pacote com bônus, entra o valor de crédito do pacote.

{% hint style="danger" %}
**Importante:** se houver empresas com plano no Mercado Pago ou no Pagar.me e nenhum meio de pagamento reserva escolhido, elas veem "Nenhum meio de pagamento disponível para recarga".
{% endhint %}

***

### Etapa 6: Liberar para as empresas

A IA da plataforma não fica disponível para todas as empresas automaticamente. O **plano** da empresa precisa incluir o recurso e você precisa liberá-lo **para cada empresa**. Sem isso, a opção nem aparece para ela.

1. Acesse **Tenants e Licenciamento > Clientes > Tenants**.
2. Na linha da empresa, clique nos três pontinhos (**⋮**) e escolha **Créditos de IA**.
3. Ligue a chave **Liberar Créditos de IA**. A empresa passa a poder usar a IA da plataforma, consumindo do saldo.

Depois de liberada, a empresa escolhe em quais recursos usar a IA da plataforma. Veja Como usar os Créditos de IA.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2Fv6a2KgoHw1qdfyNbIMWf%2Fimage.png?alt=media&amp;token=a2f2f24c-3c5e-49a8-982b-91ae9a61b507" alt=""><figcaption></figcaption></figure>

Na mesma janela você vê o **Saldo** e o **Extrato** da empresa e pode fazer um **Ajuste manual**: escolha **Creditar** ou **Debitar**, informe o **Valor (R$)** e o **Motivo** e clique em **Aplicar**. Use para dar cortesia, testar ou corrigir um lançamento.

{% hint style="warning" %}
O **Motivo** do ajuste aparece no extrato que a empresa vê. Escreva algo que você não se importe de mostrar ao cliente.
{% endhint %}

A coluna **Créditos de IA** da lista de tenants mostra a situação de cada empresa de relance.

### [Documentação como usar os créditos de IA](https://ajuda.zdg.com.br/configuracao-administrador/configuracao/creditos-de-ia.md)

***

### Resumo das Funcionalidades

| Funcionalidade                                          | Onde acessar                                             |
| ------------------------------------------------------- | -------------------------------------------------------- |
| Conectar o serviço, cotação do dólar e limites          | **IA da plataforma > Conexão**                           |
| Ligar ou desligar o consumo para todas as empresas      | **IA da plataforma > Conexão > IA da plataforma ligada** |
| Escolher modelos à venda, padrão, transcrição e voz     | **IA da plataforma > Modelos**                           |
| Ativar a margem e conferir o preço final                | **IA da plataforma > Preços**                            |
| Margem por faixa, provedor e modelo                     | **IA da plataforma > Margens**                           |
| Valor livre ou pacotes, recarga mínima e aviso de saldo | **IA da plataforma > Venda**                             |
| Liberar o recurso, ver saldo e extrato, ajuste manual   | **Tenants > ⋮ > Créditos de IA**                         |

***

### Encerramento

Com a IA da plataforma configurada, suas empresas usam IA sem precisar contratar um provedor, e você transforma o consumo delas em receita, com margem controlada e saldo pré-pago que protege o seu caixa.

***

### Possíveis Erros e Soluções

#### "Testar conexão" falha com conta sem crédito

**Causa:** a conta no serviço de IA está sem saldo. **Solução:** adicione crédito no painel do serviço e teste de novo.

#### "Testar conexão" falha com chave recusada

**Causa:** chave errada, revogada ou de outro serviço, ou **Endereço do serviço** incorreto. **Solução:** gere uma nova chave no serviço, cole em **Chave de acesso** e confira se o endereço termina em `/v1`.

#### "Testar conexão" falha com modelo padrão não escolhido

**Causa:** o campo **Modelo padrão** da aba **Modelos** está como "Nenhum". **Solução:** sincronize os modelos, escolha um modelo padrão e salve.

#### A lista de modelos aparece vazia

**Causa:** os modelos ainda não foram sincronizados ou a conexão não foi salva. **Solução:** salve a aba **Conexão** e clique em **Sincronizar modelos** na aba **Modelos**.

#### A empresa não consegue usar a IA

**Causa:** a chave **IA da plataforma ligada** está desligada, o plano da empresa não inclui o recurso, ele não foi liberado para ela, o recurso de IA dela está na chave própria ou o saldo passou do limite negativo. **Solução:** confira a chave na aba **Conexão**, o plano da empresa e a chave **Liberar Créditos de IA** em **Tenants > ⋮ > Créditos de IA**. Depois, peça para a empresa conferir se escolheu **IA da plataforma** no recurso e se tem saldo.

#### A empresa vê "Nenhum meio de pagamento disponível para recarga"

**Causa:** o plano dela é cobrado pelo Mercado Pago ou pelo Pagar.me e não há **Meio de pagamento reserva** escolhido. **Solução:** escolha um meio de pagamento reserva na aba **Venda** e salve.

#### O preço de um modelo aparece em branco

**Causa:** o serviço não informa preço para esse modelo (comum em servidor próprio). **Solução:** digite o preço de venda do modelo na tabela da aba **Preços** e salve.


---

# 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-superadmin/tenants-e-licenca/ia-da-plataforma.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.
