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

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

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...'
  }
});

Customers

O recurso Customer representa um cliente do seu sistema que será cobrado.

POST /integration/customers Criar um novo customer ▼

Body Parameters

name
string
 Required
Nome completo do cliente.
email
string
 Required
E-mail do cliente (deve ser único).
document
string
 Required
CPF ou CNPJ do cliente.
phone
string
 Optional
Telefone do cliente (e.g., +5511999999999).
externalReference
string
 Optional
ID do cliente no seu sistema interno.
Exemplo de Resposta (201 Created)
{
  "id": "uuid",
  "name": "João Silva",
  "email": "joao@example.com",
  "document": "12345678900",
  "createdAt": "2023-10-27T10:00:00.000Z"
}
GET /integration/customers Listar todos os customers ▼

Retorna uma lista de todos os customers associados à sua conta (paginados).

Exemplo de Resposta (200 OK)
[
  {
    "id": "uuid",
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "createdAt": "2023-10-27T10:00:00.000Z"
  }
]

Plans

Planos definem o preço base, a frequência de cobrança e opções de trial para assinaturas.

POST /integration/plans Criar um novo plano ▼

Body Parameters

name
string
 Required
Nome do plano (e.g., "Plano Pro").
amountCents
number
 Required
Valor em centavos (e.g., 9900 para R$ 99,00).
interval
enum
 Required
Intervalo de cobrança: MONTHLY, YEARLY, WEEKLY.
trialDays
number
 Optional
Dias grátis de teste antes da primeira cobrança. Padrão: 0.
Exemplo de Resposta (201 Created)
{
  "id": "uuid",
  "name": "Plano Pro",
  "amountCents": 9900,
  "interval": "MONTHLY",
  "trialDays": 0,
  "createdAt": "2023-10-27T10:00:00.000Z"
}

Subscriptions

Assinaturas conectam um Customer a um Plan, efetuando cobranças recorrentes usando o cartão de crédito fornecido.

Segurança de Cartões: O número do cartão é enviado "limpo" no request de criação e imediatamente criptografado usando AES-256-GCM em nosso backend antes de ser armazenado. A Fleeky Go se responsabiliza pela comunicação segura com o processador de pagamentos.
POST /integration/subscriptions Criar uma nova assinatura ▼

Body Parameters

customerId
string
 Required
ID do Customer previamente criado.
planId
string
 Required
ID do Plan.
cardNumber
string
 Required
Número do cartão sem espaços (e.g., "4111111111111111").
cardExpMonth
string
 Required
Mês de expiração (e.g., "12").
cardExpYear
string
 Required
Ano de expiração com 4 dígitos (e.g., "2030").
cardCvv
string
 Required
Código de segurança CVV.
cardHolderName
string
 Required
Nome impresso no cartão.
Exemplo de Resposta (201 Created)
{
  "id": "uuid",
  "customerId": "uuid",
  "planId": "uuid",
  "status": "ACTIVE",
  "currentPeriodStart": "2023-10-27T10:00:00.000Z",
  "currentPeriodEnd": "2023-11-27T10:00:00.000Z",
  "createdAt": "2023-10-27T10:00:00.000Z"
}

Ciclo de Vida (Lifecycle)

TRIALING
→
ACTIVE
→
PAST_DUE
→
CANCELED / EXPIRED

Se a cobrança de renovação falhar, a assinatura entra em PAST_DUE e tentaremos cobrar novamente (backoff exponencial: 4h, 8h, 16h).

Pagamentos Avulsos (Checkout Transparente)

Venda produtos cadastrados na sua conta com pagamentos únicos via Cartão de Crédito, PIX ou Boleto.

Criar um Pagamento

Processa o pagamento de um produto com o valor exato configurado no seu banco de dados. Lembre-se sempre de enviar o seu header Authorization: Bearer <sua-chave>.

POST /integration/payments Processar pagamento avulso ▼

1. Pagamento com PIX

curl -X POST \
  https://beta.api.go.fleeky.com.br/api/v1/integration/payments \
  -H "Authorization: Bearer fgo_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "description": "Camiseta Preta M",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678909"
    },
    "paymentMethod": "PIX"
  }'

