For the complete documentation index, see llms.txt. This page is also available as Markdown.

IA da plataforma

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.

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.


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.


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.

  1. Clique em Salvar.

  2. 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).

  3. Se for usar voz, clique em Testar voz depois de escolher o modelo de voz na Etapa 2.

  4. Quando tudo estiver configurado, ligue a chave IA da plataforma ligada e salve.

Com a chave IA da plataforma ligada desligada, nenhuma empresa consome créditos. Deixe-a desligada enquanto configura e testa as outras abas.


Etapa 2: Escolher os modelos (aba Modelos)

  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.

  1. Clique em Salvar.


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

  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.

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.


Etapa 4: Configurar as margens (aba Margens)

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.


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

  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).

  1. 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.


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.

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.

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


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.

Atualizado

Isto foi útil?