# Bloopi API — Documentação de Referência

## Visão Geral

A API da Bloopi é uma API REST com respostas em JSON. Use-a para integrar pagamentos, consultar transações, gerenciar produtos e assinaturas programaticamente.

**Base URL:** `https://api.bloopi.com.br/v1`

**Autenticação:** Bearer token — envie sua API Key no header `Authorization: Bearer sua_api_key`

**API Keys:** Geradas em app.bloopi.com.br > Configurações > API

---

## Autenticação

```bash
curl https://api.bloopi.com.br/v1/products \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"
```

---

## Payment Intents

### Criar Payment Intent

Cria uma intenção de pagamento para processar uma cobrança.

```
POST /v1/payment-intents
```

**Body:**
```json
{
  "amount": 9700,
  "currency": "BRL",
  "payment_method": "credit_card",
  "customer_email": "comprador@email.com",
  "customer_name": "Nome do Comprador",
  "customer_document": "12345678901",
  "installments": 3,
  "description": "Curso de Marketing Digital",
  "metadata": {
    "product_id": "prod_abc123",
    "external_id": "pedido_789"
  }
}
```

**Campos obrigatórios:**
- `amount` — valor em centavos (ex: 9700 = R$ 97,00)
- `currency` — moeda (ex: "BRL")
- `payment_method` — "credit_card", "pix" ou "boleto"

**Resposta:**
```json
{
  "id": "pi_abc123xyz",
  "status": "requires_payment_method",
  "amount": 9700,
  "currency": "BRL",
  "client_secret": "pi_abc123xyz_secret_...",
  "created_at": "2026-03-14T21:00:00Z"
}
```

### Consultar Payment Intent

```
GET /v1/payment-intents/{id}
```

**Resposta:**
```json
{
  "id": "pi_abc123xyz",
  "status": "succeeded",
  "amount": 9700,
  "currency": "BRL",
  "payment_method": "credit_card",
  "customer_email": "comprador@email.com",
  "created_at": "2026-03-14T21:00:00Z",
  "paid_at": "2026-03-14T21:05:00Z"
}
```

**Status possíveis:**
- `requires_payment_method` — aguardando método de pagamento
- `requires_confirmation` — aguardando confirmação
- `processing` — em processamento
- `succeeded` — pagamento aprovado
- `failed` — pagamento recusado
- `canceled` — cancelado

### Listar Payment Intents

```
GET /v1/payment-intents?limit=20&status=succeeded
```

**Parâmetros de query:**
- `limit` — número de resultados (padrão: 20, máximo: 100)
- `status` — filtrar por status
- `from` — data inicial (ISO 8601)
- `to` — data final (ISO 8601)
- `customer_email` — filtrar por email

---

## Transações

### Listar Transações

```
GET /v1/transactions
```

**Resposta:**
```json
{
  "data": [
    {
      "id": "txn_abc123",
      "payment_intent_id": "pi_abc123xyz",
      "amount": 9700,
      "currency": "BRL",
      "status": "succeeded",
      "payment_method": "credit_card",
      "customer_name": "Nome do Comprador",
      "customer_email": "comprador@email.com",
      "created_at": "2026-03-14T21:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}
```

### Consultar Transação

```
GET /v1/transactions/{id}
```

---

## Produtos

### Listar Produtos

```
GET /v1/products
```

