Integrar IA ao Asaas, Mercado Pago ou Pagar.me com segurança

Integrar IA ao Asaas, Mercado Pago ou Pagar.me com segurança

Para integrar IA ao Asaas, Mercado Pago ou Pagar.me com segurança, comece por uma integração somente leitura, depois permita que a IA prepare links de pagamento que um humano aprova, e só então avalie qualquer ação mais ampla. Em paralelo, trate os webhooks como entrada não confiável (verifique origem, evite duplicidade) e envie ao modelo apenas os dados financeiros mínimos. A IA entende, resume e propõe. A decisão de cobrar, estornar ou alterar valor continua sob regras fixas e aprovação.

Principais pontos

• Comece com leitura: consultar cobranças, status e vencimentos já resolve boa parte da rotina de cobrança sem risco de movimentar dinheiro.
• Se o provedor não oferecer uma credencial só de leitura para o que você precisa, crie uma camada intermediária sua que exponha à IA apenas funções de consulta.
• Link de pagamento gerado por IA deve passar por aprovação humana, com valor, cliente e descrição conferidos antes do envio.
• Webhook é entrada externa: verifique autenticidade, trate eventos repetidos e nunca deixe o texto de um evento virar instrução para o modelo.
• Envie ao modelo o mínimo de dado pessoal e financeiro, registre cada consulta e cada ação, e defina de antemão quem responde por erro.

Por que começar com acesso somente leitura?

Cobrança é uma área em que um erro custa caro e é difícil de desfazer: cobrar a pessoa errada, duplicar um link, enviar um valor trocado por WhatsApp. Um agente de IA, por mais capaz, pode interpretar mal um pedido ou ser induzido por um texto malicioso. Por isso a primeira versão da integração não deveria ter nenhum poder de escrita.

Com leitura, a IA já faz trabalho útil para o financeiro e o atendimento:

• Responder "esse boleto já foi pago?" consultando o status da cobrança.
• Listar cobranças vencidas de um cliente para quem vai ligar ou escrever.
• Resumir o histórico de um cliente antes de uma negociação.
• Apontar divergências, como pagamento sem cobrança correspondente ou cobrança sem retorno.
• Preparar o rascunho de uma mensagem de lembrete, que uma pessoa envia ou aprova.

Asaas, Mercado Pago e Pagar.me oferecem APIs e chaves de acesso, mas o nível de granularidade das permissões varia entre eles e pode mudar. Consulte a documentação oficial de cada provedor para saber se é possível limitar uma chave a consultas. Se não for, a saída segura é construir uma pequena camada própria (um serviço seu) que guarda a chave completa e expõe à IA somente funções como "consultar cobrança por identificador" e "listar cobranças vencidas de um cliente". A IA nunca vê a chave e nunca chama a API do provedor diretamente.

Esse desenho segue o princípio de menor privilégio descrito no guia de autorização da OWASP: cada componente recebe só a permissão de que precisa para a tarefa.

Como desenhar a integração, passo a passo?

Um plano enxuto, que serve para qualquer um dos três provedores:

• Mapeie o fluxo atual: quem cria cobranças, quem confere pagamentos, quem fala com o cliente inadimplente, onde as informações ficam hoje.
• Escolha uma única pergunta ou tarefa para começar, por exemplo "consultar status de cobrança por pedido".
• Use credenciais de ambiente de testes (sandbox, quando o provedor oferecer) durante todo o desenvolvimento.
• Crie as funções de consulta na camada intermediária, com entradas validadas (identificador no formato esperado, sem texto livre repassado à API).
• Limite o retorno: devolva à IA só os campos necessários, como status, valor, vencimento e identificador, sem documento completo, endereço ou dados de cartão.
• Registre cada chamada: quem pediu, qual função, quando, com que resultado.
• Defina o que a IA responde sozinha e o que ela encaminha a uma pessoa (contestação, estorno, renegociação, qualquer exceção).
• Rode o piloto com um grupo pequeno, compare as respostas da IA com a conferência manual e só depois amplie.

Se a IA vai conversar com clientes pelo WhatsApp, vale ler antes o guia sobre como integrar IA ao WhatsApp da empresa, porque a consulta financeira passa a depender de identificar corretamente quem está do outro lado da conversa.

