Visão geral para IA e agentes

Assistentes de programação (Claude, ChatGPT e similares) e agentes autônomos conseguem integrar o SharkPay rápido — desde que usem a API oficial, dentro das permissões que você concedeu.

Recursos legíveis por máquina

Recurso	URL	Uso
OpenAPI 3.1 (YAML)	/developers/openapi.yaml	Fonte da verdade: rotas, parâmetros, schemas, erros.
OpenAPI (JSON)	/developers/openapi.json	Para ferramentas que não leem YAML (function calling).
llms.txt	/llms.txt	Índice das páginas e regras para agentes.
Coleção Postman	/developers/postman.json	Testar manualmente o que a IA gerou.

Arquitetura recomendada

Camadas

Agente de IA / assistente
        │  (só vê nomes de ferramentas e resultados resumidos)
        ▼
  Camada de ferramentas no SEU servidor  ← aplica permissões, limites, aprovação humana, logs
        │  (lê SHARKPAY_* do ambiente; o agente nunca vê)
        ▼
  API oficial do SharkPay (HTTPS, Bearer, Idempotency-Key)
        ▲
        │  webhook assinado
  Seu receptor de webhook → atualiza pedidos

Há dois usos distintos, com riscos diferentes:

Uso	Exemplo	Risco
A IA ESCREVE o código da integração	Você pede ao assistente o módulo de pagamento; você revisa, testa e faz deploy.	Baixo se você revisar e nunca colar segredos no chat.
A IA OPERA a API em tempo de execução	Agente que consulta cobranças ou emite saques.	Alto: exige ferramentas restritas, permissões mínimas e aprovação humana para dinheiro.

Como a IA deve entender a API

Dê a ela o openapi.yaml (ou o llms.txt e a Referência) como contexto. É a fonte da verdade.
Diga o que não existe: sem sandbox, sem endpoint de reembolso/cancelamento, sem escopos de token, sem recorrência/split (veja Limitações). Modelos tendem a inventar esses recursos.
Peça que cite o operationId usado em cada chamada — facilita a revisão.
Peça código com: leitura de segredos do ambiente, Idempotency-Key, timeouts, retentativas com backoff, verificação de assinatura sobre o corpo bruto e testes.

Fluxos que a IA precisa conhecer

Autenticar: POST /api/auth (Basic) → Bearer; renovar ao receber 401.
Cobrar: POST /api/pix/create com Idempotency-Key → guardar reference → aguardar invoice.paid.
Confirmar: webhook assinado ou GET /api/invoice/ref/{ref}.
Sacar: POST /api/pixout/create — dinheiro saindo; sempre com aprovação.

Controles obrigatórios para agentes que operam a API

Controle	Como
Menor privilégio	Exponha ao agente só as ferramentas necessárias (ex.: consultar). Não exponha saque se ele só precisa ler.
Segredo fora do agente	A camada de ferramentas lê SHARKPAY_SECRET_KEY; o agente nunca recebe a chave nem o token.
Aprovação humana	Operações que movem dinheiro retornam “pendente de aprovação” e só executam após confirmação de uma pessoa.
Limites	Valor máximo por operação, total por dia, lista de chaves Pix permitidas.
Idempotência	Chave determinística por intenção (ex.: hash do pedido + valor + destino).
Auditoria	Registre quem pediu, parâmetros (sem segredos) e resultado.
Dados sensíveis	Nunca envie número/CVV de cartão ao modelo; mascare documentos e e-mails quando possível.

Próximos passos: prompts prontos, ferramentas para agentes e testes e diagnóstico.