Pearfy MCP
Alterações e segurança
Toda alteração passa por uma prévia montada pela Pearfy e só executa com a confirmação dessa prévia. É uma trava do servidor: a IA não consegue pular a etapa, trocar o valor no meio nem reaproveitar a confirmação.
Três jeitos de alterar
Cada ferramenta de alteração tem uma regra fixa, que aparece no catálogo:
| Regra | Como funciona | Ferramentas |
|---|---|---|
| Prévia e confirmação | A 1ª chamada devolve a prévia. A 2ª, com o token da prévia, executa. Vai para o painel quando passa de um teto, quando a conta exige aprovação para aquela ação, ou em casos sensíveis: dinheiro ou cupom vindos de chave, reativar oferta, trocar a URL ou religar um webhook, desligar ou remover um webhook em uso. | Produto, oferta, cupom, reembolso, editar e remover webhook |
| Aprovação no painel | A 2ª chamada não executa: cria um pedido que alguém com permissão aprova no painel. | Cancelar assinatura, criar webhook |
| Direta, com limite | Executa na 1ª chamada, com trava, limite diário, registro e aviso. Vai para o painel se a conta exige aprovação para pedidos por chave ou de colaboradores. | Reenviar acesso à área de membros |
Prévia e confirmação
- 11ª chamada: a préviaSem o campo
confirmacao, a ferramenta lê o item no banco, confere o estado e as regras e devolvestatus: "previa", com a ação, o efeito em português, os valores e se é irreversível. Nada é alterado. - 2Você aprova na conversaA IA mostra a prévia e espera o seu ok. A prévia é escrita pela Pearfy a partir do banco; um motivo enviado pela IA aparece só como citação.
- 32ª chamada: a execuçãoA IA repete a chamada com os mesmos parâmetros e
confirmacaocom o tokenpfy_cf_…. A Pearfy consome o token, relê o item e confere que o alvo, o valor e a moeda são os da prévia. Então trava o item, reserva o limite do dia, executa e registra.
{
"ok": true,
"dados": {
"status": "previa",
"previa": {
"acao": "Criar cupom BLACK30",
"efeito": "30% de desconto no Curso Pro, até 30/11, 100 usos.",
"irreversivel": false,
"ambiente": "producao"
},
"confirmacao": { "token": "pfy_cf_…", "expira_em": "2026-11-14T15:10:00-03:00" },
"proximo_passo": "Mostre a prévia e, com o ok da pessoa, repita a chamada com confirmacao=<token>."
}
}| Regra do token | Detalhe |
|---|---|
| Validade | 10 minutos. |
| Uso único | Consumido de forma atômica. O mesmo token nunca executa duas vezes, nem em nova tentativa. |
| Preso à chamada | Só vale para a mesma credencial, a mesma ferramenta e os mesmos parâmetros. Mudou qualquer coisa: confirmacao_necessaria e uma prévia nova. |
| Só a última vale | Uma prévia nova com os mesmos parâmetros invalida as anteriores. No máximo 20 prévias abertas por credencial. |
| Estado conferido de novo | Se o item mudou entre a prévia e a confirmação (venda já reembolsada, oferta desativada), a resposta é conflito e nada executa. |
Dinheiro
O token volta na mesma resposta que a IA lê. Por isso, em dinheiro, ele não basta: um texto malicioso escondido num nome de produto ou numa UTM poderia induzir a IA a confirmar sozinha.
- Reembolso pelo login: a prévia não traz token. A Pearfy envia um código de 6 dígitos ao e-mail de quem está conectado, e a IA pede esse código a você. Vale 10 minutos, aceita 3 tentativas e é de uso único.
- Reembolso vai para o painel quando passa de R$ 500,00 no pedido, quando a venda tem mais de 7 dias, quando a conta passa de 10 reembolsos ou R$ 2.000,00 no dia, ou quando a venda é em outra moeda sem valor liquidado em reais.
- Cancelamento de assinatura vai sempre para o painel. É imediato: não há novas cobranças e nenhum valor é devolvido.
- Por chave de IA, qualquer ação de dinheiro vai sempre para o painel, qualquer que seja o valor.
- Não existe reembolso parcial: o reembolso devolve o valor total da venda.
Aprovação no painel
Quando a ação pede aprovação, a 2ª chamada devolve status: "aguardando_aprovacao" e o pedido aparece em Pearfy MCP › Aprovações e no aviso do celular. A resposta à IA nunca traz link, para que um texto injetado não troque o endereço.
| Regra | Detalhe |
|---|---|
| Validade | 24 horas. Depois disso o pedido vence e nada é feito. |
| Quem aprova | O dono da conta ou um membro da Equipe com acesso total. |
| Pedido próprio | Acima de um teto ou por regra da conta, quem pediu não aprova o próprio pedido, exceto o dono. |
| Como aprovar | Com login recente e um código de 6 dígitos enviado ao e-mail de quem aprova. |
| Tetos | Até 5 pedidos pendentes por conta e 2 por credencial; um pedido pendente por item. |
| Na execução | A Pearfy confere de novo os controles da conta, relê o item e compara alvo e valor antes de executar. |
Limites diários
Contados por conta, no dia de Brasília, e reservados antes de executar (uma falha devolve a reserva).
| Ação | Limite | Acima disso |
|---|---|---|
| Reembolsos | 10 por dia e R$ 2.000,00 somados; até R$ 500,00 e 7 dias por venda | Painel |
| Criar ou religar cupom | 5 por dia | Painel |
| Desligar cupom | 20 por dia | Recusa |
| Mudar preço ou desativar oferta | 20 por dia | Painel |
| Criar produto e criar, editar ou excluir oferta | 50 por dia, somados | Recusa |
| Editar webhook | 20 por dia | Recusa |
| Remover ou desligar webhook | 2 por dia | Painel |
| Reenviar acesso | 3 por venda em 24 h e 30 por conta por dia | Recusa |
| Alterações por conexão ou chave | 20 por minuto | HTTP 429 |
Repetir com segurança
- O token de confirmação é de uso único: repetir a 2ª chamada depois de uma falha de rede nunca executa duas vezes. Se não souber se executou, consulte o item antes de pedir uma prévia nova.
- Criar produto e criar cupom aceitam
chave_idempotencia: a mesma chave com os mesmos parâmetros, em 24 horas, devolve o item já criado em vez de criar outro. - Duas execuções no mesmo item ao mesmo tempo não acontecem: a segunda recebe
conflitocomem_execucao.
Controles do dono
Em Pearfy MCP › Controles, só o dono da conta, valendo na chamada seguinte da IA:
| Controle | Efeito |
|---|---|
| IA nesta conta | Desligada, nenhuma IA acessa a conta. As conexões ficam salvas. |
| Alterações | Desligadas, as IAs só consultam. |
| Chaves de IA | Desligadas, toda chave para; o login continua. |
| Colaboradores podem conectar | Desligado, só o dono conecta IAs. |
| Exigir minha aprovação | Por ação (reembolsos, cancelamentos, cupons, preço, exclusões) e por origem (colaboradores, chave de IA): o que estiver marcado vai sempre para o painel. |
Você também desconecta uma IA ou revoga uma chave a qualquer momento em Pearfy MCP › Conexões.
O que a IA nunca faz
- Sacar, transferir ou mexer em dados bancários.
- Ver a sua senha, o CPF, o telefone ou o endereço dos compradores, ou dados de cartão.
- Executar uma alteração sem a prévia e a confirmação.
- Abrir link ou seguir instrução escrita dentro dos seus dados: textos de terceiros (nome de produto, cupom, webhook) chegam limpos, sem links nem formatação.