📖 Introdução

Bem-vindo à documentação da FlashPix API. Esta API permite integração completa com o sistema de pagamentos PIX, incluindo geração de QR Codes, pagamentos e consulta de saldo.

Base URL

https://api.flashpix.cloud

Protocolo

A API utiliza o protocolo HTTP/HTTPS com requisições e respostas no formato JSON.

Características

• ✅ Autenticação OAuth 2.0 com Client Credentials
• ✅ Geração de QR Code PIX dinâmico
• ✅ Pagamentos PIX via chave
• ✅ Consulta de saldo em tempo real
• ✅ Webhooks para notificações
• ✅ Cálculo automático de taxas

🔐 Autenticação

A API utiliza tokens JWT (JSON Web Tokens) para autenticação. Você precisa obter um access_token através do endpoint OAuth antes de fazer requisições aos endpoints protegidos.

Fluxo de Autenticação

1. Obtenha suas credenciais (client_id e client_secret)
2. Faça uma requisição POST para /v2/oauth/token com Basic Auth
3. Receba o access_token na resposta
4. Use o token no header Authorization: Bearer {token} nas próximas requisições

Headers Necessários

🔑 OAuth - Obter Token de Acesso

Endpoint para obter ou renovar o access_token usando credenciais do cliente.

Headers

Exemplo de Requisição

POST /v2/oauth/token HTTP/1.1
Host: api.flashpix.cloud
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

Exemplo com cURL

curl -X POST https://api.flashpix.cloud/v2/oauth/token \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -H "Content-Type: application/json"

Resposta de Sucesso (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Parâmetros da Resposta

Possíveis Erros

💰 Consultar Saldo

Endpoint para consultar o saldo disponível do usuário autenticado.

Headers

Exemplo de Requisição

POST /v2/balance HTTP/1.1
Host: api.flashpix.cloud
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Exemplo com cURL

curl -X POST https://api.flashpix.cloud/v2/balance \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Resposta de Sucesso (200 OK)

{
  "amount": 1500.50
}

Parâmetros da Resposta

Possíveis Erros

💳 PIX - Pagamentos

Gerar QR Code PIX

Endpoint para gerar um QR Code PIX dinâmico para recebimento de pagamentos.

Headers

Parâmetros do Body (JSON)

Exemplo de Requisição

POST /v2/pix/qrcode HTTP/1.1
Host: api.flashpix.cloud
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "amount": 150.00,
  "external_id": "TXN123456789",
  "payerQuestion": "Pagamento de serviço",
  "postbackUrl": "https://seusite.com/webhook",
  "payer": {
    "name": "João Silva",
    "document": "12345678900"
  }
}

Exemplo com cURL

curl -X POST https://api.flashpix.cloud/v2/pix/qrcode \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "external_id": "TXN123456789",
    "payerQuestion": "Pagamento de serviço",
    "postbackUrl": "https://seusite.com/webhook",
    "payer": {
      "name": "João Silva",
      "document": "12345678900"
    }
  }'

Resposta de Sucesso (201 Created)

{
  "transactionId": "e76e996f57849498d0ddm4ebrz4y5g55",
  "status": "PENDING",
  "qrCode": "00020126580014br.gov.bcb.pix...",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "postbackUrl": "https://seusite.com/webhook",
  "amount": 150.00,
  "external_id": "TXN123456789"
}

Parâmetros da Resposta

Possíveis Erros

Realizar Pagamento PIX

Endpoint para realizar um pagamento PIX para uma chave PIX específica.

Headers

Parâmetros do Body (JSON)

Exemplo de Requisição

POST /v2/pix/payment HTTP/1.1
Host: api.flashpix.cloud
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "amount": 250.00,
  "description": "Pagamento de fornecedor",
  "creditParty": {
    "name": "Maria Santos",
    "keyType": "CPF",
    "key": "98765432100"
  }
}

Exemplo com cURL

curl -X POST https://api.flashpix.cloud/v2/pix/payment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "description": "Pagamento de fornecedor",
    "creditParty": {
      "name": "Maria Santos",
      "keyType": "CPF",
      "key": "98765432100"
    }
  }'

Resposta de Sucesso (200 OK)

Em caso de sucesso, o endpoint retorna status 200 sem corpo na resposta. O saldo do usuário é automaticamente debitado e a transação é registrada no banco de dados.

Possíveis Erros

⚠️ Códigos de Erro

A API utiliza códigos de status HTTP padrão para indicar sucesso ou falha das requisições.

Códigos de Sucesso

Códigos de Erro do Cliente

Códigos de Erro do Servidor

Formato de Resposta de Erro

Quando ocorre um erro, a API retorna um objeto JSON com a seguinte estrutura:

{
  "statusCode": 400,
  "message": "Descrição do erro",
  "errorDetails": {
    // Detalhes adicionais quando disponível
  }
}

Exemplos de Erros Comuns

Token Expirado

{
  "message": "Token inválido ou expirado."
}

Credenciais Inválidas

{
  "statusCode": 404,
  "message": "Credenciais inválidas."
}

Saldo Insuficiente

{
  "message": "Saldo insuficiente."
}

External ID Duplicado

{
  "message": "O external_id já está em uso em outra transação."
}

🔔 Webhooks

A API envia notificações via webhook para informar sobre mudanças no status das transações.

Configuração

Ao criar um QR Code PIX, você deve fornecer uma URL no campo postbackUrl. Esta URL receberá notificações POST quando o status da transação mudar.

Formato da Notificação

As notificações são enviadas via POST com Content-Type application/json:

{
  "transactionId": "e76e996f57849498d0ddm4ebrz4y5g55",
  "external_id": "TXN123456789",
  "status": "COMPLETED",
  "amount": 150.00,
  "timestamp": "2024-01-15T10:30:00Z"
}

Status Possíveis

🔒 Segurança

Boas Práticas

• ✅ Nunca exponha suas credenciais (client_id e client_secret) no frontend
• ✅ Armazene tokens de forma segura e nunca os compartilhe
• ✅ Use HTTPS em produção para todas as requisições
• ✅ Implemente rate limiting para prevenir abuso
• ✅ Valide e sanitize todos os dados de entrada
• ✅ Monitore logs de acesso e transações suspeitas
• ✅ Mantenha as dependências atualizadas
• ✅ Configure webhooks com URLs HTTPS válidas
• ✅ Implemente retry logic para webhooks falhados

📞 Suporte

Para dúvidas, problemas ou sugestões sobre a API:

• 📧 Email: suporte@flashpix.cloud
• 📱 Telefone: (11) 1234-5678
• 💬 Chat: Disponível no painel administrativo