Aparência

📖 Referência Completa de Endpoints ​

Esta seção fornece a especificação técnica detalhada para os principais endpoints de negócio da FastGivr API.

A URL base para todas as requisições é:

  • Produção: https://api.fastgivr.com.br/api/v1
  • Sandbox: https://api-sandbox.fastgivr.com.br/api/v1

1. POST /access/account/get-token (Autenticação) ​

Descrição e Regras ​

Gera um token JWT Bearer temporário que expira estritamente em 10 minutos. Este endpoint é o ponto de partida obrigatório para qualquer fluxo de integração programática.

  • Método HTTP: POST
  • Rota: /access/account/get-token
  • Autenticação: Não requer cabeçalho de autenticação (usa Chave Secreta no corpo).
  • Permissões Necessárias: Nenhuma (Endpoint Público de Acesso).
  • Regras de Validação:
    • email deve ser um e-mail válido cadastrado no portal.
    • token deve corresponder à chave secreta ativa (sec_test_... ou sec_prod_...).

Parâmetros da Requisição (Body JSON) ​

CampoTipoObrigatórioDescrição
emailstringSimE-mail do proprietário da conta ou integrador.
tokenstringSimChave Secreta da API (Secret Key).

Código de Exemplo (Multi-Linguagem) ​

💻 cURL ​

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

💻 JavaScript (Fetch) ​

javascript
const response = await fetch('https://api.fastgivr.com.br/api/v1/access/account/get-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'integrador@empresa.com',
    token: 'sec_prod_xyz123'
  })
});
const data = await response.json();

💻 TypeScript ​

typescript
import axios from 'axios';

interface AuthResponse {
  success: boolean;
  data: {
    token: string;
    token_type: string;
    expires_at: string;
  };
  message: string;
}

const getAuthToken = async (): Promise<string> => {
  const res = await axios.post<AuthResponse>('https://api.fastgivr.com.br/api/v1/access/account/get-token', {
    email: 'integrador@empresa.com',
    token: 'sec_prod_xyz123'
  });
  return res.data.data.token;
};

💻 Python ​

python
import requests

payload = {
    "email": "integrador@empresa.com",
    "token": "sec_prod_xyz123"
}
response = requests.post("https://api.fastgivr.com.br/api/v1/access/account/get-token", json=payload)
token = response.json()["data"]["token"]

💻 PHP ​

php
<?php
$ch = curl_init("https://api.fastgivr.com.br/api/v1/access/account/get-token");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        "email" => "integrador@empresa.com",
        "token" => "sec_prod_xyz123"
    ]),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"]
]);
$res = json_decode(curl_exec($ch), true);
$token = $res['data']['token'];
?>

🤖 Markdown AI ​

markdown
# Solicitação de Token com Prompt
Use um agente inteligente para formatar a chamada de autenticação da FastGivr:
> "Gere uma requisição HTTP POST para obter o token do e-mail 'integrador@empresa.com' usando o token secreto contido na variável SEC_KEY."

Respostas da API ​

sucesso (200 OK) ​

json
{
  "success": true,
  "data": {
    "token": "2|apiKeyToken...",
    "token_type": "Bearer",
    "expires_at": "2026-05-18T15:20:00+00:00"
  },
  "message": "Autenticado com sucesso"
}

erro (401 Unauthorized) ​

json
{
  "success": false,
  "message": "Credenciais de API inválidas."
}

2. POST /quickpay/pix/charge (Criar Cobrança Pix) ​

Descrição e Regras ​

Gera um pagamento Pix imediato contendo a chave copia-e-cola e a imagem QR Code codificada em base64. A liquidação é instantânea na conta FastGivr.

  • Método HTTP: POST
  • Rota: /quickpay/pix/charge
  • Autenticação: Sim (Authorization: Bearer <TOKEN>).
  • Permissões Necessárias: charges.create
  • Regras de Validação:
    • amount deve ser um decimal positivo (mínimo: R$ 0,50).
    • payer_document deve ser um CPF (11 dígitos) ou CNPJ (14 dígitos) válido.

Parâmetros da Requisição (Body JSON) ​

CampoTipoObrigatórioDescrição
amountdecimalSimValor cobrado em reais (ex: 150.00).
payer_namestringSimNome completo do comprador.
payer_documentstringSimCPF/CNPJ do comprador (apenas números).

Código de Exemplo (Multi-Linguagem) ​

💻 cURL ​

bash
curl -X POST https://api.fastgivr.com.br/api/v1/quickpay/pix/charge \
     -H "Authorization: Bearer 2|apiKeyToken..." \
     -H "Content-Type: application/json" \
     -d '{
           "amount": 150.00,
           "payer_name": "João da Silva",
           "payer_document": "12345678909"
         }'

💻 JavaScript ​

javascript
const response = await fetch('https://api.fastgivr.com.br/api/v1/quickpay/pix/charge', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer 2|apiKeyToken...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 150.00,
    payer_name: 'João da Silva',
    payer_document: '12345678909'
  })
});
const chargeData = await response.json();

💻 TypeScript ​

typescript
import axios from 'axios';

interface PixChargeResponse {
  success: boolean;
  data: {
    txid: string;
    pix_copia_e_cola: string;
    qrcode_image_base64: string;
    amount: number;
  };
}

