> For the complete documentation index, see [llms.txt](https://ajuda.uplaces.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.uplaces.com.br/agentes-de-ia/chaves-permissoes-e-historico.md).
# Chaves, permissões e histórico dos agentes
Chave de acesso, permissões e histórico dos Agentes de IA: crie e revogue chaves, escolha o que o agente pode ler e alterar por área e veja tudo o que ele fez.
Aqui você controla o que cada agente pode fazer na sua loja: cria e revoga chaves de acesso, escolhe as áreas e o prazo, simula antes de gravar e acompanha tudo no histórico. A regra é a do menor acesso: o agente só faz o que a chave permite, e nunca mais do que a pessoa que a criou.
Quem conecta pelo Claude ou pelo ChatGPT (1 clique) segue os mesmos controles. Se ainda não conectou, comece por [Agentes de IA: conecte o Claude ou o ChatGPT à sua loja](/agentes-de-ia.md).
{% hint style="info" %}
Abra **Agentes de IA** no menu da loja. O item só aparece com o módulo ligado em **Módulos**, e a tela é só para administradores da loja.
{% endhint %}
## Chave ou conexão de 1 clique: qual usar
As duas formas dão o mesmo tipo de acesso e seguem as mesmas regras.
| | Conexão de 1 clique (OAuth) | Chave de acesso |
| ------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| **Para quem** | Claude, ChatGPT, Cursor, VS Code | Claude Code, Claude Desktop, n8n, servidor próprio |
| **Como** | Você cola o endereço do servidor e aprova na tela da Uplaces | Você cria a chave aqui e cola na configuração do agente |
| **Na tabela** | Aparece como **conector OAuth**, e a chave renova sozinha | Aparece com o começo da chave (`upl_mcp_...`) |
| **Validade** | Escolhida na tela de aprovação | Escolhida ao criar a chave |
{% hint style="info" %}
Use a conexão de 1 clique quando o aplicativo oferecer. Use chave quando o agente roda num terminal, num servidor ou numa automação.
{% endhint %}
## Criar uma chave
1. Abra **Agentes de IA** e clique em **Nova chave**. Na primeira vez, o botão se chama **Criar chave e conectar**.
2. Em **Nome**, escreva para que a chave serve, com pelo menos três letras. Por exemplo: `Claude, catálogo`.
3. Em **Validade**, escolha o prazo na lista, de dias até 1 ano.
4. Em **O que o agente pode fazer**, escolha o acesso (veja a seção 3).
5. Se o agente roda num servidor com IP fixo, abra **Opções avançadas** e informe os **IPs autorizados** (veja a seção 5).
6. Clique em **Criar chave**.
Na tela **Chave criada**:
1. Clique em **Copiar** e guarde a chave. A tela avisa: "Copie agora: ela não aparece de novo."
2. Escolha o seu cliente (Claude Code, Claude Desktop, Cursor / VS Code ou n8n / HTTP) para ver o trecho pronto para colar.
3. Cole a chave na **configuração do agente**, nunca dentro da conversa com ele.
4. Aguarde. Quando o agente fizer a primeira chamada, a tela mostra **Conectado** e o nome do aplicativo.
5. Clique em **Concluir**.
{% hint style="info" %}
A Uplaces guarda só uma impressão da chave e não consegue mostrá-la de novo. Se perder a chave, revogue e crie outra.
{% endhint %}
A loja tem um limite de chaves ativas. Quando chegar nele, a tela pede para revogar as que você não usa antes de criar outra.
## Permissões por área
Cada chave vale para uma loja e tem permissões por área. Em cada área você escolhe **Ler** (o agente só consulta) ou **Alterar** (o agente também grava). Quem pode alterar também pode ler.
Os três atalhos:
| Atalho | O que libera |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Só consultar** | Ler em todas as áreas, inclusive pedidos. Não altera nada |
| **Catálogo e preços** | Ler a loja virtual. Ler e alterar produtos, categorias, estoque, tabelas de preço, condições de pagamento e políticas comerciais |
| **Configurar a loja inteira** | Ler e alterar em todas as áreas. Pedidos continuam só leitura |
As áreas:
| Área | Ler | Alterar |
| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
| **Loja virtual** | ver configurações, aparência e módulos | alterar aparência, textos e ligar ou desligar módulos |
| **Produtos** | ver produtos, categorias e estoque | cadastrar e alterar produtos, categorias e estoque |
| **Clientes** | ver clientes | cadastrar e alterar clientes |
| **Preços e condições** | ver tabelas de preço, condições de pagamento e políticas | alterar tabelas de preço, condições de pagamento e políticas |
| **Descontos e cashback** | ver cupons, promoções, regras de desconto e cashback | alterar cupons, promoções, regras de desconto e cashback |
| **Impostos** | ver regras de IPI e ICMS-ST | alterar regras de IPI e ICMS-ST |
| **Meios de pagamento** | ver meios de pagamento (credenciais nunca aparecem) | ativar, desativar e ajustar meios de pagamento (nunca credenciais) |
| **Logística** | ver fretes e transportadoras | alterar fretes e transportadoras |
| **Vendedores e comissões** | ver vendedores e comissões | alterar comissões |
| **Pedidos** | ver pedidos, itens e status | não existe: pedidos são só leitura |
Para montar um acesso sob medida, abra **Personalizar por área** e marque **Ler** e **Alterar** em cada linha.
Na tabela de chaves:
A coluna **Acesso** mostra uma etiqueta: **Só consultar**, **Catálogo e preços**, **Loja inteira** ou **Personalizada** com o número de áreas. Passe o mouse no ponto de interrogação para ver a lista: "Lê e altera" e "Só lê".
{% hint style="info" %}
Dê o menor acesso que resolve a tarefa. Para testar, comece por **Só consultar**.
{% endhint %}
Cada área depende do módulo correspondente:
Algumas ações só existem quando o módulo está ligado na sua loja, como Cashback, Impostos e Meios de pagamento. Em **O que o agente pode fazer**, as áreas sem módulo ligado mostram **módulo desligado**. Ligue o módulo em **Módulos** para liberar as ações.
{% hint style="warning" %}
Credenciais de pagamento nunca ficam ao alcance do agente. Chave de gateway, chave Pix e conta de recebimento só se alteram pela tela, por uma pessoa.
{% endhint %}
## Prazo da chave
Toda chave tem validade. A coluna **Expira** mostra a data. Quando falta pouco, a data fica em destaque, com o aviso: "Crie outra chave antes do prazo para o agente não parar."
Depois do prazo, a coluna mostra **expirou** e o agente deixa de funcionar. Crie outra chave e atualize a configuração do agente.
{% hint style="info" %}
Para testes, use o prazo mais curto. Para automações que rodam todo dia, anote a data e crie a chave nova antes do vencimento.
{% endhint %}
## Limitar por IP
Se o agente roda num servidor com IP fixo, como o n8n em uma VPS, restrinja a chave a esse endereço. Em **Opções avançadas**, preencha **IPs autorizados**:
```
203.0.113.10, 198.51.100.0/24
```
Você pode informar um IP, vários separados por vírgula ou uma faixa. Com o campo vazio, a chave aceita qualquer origem. Chamadas de outro IP são recusadas.
Na tabela, a chave com lista de IPs mostra **IP restrito** na coluna **Expira**.
{% hint style="info" %}
Não use lista de IPs se o agente roda no seu computador ou em um serviço que muda de endereço. Nesse caso, a chamada seria recusada.
{% endhint %}
## Simulação antes de gravar
Toda alteração que o agente faz aceita simulação. Na simulação, o agente valida o pedido com as mesmas regras da tela, mostra o que mudaria e não grava nada. As exclusões exigem confirmação explícita.
1. Peça ao agente: "Simule antes de gravar."
2. Leia o que ele mostra: os campos que mudariam, de qual valor para qual valor.
3. Se estiver certo, diga: "Pode gravar."
A simulação aparece no histórico com o status **simulação**.
{% hint style="info" %}
Em alterações em lote, como preços ou estoque de muitos produtos, simule sempre. Uma instrução vaga vira muitas alterações de uma vez.
{% endhint %}
## Histórico: o que o agente fez
O bloco **Atividade dos agentes** tem uma linha por chamada, inclusive as recusadas.
O que cada linha mostra:
* quando aconteceu e qual chave fez;
* o que foi pedido, como "Criar cupom";
* o status:
| Status | O que significa |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| **gravou** | O agente alterou algum dado da loja |
| **simulação** | O agente simulou, nada foi gravado |
| **recusado** | O pedido foi recusado: argumento inválido, limite de ritmo, confirmação ausente ou erro. Nada foi gravado |
| **erro** | Algo falhou. Nada foi gravado |
| **conexão** | O aplicativo conectou na loja |
Para ver o antes e o depois:
1. Clique na linha.
2. A tela mostra cada campo alterado, com o valor de antes e o de depois, e o pedido que o agente enviou.
Filtros:
Use **Todas** ou **Só alterações**. Em **Só alterações**, aparecem apenas as chamadas que gravaram algo.
Cartões de resumo:
Depois do primeiro uso, o topo da tela mostra **Chamadas em 7 dias**, **Alterações gravadas** e **Recusadas**. Na tabela de chaves, a coluna **Uso 7 dias** mostra as chamadas de cada chave e quantas foram recusadas, e **Último uso** mostra quando e por qual aplicativo.
Leituras:
Das consultas, o histórico guarda só o que foi pedido, nunca os dados que voltaram.
O histórico fica guardado por alguns meses, não para sempre. Se precisar de um registro de longo prazo, copie o que for importante.
## Revogar uma chave
1. Abra **Agentes de IA**.
2. Na tabela **Chaves de acesso**, localize a chave. Quem conectou com 1 clique aparece como **conector OAuth**.
3. Clique em **Revogar**. O botão muda para **Confirmar revogação**.
4. Clique de novo para confirmar. O acesso termina na hora.
O que acontece:
* A chave revogada aparece na tabela com a data da revogação. Não dá para desfazer: crie outra, se precisar.
* Enquanto o módulo **Agentes de IA** estiver desligado em **Módulos**, nenhuma conexão funciona.
**Para mudar as permissões de uma chave**, crie outra com o acesso novo e revogue a antiga. Para uma conexão de 1 clique, refaça a conexão e aprove com as permissões novas.
## Limites de uso
Cada chave tem limite de chamadas por minuto e de alterações por minuto, e a loja tem limites diários. Quando o agente passa do limite, a Uplaces responde com o tempo de espera, e o agente deve aguardar antes de tentar de novo.
Os limites protegem a loja dos seus compradores: o uso de agentes nunca deve tirar recurso de quem está comprando. Se o seu uso legítimo bate no limite com frequência, fale com o suporte.
## Boas práticas de segurança
* Menor acesso possível. Comece por **Só consultar**. Libere **Alterar** só nas áreas da tarefa.
* Uma chave por agente. Dê nomes claros, como `n8n, estoque`. Assim o histórico mostra quem fez cada coisa.
* A chave vai na configuração, nunca na conversa. Não cole a chave no chat com o agente, em e-mail, em planilha nem em print.
* Perdeu ou vazou? Revogue na hora e crie outra.
* Prazo curto para testes. Revogue as chaves que você não usa mais.
* IP fixo para servidores. Se a automação roda em IP fixo, limite a chave a ele.
* Simule antes de gravar, principalmente em alterações em lote.
* Revise o histórico. Abra **Só alterações** com frequência e confira o que mudou.
* Confira o endereço de retorno na tela de aprovação. Se você não reconhece o endereço, clique em **Recusar**.
* Cuidado com texto de terceiros. Um documento, e-mail ou planilha que você manda para o agente pode conter instruções escondidas. Por isso a chave deve ter só as permissões da tarefa, e a simulação deve ser lida antes de gravar.
* Se a pessoa que criou a chave sai da empresa, a chave para junto quando ela perde o acesso à loja. Mesmo assim, revogue as chaves dela.
* Lembre para onde vão os dados. O que o agente lê passa pelo serviço de IA que você escolheu (Claude, ChatGPT, Cursor ou outro). Confira a política de privacidade desse serviço.
## Perguntas frequentes
O agente alterou algo errado. Como desfazer?
A Uplaces não desfaz sozinha. Abra **Atividade dos agentes**, clique na alteração e veja o valor de antes. Depois peça ao agente para restaurar esse valor, ou corrija pela tela da loja. Para evitar, simule antes de gravar.
Posso editar as permissões de uma chave que já criei?
Não. Crie outra chave com o acesso novo e revogue a antiga.
A chave aparece de novo depois de criada?
Não. A tela mostra a chave completa uma única vez, ao criar. Depois, só o começo dela fica visível. Se perder, revogue e crie outra.
Quem consegue ver e criar chaves?
Administradores da loja, em **Agentes de IA**. O agente age em nome de quem criou a chave e nunca com mais permissão que essa pessoa.
O agente consegue alterar pedidos?
Não. Os pedidos são só leitura para o agente. Ele consulta pedidos, itens e status.
## Problemas comuns: o agente foi recusado?
Abra **Atividade dos agentes** e clique na linha **recusado**. A mensagem diz o motivo. Os mais comuns:
1. A ação está fora do acesso da chave. A chave não tem **Ler** ou **Alterar** nessa área, e o agente não consegue usar a ação ou diz que ela não existe. Crie outra chave com o acesso certo.
2. Módulo desligado. A ação depende de um módulo, como Cashback ou Impostos. Ligue em **Módulos**.
3. Dado inválido. A mensagem diz o campo. Peça ao agente para corrigir e simular de novo.
4. Confirmação ausente. Uma exclusão exige confirmação explícita. Peça ao agente para confirmar.
5. Limite de ritmo. O agente chamou rápido demais. Ele recebe o tempo de espera e deve aguardar.
Se o agente nem chega a aparecer na atividade, veja na tabela de chaves se a chave **expirou**, foi **revogada** ou tem **IP restrito** diferente do endereço de onde o agente chama. Nesses casos, crie outra chave ou ajuste o IP.
## Veja também
* [Agentes de IA: conecte o Claude ou o ChatGPT à sua loja](/agentes-de-ia.md)
* [Agentes de IA: o que pedir ao agente](/agentes-de-ia/o-que-pedir.md)
* No site: [integrações](https://uplaces.com.br/integracoes/)