B2B Billing API

A infraestrutura completa para faturar, gerenciar assinaturas e reter clientes.

Base URL: https://beta.api.go.fleeky.com.br/api/v1

Clique para copiar a URL base

Ambientes

A Fleeky Go oferece dois ambientes separados. Use o Staging (Sandbox) para desenvolvimento e testes, e o Produção para transações reais.

⠀	🧪 Staging (Sandbox)	🚀 Produção
Base URL	`https://staging.api.go.fleeky.com.br/api/v1`	`https://beta.api.go.fleeky.com.br/api/v1`
Painel Admin	`https://staging.admin.go.fleeky.com.br`	`https://beta.admin.go.fleeky.com.br`
App (Dashboard)	`https://staging.app.go.fleeky.com.br`	`https://beta.app.go.fleeky.com.br`
Checkout (Pay)	`https://staging.pay.fleeky.com.br`	`https://beta.pay.fleeky.com.br`
Prefixo da API Key	`fgo_live_`	`fgo_live_`
Dados	Banco de dados separado (staging)	Banco de dados de produção
Transações	Sandbox (dados de teste)	Reais

🧪 Ambiente Sandbox: O Staging é um ambiente de sandbox para desenvolvimento e testes. Nenhuma transação real é processada. Use dados de teste (CPFs fictícios válidos, cartões de teste).

💡 Recomendação: Desenvolva e teste sua integração apontando para staging.api.go.fleeky.com.br. Após validar, basta trocar a Base URL para beta.api.go.fleeky.com.br — os endpoints e formatos são idênticos.

Autenticação

A Fleeky Go usa API Keys para autenticar requisições M2M (Machine-to-Machine).

Como obter sua chave: Acesse o painel administrativo da Fleeky Go, vá em Desenvolvedores > API Keys e clique em "Gerar Nova Chave". A chave começa com fgo_live_. Guarde-a de forma segura!

Todas as requisições devem incluir o cabeçalho Authorization com o formato Bearer <sua-chave>.

curl -X GET \
  https://beta.api.go.fleeky.com.br/api/v1/integration/customers \
  -H "Authorization: Bearer fgo_live_1234567890abcdef..."

const response = await fetch('https://beta.api.go.fleeky.com.br/api/v1/integration/customers', {
  headers: {
    'Authorization': 'Bearer fgo_live_1234567890abcdef...'
  }
});

Webhooks

Webhooks enviam notificações HTTP POST em tempo real quando eventos ocorrem na sua conta. Configure endpoints HTTPS e receba atualizações instantâneas.

Configuração: Acesse Desenvolvedores → Webhooks no painel para criar endpoints. Cada endpoint recebe um Webhook Secret (iniciado com whsec_) para validação de assinatura.

Catálogo de Eventos

Todos os eventos seguem o formato recurso.ação. Inscreva-se em eventos específicos ou receba todos com o wildcard *.

Pagamentos

payment.created Disparado quando um pagamento é criado.

payment.approved Disparado quando um pagamento é aprovado pelo adquirente.

payment.failed Disparado quando um pagamento falha.

payment.declined Disparado quando um pagamento é recusado.

payment.cancelled Disparado quando um pagamento é cancelado.

payment.refunded Disparado quando um estorno é processado.

payment.pending Disparado quando um pagamento fica pendente (aguardando confirmação).

Pedidos

order.created Disparado quando um pedido é criado.

order.paid Disparado quando um pedido é pago integralmente.

order.canceled Disparado quando um pedido é cancelado.

Assinaturas

subscription.created Disparado quando uma assinatura é criada.

subscription.renewed Disparado quando uma cobrança recorrente é renovada.

subscription.canceled Disparado quando uma assinatura é cancelada.

subscription.overdue Disparado quando uma assinatura fica inadimplente.

Sistema

webhook.test Evento de teste para validar a integração. Envie via painel em Desenvolvedores → Webhooks → Testar.

Exemplo de Payload

Todos os webhooks enviam um POST com o seguinte formato JSON:

{
  "event": "payment.approved",
  "timestamp": "2026-06-10T19:00:00.000Z",
  "data": {
    "id": "tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 15990,
    "currency": "BRL",
    "status": "approved",
    "paymentMethod": "credit_card",
    "installments": 3,
    "customer": {
      "name": "João Silva",
      "email": "joao@empresa.com.br"
    },
    "metadata": {
      "orderId": "ORD-2026-1234"
    }
  }
}

          

O campo amount é sempre em centavos (15990 = R$ 159,90).

Verificando a Assinatura (HMAC-SHA256)

Cada webhook inclui o header Fleeky-Signature contendo uma assinatura HMAC-SHA256. Verifique para garantir autenticidade:

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// No seu endpoint:
app.post('/webhook', (req, res) => {
  const signature = req.headers['fleeky-signature'];
  const rawBody = JSON.stringify(req.body);

  if (!verifySignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Assinatura inválida');
  }

  // Processar evento...
  const { event, data } = req.body;
  console.log(`Evento recebido: ${event}`);

  // IMPORTANTE: Responda 200 rapidamente
  res.status(200).send('OK');
});

Segurança: Use crypto.timingSafeEqual para comparar assinaturas. Comparações com === são vulneráveis a ataques de timing.

Política de Retry

Se seu endpoint não responder com status 2xx em até 10 segundos, o webhook será reenviado automaticamente:

1ª tentativa	Imediata — envio original
2ª tentativa	~30 segundos — backoff exponencial
3ª tentativa	~60 segundos — backoff exponencial

Após 3 tentativas, o webhook é marcado como falho. Você pode re-enviar manualmente pelo painel (máx. 10/hora por endpoint).

Boas Práticas

Responda 200 rapidamente. Retorne 200 OK antes de processar. Use uma fila interna.
Implemente idempotência. Use o data.id para detectar duplicatas — o mesmo evento pode chegar mais de uma vez.
Verifique a assinatura. Sempre valide o header Fleeky-Signature.
Use HTTPS. Seu endpoint deve obrigatoriamente usar HTTPS.
Teste antes de produção. Use o botão "Testar" no painel para validar sua integração.