Como gerar links de pagamento com aprovação humana?

Depois que a leitura estiver estável, o segundo passo natural é a IA preparar um link de pagamento. A palavra importante é preparar, não emitir. O fluxo seguro tem três etapas separadas:

• Proposta: a IA monta um rascunho com cliente, valor, descrição, vencimento e forma de pagamento, a partir de uma fonte confiável (pedido, orçamento ou contrato), nunca apenas a partir do que foi dito na conversa.
• Aprovação: uma pessoa vê o rascunho completo, compara com a fonte e aprova ou recusa. Quem aprova deve ser identificável e ter permissão para isso.
• Emissão: o seu sistema, e não o modelo, chama a API do provedor com os dados exatamente como foram aprovados.

Algumas regras reduzem o risco desse trecho:

• Valores vêm de uma tabela, orçamento ou pedido existente. A IA não calcula desconto por conta própria.
• Defina um teto de valor por link acima do qual a aprovação exige outra pessoa.
• Use chaves de idempotência quando o provedor oferecer, para que uma repetição de chamada não crie cobranças duplicadas. A documentação da Stripe sobre requisições idempotentes é um exemplo claro do conceito. Cada provedor brasileiro tem seu próprio mecanismo, então confirme na documentação oficial dele.
• Guarde o rascunho aprovado, quem aprovou e o identificador do link gerado. Isso é o seu registro de decisão.
• Proíba na camada de código qualquer alteração ou cancelamento de cobrança feita diretamente pela IA.

Para organizar essas barreiras, o artigo sobre guardrails em agentes de IA detalha como validar entrada, saída e ação separadamente. Já o texto sobre o que não delegar à IA na empresa ajuda a decidir onde a aprovação humana não deve ser removida.

O que checar nos webhooks antes de a IA reagir a eles?

Webhooks são as notificações que o provedor envia ao seu sistema quando algo acontece: pagamento confirmado, cobrança vencida, estorno. São úteis, mas são também uma porta aberta na internet. Qualquer pessoa que descubra o endereço pode tentar enviar um evento falso dizendo que uma cobrança foi paga.

O que verificar, de forma geral (os detalhes de assinatura ou token mudam de provedor para provedor, então siga a documentação oficial de cada um):

• Autenticidade: valide a assinatura ou o token que o provedor envia. Rejeite o que não passar. A documentação de webhooks da Stripe mostra o raciocínio de verificação que a maioria dos provedores segue.
• Confirmação na fonte: para eventos sensíveis, como "pago", consulte a API do provedor para confirmar o estado real antes de liberar produto ou serviço.
• Duplicidade: provedores podem reenviar o mesmo evento. Guarde o identificador do evento e ignore repetições.
• Ordem: eventos podem chegar fora de sequência. Use o estado consultado, não só a ordem de chegada.
• Resposta rápida: confirme o recebimento e processe o trabalho pesado depois, em fila, para não perder eventos por tempo esgotado.
• Isolamento do modelo: o conteúdo do evento nunca vira instrução. Campos de texto livre, como descrição ou nome do pagador, podem conter frases que tentam manipular o modelo. Esse risco aparece na lista de riscos para aplicações com LLM da OWASP.

Uma divisão simples ajuda: a lógica determinística (validar, deduplicar, atualizar status) roda em código comum. A IA entra depois, por exemplo para redigir um aviso ao cliente, sempre a partir de campos estruturados e já validados.

Que dados financeiros a IA pode ver, e o que a LGPD pede?

Dados de cobrança identificam pessoas: nome, documento, e-mail, telefone, histórico de pagamento. A LGPD exige finalidade clara, minimização e cuidado com o compartilhamento. Na prática, isso vira regras de projeto:

• Nunca envie ao modelo dados de cartão, senhas, chaves de API ou tokens. Eles não têm utilidade para a tarefa e aumentam o dano de um vazamento.
• Mascare ou omita o que não for necessário: em vez de documento completo, use um identificador interno da cobrança.
• Verifique onde o provedor de IA processa os dados e se há transferência internacional. Esse ponto tem requisitos próprios, que tratamos em um texto separado sobre a LGPD e a transferência de dados com IA.
• Defina por quanto tempo os logs de consulta ficam guardados e quem pode lê-los.
• Se uma decisão sobre uma pessoa for automatizada (por exemplo, negar uma condição de pagamento), consulte a orientação jurídica sobre revisão humana. Para dúvidas de enquadramento, o site da ANPD é a referência oficial.
• Se o modelo for chamado por um agente com ferramentas, mantenha a chave do provedor de pagamento fora do contexto do modelo, guardada no seu servidor.

