🔒 Autenticação & Segurança

Todas as requisições enviadas para a FastGivr API devem ser autenticadas e transmitidas sob criptografia de canal seguro HTTPS. Esta seção descreve a arquitetura de autenticação segura baseada em JWT (JSON Web Tokens), limites de requisições e regras de segurança.

---

🔑 Fluxo de Autenticação com Token Bearer

A FastGivr utiliza um modelo de autenticação Server-to-Server altamente seguro:

sequenceDiagram
    participant Servidor Cliente
    participant FastGivr Auth API
    participant FastGivr Endpoints

    Servidor Cliente->>FastGivr Auth API: POST /access/account/get-token (envia E-mail e Chave Privada)
    FastGivr Auth API-->>Servidor Cliente: Retorna JWT Bearer Token (Validade: 10 min)
    Servidor Cliente->>FastGivr Endpoints: GET /quickpay/pix/charge (com Header Authorization)
    FastGivr Endpoints-->>Servidor Cliente: Retorna Dados da transação (200 OK)

1. Obtenção do Token: O seu servidor envia a Chave Privada (sec_test_... ou sec_prod_...) e o e-mail cadastrado para obter um token de curta duração.
2. Utilização do Token: Para as chamadas aos endpoints de negócio (criar cobranças, consultar lançamentos), utilize o token JWT no cabeçalho HTTP Authorization.

Authorization: Bearer 2|apiKeyTokenExample123...

---

⏱️ Expiração e Lógica de Renovação (Refresh)

Os tokens Bearer emitidos expiram estritamente após 10 minutos a partir do momento da criação.

💡 Recomendação de Lógica de Renovação

Para evitar que suas transações falhem repentinamente devido à expiração do token, seu sistema de integração deve implementar uma lógica de caching com renovação proativa:

1. Armazene o token Bearer e seu carimbo de expiração (expires_at) na memória do seu servidor (Redis ou memória do processo).
2. Antes de realizar qualquer requisição à FastGivr, compare a hora atual com expires_at.
3. Se o token expirar em menos de 60 segundos, faça uma nova chamada para /access/account/get-token para renová-lo em segundo plano, atualizando o cache.

---

🚦 Controle de Taxa (Rate Limiting)

Para proteger nossa infraestrutura contra abuso e ataques de negação de serviço (DoS), aplicamos políticas estritas de limite de chamadas à API:

Ambiente	Limite Padrão	Escopo do Limite	Cabeçalho de Erro HTTP
Sandbox	60 requisições/min	Por IP e Token de API	429 Too Many Requests
Produção	300 requisições/min	Por IP e Token de API	429 Too Many Requests

Cabeçalhos de Rate Limit Retornados:

Todas as respostas da API contêm cabeçalhos HTTP para monitoramento preventivo:

• X-RateLimit-Limit: O número máximo de requisições permitidas no período.
• X-RateLimit-Remaining: O número de requisições restantes permitidas dentro da janela atual.
• X-RateLimit-Reset: O carimbo de data/hora Unix indicando quando a janela de limite será reiniciada.

---

🛡️ Bochas Práticas de Integração (Guia de Segurança)

Para manter seus dados protegidos, siga rigidamente as seguintes recomendações:

1. Rotação de Chaves de API

• Agende uma rotação semestral de suas chaves secretas (Secret Keys) no painel administrativo da FastGivr.
• Se suspeitar que um funcionário desligado teve acesso a códigos de produção com chaves expostas, revogue e crie uma nova imediatamente.

2. Armazenamento Seguro de Credenciais

• Nunca coloque chaves no código-fonte (hardcoded).
• Utilize variáveis de ambiente protegidas no seu servidor (ex: .env no Node.js/PHP, secrets do AWS Parameter Store ou HashiCorp Vault).

3. Validação de Assinaturas de Webhook

• Para garantir que as notificações de webhook recebidas no seu servidor realmente vieram da FastGivr e não foram manipuladas por terceiros, sempre valide a assinatura criptográfica enviada no header do webhook. Consulte os detalhes na seção de Webhooks.