Limites, formatos e segurança
Limites da API, formatos aceitos e o que você precisa cumprir para operar com segurança.
Limites de requisição
| Rota | Limite | Chave do limite |
|---|---|---|
| POST /api/auth | 10 por minuto | IP |
| GET /api/cep/search/{cep} | 30 por minuto | IP |
| Demais rotas /api | 60 por minuto | Conta autenticada (ou IP) |
Ao exceder, a API responde 429 com o cabeçalho Retry-After (segundos). Veja a estratégia de retentativa em Erros. Precisa de mais? Fale com o suporte; não existe elevação automática.
Formatos de dados
| Item | Formato |
|---|---|
| Corpo | JSON (Content-Type: application/json), UTF-8. Exceção: o checkout hospedado recebe formulário. |
| Valores no envio | Números com ponto decimal (12.50), sem milhar, maiores que zero. |
| Valores na resposta | Strings decimais com 2 casas ("12.50"). |
| Datas | AAAA-MM-DD na entrada; nas respostas, data/hora do servidor. |
| Moeda | Moeda ativa da plataforma (BRL). |
| Paginação | page + limit (máx. 50 em /api/invoices; saques: 25 por página). |
| Identificadores | Cobrança: INV-XXXXXX; webhook: evt_…; chaves: PUB-… / SEC-…. |
Requisitos de segurança
- HTTPS sempre. Não envie chaves nem tokens por HTTP.
- Chave secreta só no servidor. Nunca em navegador, app móvel, repositório, log, e-mail ou prompt de IA. Apps móveis falam com o seu backend, que fala com o SharkPay.
- Isolamento por conta. Você só lê e altera recursos da sua conta; um id de outra conta responde 404.
- Segredos em repouso. A chave secreta e o segredo do webhook ficam criptografados no banco da plataforma e nunca são devolvidos em consultas.
- Webhooks assinados com HMAC-SHA256 e proteção contra replay (janela de 5 min). URLs de webhook que apontam para redes privadas são bloqueadas (proteção SSRF) e a conexão é fixada no IP validado.
- Tokens com acesso integral à conta. Não existem escopos hoje; trate o token como a própria chave. Prazo padrão 30 dias.
- Cartão: receber número/CVV implica PCI DSS. Prefira o checkout hospedado.
- Rotação: gere novas chaves no painel ao suspeitar de vazamento; as antigas deixam de valer na hora.