Este conteúdo é orientação técnica e operacional, não parecer jurídico. Para o enquadramento de base legal e contratos com o provedor de IA, envolva o jurídico ou o encarregado de dados da empresa.

Cenário ilustrativo: cobrança de mensalidade por WhatsApp

Imagine uma pequena empresa de serviços recorrentes que usa um dos três provedores para emitir cobranças mensais. Hoje, uma pessoa do financeiro responde no WhatsApp perguntas como "já caiu meu pagamento?" e "pode mandar o link de novo?".

Na primeira fase, a IA atende apenas a primeira pergunta. Ela identifica o cliente por um dado já validado no cadastro, chama a função de consulta na camada intermediária e responde com o status e a data de vencimento. Se não achar a cobrança, ou se o cliente falar em contestação, ela encaminha à pessoa do financeiro com um resumo.

Na segunda fase, quando o cliente pede o link novamente, a IA não emite nada. Ela cria um rascunho (mesma cobrança, mesmo valor, nova data permitida pela política) e o envia a uma fila de aprovação. A pessoa do financeiro confere, aprova, o sistema emite o link pela API e a IA redige a mensagem com o link já gerado. Todo o caminho fica registrado.

Nada disso exige que o modelo tenha qualquer permissão de escrita no provedor. Para mensagens que a empresa inicia, como lembretes de vencimento, as regras de templates e consentimento do WhatsApp precisam ser respeitadas, e o texto sobre mensagens ativas no WhatsApp cobre esse ponto.

Como o método mapear, limitar, pilotar e transferir se aplica aqui?

Mapear: levantar o fluxo real de cobrança, quem decide o quê e quais perguntas se repetem, antes de escolher qualquer ferramenta. Limitar: definir quais dados e quais funções a IA pode usar, começando por leitura, com a chave do provedor fora do alcance do modelo. Pilotar: rodar um único fluxo, como consulta de status ou rascunho de link, com logs e uma métrica de sucesso combinada de antemão (por exemplo, quantas respostas a pessoa do financeiro precisou corrigir). O guia sobre como medir um piloto de automação com IA detalha esse tipo de critério. Transferir: entregar à equipe a documentação, os logs e o procedimento de revisão, e decidir com base nos dados se o piloto deve expandir, ser ajustado ou parar.

Perguntas frequentes

Posso dar a chave completa da API do Asaas, Mercado Pago ou Pagar.me para a IA? Não é recomendado. Uma chave com poder de escrita permite criar, alterar ou cancelar cobranças, e um erro ou manipulação do modelo teria efeito real. Guarde a chave no seu servidor e exponha à IA apenas funções de consulta bem delimitadas.

A IA pode enviar o link de pagamento diretamente ao cliente? Pode, desde que o link tenha sido aprovado por uma pessoa e emitido pelo seu sistema. O modelo redige a mensagem, mas não define valor, cliente ou condições. Para mensagens que a empresa inicia, respeite as regras de templates e consentimento do WhatsApp.

Como proteger os webhooks de eventos falsos? Valide a assinatura ou o token enviado pelo provedor, confirme eventos sensíveis consultando a API e ignore eventos repetidos pelo identificador. Os detalhes de cada mecanismo estão na documentação oficial do provedor que você usa. Além disso, nunca trate o texto do evento como instrução para o modelo.

Quando faz sentido permitir que a IA execute ações sozinha? Só depois de um piloto com logs, métrica combinada e revisão dos erros, e apenas para ações de baixo risco e fáceis de desfazer. Para estorno, alteração de valor ou cancelamento, mantenha aprovação humana. Se houver dúvida, a resposta padrão é manter a pessoa no circuito.

Fontes

• Stripe: webhook delivery and verification
• Stripe: idempotent requests
• OWASP: Authorization Cheat Sheet
• OWASP Top 10 for LLM Applications