# SharkPay API

> Gateway de pagamentos com API HTTP/JSON (Pix, boleto, cartão, saques Pix, checkout hospedado, webhooks assinados). Autenticação por token Bearer obtido com chave pública + secreta. Valores monetários em decimal (ponto). Idempotency-Key em POST.

## Fontes oficiais (use estas, não adivinhe endpoints)

- [OpenAPI (YAML)](https://sharkpay.com.br/developers/openapi.yaml): contrato completo e fiel ao backend
- [OpenAPI (JSON)](https://sharkpay.com.br/developers/openapi.json)
- [Coleção Postman](https://sharkpay.com.br/developers/postman.json)


## Começar

- [Visão geral e arquitetura](https://sharkpay.com.br/developers/overview): Como o SharkPay funciona e como a integração se organiza.
- [Início rápido](https://sharkpay.com.br/developers/quickstart): Da chave de API à primeira cobrança Pix em 5 passos.
- [Credenciais de API](https://sharkpay.com.br/developers/credentials): Criar, guardar, rotacionar e proteger suas chaves.
- [Autenticação e autorização](https://sharkpay.com.br/developers/authentication): Trocar as chaves por um token Bearer e entender o que ele permite.

## Guias

- [Criar cobranças](https://sharkpay.com.br/developers/payments): Pix, boleto e cartão de crédito pela API.
- [Consultar status de transações](https://sharkpay.com.br/developers/status): Ciclo de vida das cobranças e como acompanhar cada uma.
- [Reembolsos, cancelamentos e saques](https://sharkpay.com.br/developers/refunds): O que a API suporta hoje e o que ainda não existe.
- [Checkout hospedado](https://sharkpay.com.br/developers/hosted-checkout): Receba sem coletar dados de pagamento no seu site.
- [Webhooks](https://sharkpay.com.br/developers/webhooks): Configurar, receber e validar eventos assinados.
- [Idempotência](https://sharkpay.com.br/developers/idempotency): Evitar operações duplicadas com Idempotency-Key.
- [Erros, timeouts e retentativas](https://sharkpay.com.br/developers/errors): Códigos de resposta, o que repetir e como.
- [Teste e produção](https://sharkpay.com.br/developers/environments): Como validar sua integração antes de operar com dinheiro real.
- [Limites, formatos e segurança](https://sharkpay.com.br/developers/limits-security): Limites de requisição, formatos de dados e requisitos de segurança.
- [Testes e solução de problemas](https://sharkpay.com.br/developers/testing): Roteiro de testes e diagnóstico dos problemas mais comuns.

## Integrações

- [Integrar com qualquer sistema](https://sharkpay.com.br/developers/integrations): Lojas, ERPs, SaaS, apps móveis, marketplaces e automações.
- [Exemplos em várias linguagens](https://sharkpay.com.br/developers/examples): Código pronto em cURL, Node.js, Python e PHP.
- [Adquirentes e PayGate](https://sharkpay.com.br/developers/acquirers): Como os adquirentes são plugados no SharkPay e como adicionar o próximo.

## Inteligência artificial

- [Visão geral para IA e agentes](https://sharkpay.com.br/developers/ai): Como assistentes e agentes devem usar a API com segurança.
- [Prompts prontos](https://sharkpay.com.br/developers/ai-prompts): Peça a uma IA para gerar sua integração, em qualquer linguagem.
- [Ferramentas para agentes](https://sharkpay.com.br/developers/ai-tools): Funções (tools) para consultar e operar com controles.
- [Testar e diagnosticar código gerado](https://sharkpay.com.br/developers/ai-testing): Testes automatizados e roteiro de correção.

## Referência

- [Referência da API](https://sharkpay.com.br/developers/reference): Todos os endpoints, gerados da especificação OpenAPI.
- [Versionamento e changelog](https://sharkpay.com.br/developers/changelog): Política de versões e histórico de mudanças.
- [Limitações e roadmap](https://sharkpay.com.br/developers/limitations): O que não existe hoje e o que está planejado.

## Regras para agentes

- Use apenas os endpoints do OpenAPI; o que não estiver lá não existe (veja /developers/limitations).
- Nunca coloque a chave secreta em prompts, logs, front-end ou repositórios; use variáveis de ambiente/cofre.
- Operações que movem dinheiro exigem Idempotency-Key e confirmação humana ou política explícita.
- Confirme pagamentos por webhook assinado ou consulta no servidor; nunca pelo redirecionamento do cliente.