const response = await fetch('https://beta.api.go.fleeky.com.br/api/v1/integration/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fgo_live_1234567890abcdef...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 9900,
    description: "Camiseta Preta M",
    customer: {
      name: "João Silva",
      email: "joao@example.com",
      document: "12345678909"
    },
    paymentMethod: "PIX"
  })
});

2. Pagamento com Cartão de Crédito

curl -X POST \
  https://beta.api.go.fleeky.com.br/api/v1/integration/payments \
  -H "Authorization: Bearer fgo_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "description": "Camiseta Preta M",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678909"
    },
    "billingAddress": {
      "street": "Rua Exemplo",
      "number": "123",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01000-000"
    },
    "paymentMethod": "CREDIT_CARD",
    "installments": 1,
    "cardNumber": "4111111111111111",
    "cardExpMonth": "12",
    "cardExpYear": "2030",
    "cardCvv": "123",
    "cardHolderName": "JOHN DOE"
  }'

const response = await fetch('https://beta.api.go.fleeky.com.br/api/v1/integration/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fgo_live_1234567890abcdef...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 9900,
    description: "Camiseta Preta M",
    customer: {
      name: "João Silva",
      email: "joao@example.com",
      document: "12345678909"
    },
    billingAddress: {
      street: "Rua Exemplo",
      number: "123",
      neighborhood: "Centro",
      city: "São Paulo",
      state: "SP",
      zipCode: "01000-000"
    },
    paymentMethod: "CREDIT_CARD",
    installments: 1,
    cardNumber: "4111111111111111",
    cardExpMonth: "12",
    cardExpYear: "2030",
    cardCvv: "123",
    cardHolderName: "JOHN DOE"
  })
});

3. Pagamento com Boleto

curl -X POST \
  https://beta.api.go.fleeky.com.br/api/v1/integration/payments \
  -H "Authorization: Bearer fgo_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "description": "Camiseta Preta M",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678909"
    },
    "paymentMethod": "BOLETO"
  }'

const response = await fetch('https://beta.api.go.fleeky.com.br/api/v1/integration/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fgo_live_1234567890abcdef...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 9900,
    description: "Camiseta Preta M",
    customer: {
      name: "João Silva",
      email: "joao@example.com",
      document: "12345678909"
    },
    paymentMethod: "BOLETO"
  })
});
Exemplo de Resposta (201 Created) - PIX
{
  "orderId": "uuid",
  "orderNumber": "M2M12345",
  "transactionId": "uuid",
  "amount": 99.90,
  "status": "pending",
  "paymentMethod": "PIX",
  "acquirerResponse": {
    "qrCode": "000201...",
    "qrCodeImageUrl": "data:image/png;base64,...",
    "expiresAt": "2023-11-20T10:30:00Z"
  }
}

Webhooks

A Fleeky Go notifica seu sistema ativamente sobre eventos do motor de faturamento.

Configure a URL de webhooks no painel (Desenvolvedores > Webhooks). Você receberá um POST contendo um payload JSON com a propriedade event.

Segurança e Assinaturas: Ao criar um webhook, você receberá um Webhook Secret (iniciado com whsec_). Use esta chave para validar a autenticidade da requisição validando a assinatura enviada no header Fleeky-Signature. O payload bruto deve ser assinado usando HMAC-SHA256 e o resultado comparado com o valor do header.
invoice.paid Uma cobrança foi processada e aprovada pelo adquirente.
invoice.payment_failed Uma tentativa de cobrança falhou. Inclui `retry_count` e motivo.
subscription.expired O limite de retentativas foi alcançado.
subscription.canceled A assinatura foi cancelada via API.

Exemplo de Payload

{
  "event": "invoice.paid",
  "timestamp": "2023-10-27T10:00:00.000Z",
  "data": {
    "subscriptionId": "uuid",
    "customerId": "uuid",
    "amountCents": 9900,
    "transaction_id": "ORDE_12345678"
  }
}