const createPixCharge = async (token: string, amount: number, name: string, doc: string) => {
  const res = await axios.post<PixChargeResponse>(
    'https://api.fastgivr.com.br/api/v1/quickpay/pix/charge',
    { amount, payer_name: name, payer_document: doc },
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return res.data;
};

💻 Python ​

python
import requests

headers = {
    "Authorization": "Bearer 2|apiKeyToken...",
    "Content-Type": "application/json"
}
payload = {
    "amount": 150.00,
    "payer_name": "João da Silva",
    "payer_document": "12345678909"
}
response = requests.post("https://api.fastgivr.com.br/api/v1/quickpay/pix/charge", json=payload, headers=headers)
print(response.json())

💻 PHP ​

php
<?php
$ch = curl_init("https://api.fastgivr.com.br/api/v1/quickpay/pix/charge");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 150.00,
        "payer_name" => "João da Silva",
        "payer_document" => "12345678909"
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer 2|apiKeyToken...",
        "Content-Type: application/json"
    ]
]);
$res = curl_exec($ch);
?>

🤖 Markdown AI ​

markdown
# prompt para IA gerar o Pix
> "Gere um pagamento no Pix da FastGivr de R$ 150 para o comprador João da Silva, CPF 12345678909."

Respostas da API ​

sucesso (201 Created) ​

json
{
  "success": true,
  "data": {
    "txid": "pix_abc123xyz...",
    "pix_copia_e_cola": "00020126580014br.gov.bcb.pix...",
    "qrcode_image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "amount": 150.00,
    "status": "pending"
  },
  "message": "Cobrança Pix criada com sucesso."
}

erro (422 Unprocessable Entity) ​

json
{
  "success": false,
  "message": "O CPF informado é inválido.",
  "errors": {
    "payer_document": ["O documento deve ser um CPF ou CNPJ válido."]
  }
}

3. POST /quickpay/withdrawals (Solicitar Saque PIX) ​

Descrição e Regras ​

Transfere o saldo de recebíveis disponível na FastGivr de forma instantânea para uma conta externa bancária usando chaves PIX.

  • Método HTTP: POST
  • Rota: /quickpay/withdrawals
  • Autenticação: Sim (Authorization: Bearer <TOKEN>).
  • Permissões Necessárias: withdrawals.create
  • Regras de Validação:
    • amount deve ser igual ou inferior ao saldo disponível contábil em tempo real.
    • pix_key_type deve pertencer à lista: CPF, CNPJ, EMAIL, PHONE, EVP (chave aleatória).

Parâmetros da Requisição (Body JSON) ​

CampoTipoObrigatórioDescrição
amountdecimalSimValor do saque em reais (ex: 1250.00).
pix_key_typestringSimTipo de Chave Pix (CPF, CNPJ, EMAIL, PHONE, EVP).
pix_keystringSimValor literal da chave Pix de destino.

Código de Exemplo (Multi-Linguagem) ​

💻 cURL ​

bash
curl -X POST https://api.fastgivr.com.br/api/v1/quickpay/withdrawals \
     -H "Authorization: Bearer 2|apiKeyToken..." \
     -H "Content-Type: application/json" \
     -d '{
           "amount": 1250.00,
           "pix_key_type": "EMAIL",
           "pix_key": "financeiro@loja.com"
         }'

💻 JavaScript ​

javascript
const response = await fetch('https://api.fastgivr.com.br/api/v1/quickpay/withdrawals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer 2|apiKeyToken...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1250.00,
    pix_key_type: 'EMAIL',
    pix_key: 'financeiro@loja.com'
  })
});
const withdrawalData = await response.json();

💻 TypeScript ​

typescript
import axios from 'axios';

interface WithdrawalResponse {
  success: boolean;
  data: {
    id: string;
    amount: number;
    pix_key: string;
    status: string;
  };
}

const requestWithdrawal = async (token: string, amount: number, keyType: string, key: string) => {
  const res = await axios.post<WithdrawalResponse>(
    'https://api.fastgivr.com.br/api/v1/quickpay/withdrawals',
    { amount, pix_key_type: keyType, pix_key: key },
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return res.data;
};

💻 Python ​

python
import requests

headers = {
    "Authorization": "Bearer 2|apiKeyToken...",
    "Content-Type": "application/json"
}
payload = {
    "amount": 1250.00,
    "pix_key_type": "EMAIL",
    "pix_key": "financeiro@loja.com"
}
response = requests.post("https://api.fastgivr.com.br/api/v1/quickpay/withdrawals", json=payload, headers=headers)
print(response.json())

💻 PHP ​

php
<?php
$ch = curl_init("https://api.fastgivr.com.br/api/v1/quickpay/withdrawals");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 1250.00,
        "pix_key_type" => "EMAIL",
        "pix_key" => "financeiro@loja.com"
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer 2|apiKeyToken...",
        "Content-Type: application/json"
    ]
]);
$res = curl_exec($ch);
?>

🤖 Markdown AI ​

markdown
# prompt para IA solicitar o saque
> "Execute uma transferência Pix da FastGivr de R$ 1.250 para a chave Pix de e-mail 'financeiro@loja.com'."

Respostas da API ​

sucesso (201 Created) ​

json
{
  "success": true,
  "data": {
    "id": "wtd_987654321",
    "amount": 1250.00,
    "pix_key_type": "EMAIL",
    "pix_key": "financeiro@loja.com",
    "status": "pending",
    "created_at": "2026-05-18T15:20:00+00:00"
  },
  "message": "Solicitação de saque enviada com sucesso."
}

erro (400 Bad Request) ​

json
{
  "success": false,
  "message": "Saldo insuficiente para saque. Saldo disponível: R$ 800,00."
}

FastGivr API Documentation

Copyright © 2026 FASTGIVR. Todos os direitos reservados.