**Resposta:**
```json
{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Curso de Marketing Digital",
      "type": "one_time",
      "active": true,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

### Consultar Produto

```
GET /v1/products/{id}
```

### Criar Produto

```
POST /v1/products
```

**Body:**
```json
{
  "name": "Curso de Marketing Digital",
  "description": "Aprenda marketing digital do zero",
  "type": "one_time"
}
```

---

## Preços

### Criar Preço

```
POST /v1/prices
```

**Body:**
```json
{
  "product_id": "prod_abc123",
  "amount": 9700,
  "currency": "BRL",
  "type": "one_time"
}
```

Para assinatura recorrente:
```json
{
  "product_id": "prod_abc123",
  "amount": 9700,
  "currency": "BRL",
  "type": "recurring",
  "interval": "monthly",
  "interval_count": 1
}
```

**Intervalos disponíveis:** `daily`, `weekly`, `monthly`, `yearly`

---

## Assinaturas

### Listar Assinaturas

```
GET /v1/subscriptions
```

**Parâmetros:**
- `status` — "active", "past_due", "canceled", "paused"
- `product_id` — filtrar por produto

### Consultar Assinatura

```
GET /v1/subscriptions/{id}
```

### Cancelar Assinatura

```
POST /v1/subscriptions/{id}/cancel
```

**Body:**
```json
{
  "cancel_at_period_end": true
}
```

- `cancel_at_period_end: true` — acesso mantido até fim do período pago
- `cancel_at_period_end: false` — cancelamento imediato

### Pausar Assinatura

```
POST /v1/subscriptions/{id}/pause
```

### Reativar Assinatura

```
POST /v1/subscriptions/{id}/resume
```

---

## Clientes

### Listar Clientes

```
GET /v1/customers
```

### Consultar Cliente

```
GET /v1/customers/{id}
```

### Criar Cliente

```
POST /v1/customers
```

**Body:**
```json
{
  "name": "Nome do Cliente",
  "email": "cliente@email.com",
  "document": "12345678901",
  "phone": "11999999999"
}
```

---

## Reembolsos

### Criar Reembolso

```
POST /v1/refunds
```

**Body:**
```json
{
  "charge_id": "ch_abc123",
  "amount": 9700,
  "reason": "requested_by_customer"
}
```

**Razões disponíveis:**
- `requested_by_customer` — solicitado pelo cliente
- `duplicate` — cobrança duplicada
- `fraudulent` — suspeita de fraude

---

## Webhooks

### Estrutura do Evento

Todos os eventos enviados via webhook seguem esta estrutura:

```json
{
  "id": "evt_abc123",
  "type": "payment.approved",
  "created_at": "2026-03-14T21:05:00Z",
  "data": {
    "object": { ... }
  }
}
```

### Eventos Disponíveis

| Evento | Descrição |
|--------|-----------|
| `payment.approved` | Pagamento aprovado |
| `payment.declined` | Pagamento recusado |
| `payment.refunded` | Pagamento estornado |
| `subscription.created` | Nova assinatura criada |
| `subscription.renewed` | Assinatura renovada |
| `subscription.canceled` | Assinatura cancelada |
| `subscription.past_due` | Cobrança de renovação falhou |
| `subscription.paused` | Assinatura pausada |

### Verificação de Assinatura

Cada webhook inclui o header `X-Bloopi-Signature` com HMAC-SHA256 do payload assinado com seu webhook secret.

```python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

---

## Códigos de Resposta HTTP

| Código | Significado |
|--------|-------------|
| 200 | Sucesso |
| 201 | Criado com sucesso |
| 400 | Requisição inválida (verifique o body) |
| 401 | Não autorizado (API key inválida) |
| 404 | Recurso não encontrado |
| 422 | Erro de validação |
| 429 | Rate limit atingido |
| 500 | Erro interno do servidor |

---

## Rate Limiting

- 100 requisições por minuto por API key
- Headers de resposta incluem `X-RateLimit-Remaining` e `X-RateLimit-Reset`
- Em caso de rate limit, aguarde antes de tentar novamente

---

## Erros

Respostas de erro seguem este formato:

```json
{
  "error": {
    "code": "invalid_amount",
    "message": "O valor deve ser um inteiro positivo em centavos",
    "param": "amount"
  }
}
```

---

## Links

- Dashboard: https://app.bloopi.com.br
- Gerar API Key: https://app.bloopi.com.br/settings/api
- Suporte: suporte@bloopi.com.br
- Documentação para LLMs: https://ai.bloopi.com.br/pt-BR