🏁 Primeiros Passos & Setup

Este guia orienta desenvolvedores e integradores desde a criação da conta até a execução da primeira chamada de API bem-sucedida na FastGivr Money.

---

🛠️ Fluxo de Integração (Passo a Passo)

graph LR
    A[1. Criar Conta] --> B[2. Obter Chaves de API]
    B --> C[3. Testar em Sandbox]
    C --> D[4. Configurar Webhooks]
    D --> E[5. Virar para Produção 🚀]

---

📌 Passo 1: Cadastro e Acesso ao Portal

Para começar, você precisa de um usuário cadastrado vinculado a uma conta FastGivr.

1. Acesse o portal administrativo da FastGivr (https://painel.fastgivr.com.br).
2. Complete seu onboarding societário (upload de documentos cadastrais básicos).
3. Aguarde a aprovação da conta (geralmente realizada em menos de 2 horas em dias úteis).

---

🔑 Passo 2: Localizar as Chaves de API

Com sua conta aprovada:

1. No menu lateral do portal administrativo, clique em Desenvolvedores > Chaves de API.
2. Você encontrará duas chaves para cada ambiente (Sandbox e Produção):
   • Chave Pública (Publishable Key): Começa com pk_test_... ou pk_prod_.... Usada no frontend (ex: formulário de captura de cartão de crédito).
   • Chave Privada (Secret Key/Token): Começa com sec_test_... ou sec_prod_.... Usada exclusivamente no seu servidor backend para assinar requisições sensíveis.

WARNING

Nunca exponha sua Chave Privada (sec_prod_...) em códigos de frontend (HTML/JavaScript no navegador), repositórios públicos de Git ou aplicativos mobile. Caso ocorra vazamento, revogue-a imediatamente no painel administrativo.

---

🔬 Passo 3: Sandbox vs Produção (Ambientes)

A FastGivr opera dois ambientes completamente isolados para garantir testes seguros:

Característica	Sandbox (Ambiente de Testes)	Produção (Ambiente Real)
URL Base	https://api-sandbox.fastgivr.com.br/api/v1	https://api.fastgivr.com.br/api/v1
Prefixo da Chave	sec_test_... e pk_test_...	sec_prod_... e pk_prod_...
Dinheiro Real	❌ Não transaciona valores reais.	🟢 Transações reais liquidadas instantaneamente.
Simuladores	Permite simular liquidação de Pix/Boleto e recusa de cartão.	Transações processadas por adquirentes reais.

---

📡 Passo 4: Executando a Primeira Requisição

Vamos realizar uma requisição simples de autenticação na API de Sandbox usando a sua chave secreta de testes.

Exemplo em cURL

Substitua seu_email@empresa.com pelo e-mail do seu cadastro e sec_test_123 pela sua chave secreta obtida no painel.

curl -X POST https://api-sandbox.fastgivr.com.br/api/v1/access/account/get-token \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
           "email": "seu_email@empresa.com",
           "token": "sec_test_123"
         }'

Resposta Esperada (200 OK)

A API retornará o token Bearer temporário que você usará nas chamadas subsequentes:

{
  "success": true,
  "data": {
    "token": "1|bearerTokenExample123...",
    "token_type": "Bearer",
    "expires_at": "2026-05-18T16:10:00+00:00"
  },
  "message": "Autenticado com sucesso"
}

---

🚀 Passo 5: Migrando para Produção

Depois de testar com sucesso todas as suas rotas no ambiente de Sandbox:

1. Altere a URL base das chamadas para a URL de Produção: https://api.fastgivr.com.br/api/v1.
2. Substitua as credenciais de teste pelas chaves reais de Produção (sec_prod_...).
3. Registre a URL de webhook do seu servidor de Produção para escutar os eventos de transações reais.