> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Acompanhe métricas de receita, assinaturas e clientes com o dashboard de analytics da Chargefy.

## Métricas Disponíveis

A Chargefy calcula e disponibiliza métricas essenciais para acompanhar a saúde financeira do seu negócio:

| Métrica | Descrição | Exemplo |
| - | - | - |
| **MRR** | Receita Recorrente Mensal — soma de todas as assinaturas ativas normalizadas para um mês | R\$ 45.000,00 |
| **ARR** | Receita Recorrente Anual — MRR multiplicado por 12 | R\$ 540.000,00 |
| **Churn Rate** | Taxa de cancelamento — percentual de assinaturas canceladas no período | 3,2% |
| **LTV** | Lifetime Value — receita média gerada por cliente ao longo do tempo | R\$ 1.250,00 |
| **Receita Total** | Soma de todos os pagamentos confirmados no período (recorrentes + únicos) | R\$ 89.500,00 |
| **Assinaturas Ativas** | Total de assinaturas com status `active` | 1.234 |
| **Novos Clientes** | Clientes criados no período selecionado | 87 |

> [!NOTE]
>
> As métricas são atualizadas a cada **15 minutos**. Para dados em tempo real, utilize a API de métricas diretamente.

## Dashboard de Analytics

O dashboard de analytics oferece uma visão consolidada do seu negócio diretamente no painel da Chargefy. Ele inclui:

* **Gráficos de evolução** do MRR e receita total ao longo do tempo
* **Indicadores resumidos** com variação percentual em relação ao período anterior
* **Tabela de assinaturas** com status, valor e data de renovação
* **Ranking de produtos** por receita gerada
* **Mapa de clientes** por estado/região

## Filtros e Período

Todas as métricas podem ser filtradas por:

### Período de datas

| Período | Descrição |
| - | - |
| Últimos 7 dias | Visão da última semana |
| Últimos 30 dias | Visão do último mês |
| Último trimestre | Últimos 3 meses |
| Último ano | Últimos 12 meses |
| Personalizado | Selecione data inicial e final |

### Filtros adicionais

| Filtro | Descrição |
| - | - |
| **Produto** | Filtre métricas por produto específico |
| **Método de pagamento** | PIX, Cartão de Crédito ou Boleto |
| **Status da assinatura** | Ativa, suspensa, cancelada, etc. |
| **Organização** | Para contas com múltiplas organizações |

```typescript theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

// Buscar métricas com filtros
const metrics = await chargefy.metrics.get({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
  product_id: "prod_xxx",
  payment_method: "pix",
});
```

## Métricas por Método de Pagamento

A Chargefy processa pagamentos utilizando três métodos. O dashboard apresenta a distribuição de receita por cada um:

### PIX

* **Confirmação instantânea** — pagamento confirmado em segundos
* Ideal para pagamentos únicos e checkout rápido
* Sem taxa de chargeback

### Cartão de Crédito

* **Cobranças recorrentes** — único método para assinaturas
* Suporte a parcelamento em pagamentos únicos
* Sujeito a chargebacks e disputas

### Boleto Bancário

* **Vencimento configurável** — prazo de 1 a 30 dias
* Conciliação automática após pagamento
* Taxa de conversão tipicamente menor que PIX e Cartão

```typescript theme={null}
// Buscar métricas agrupadas por método de pagamento
const metricsByPayment = await chargefy.metrics.get({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
  group_by: "payment_method",
});

// Resultado
// {
//   pix: { total_revenue: 3250000, transactions: 412 },
//   credit_card: { total_revenue: 5890000, transactions: 287 },
//   boleto: { total_revenue: 1120000, transactions: 98 }
// }
// Nota: valores em centavos (R$ 32.500,00 = 3250000)
```

> [!NOTE]
>
> Valores monetários retornados pela API são sempre em **centavos** (inteiros). Para exibir R\$ 49,90, a API retorna `4990`.

## API de Métricas

### Visão geral das métricas

```bash cURL theme={null}
curl -X GET "https://api.chargefy.io/api/v1/metrics?start_date=2026-01-01&end_date=2026-03-12" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"
```

```typescript SDK theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const metrics = await chargefy.metrics.get({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
});

console.log(metrics.mrr);               // 4500000 (R$ 45.000,00)
console.log(metrics.arr);               // 54000000 (R$ 540.000,00)
console.log(metrics.churn_rate);         // 3.2
console.log(metrics.ltv);               // 125000 (R$ 1.250,00)
console.log(metrics.total_revenue);      // 8950000 (R$ 89.500,00)
console.log(metrics.active_subscriptions); // 1234
console.log(metrics.new_customers);      // 87
```

### Resposta da API

```json theme={null}
{
  "mrr": 4500000,
  "arr": 54000000,
  "churn_rate": 3.2,
  "ltv": 125000,
  "total_revenue": 8950000,
  "active_subscriptions": 1234,
  "new_customers": 87,
  "period": {
    "start_date": "2026-01-01",
    "end_date": "2026-03-12"
  },
  "comparison": {
    "mrr_change": 5.4,
    "revenue_change": 12.1,
    "churn_change": -0.8
  }
}
```

### Métricas ao longo do tempo

Para obter a evolução das métricas em intervalos regulares:

```typescript theme={null}
const timeline = await chargefy.metrics.getTimeline({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
  interval: "month", // "day" | "week" | "month"
  metric: "mrr",
});

// Resultado
// {
//   data: [
//     { date: "2026-01-01", value: 4200000 },
//     { date: "2026-02-01", value: 4350000 },
//     { date: "2026-03-01", value: 4500000 }
//   ]
// }
```

### Métricas por produto

```typescript theme={null}
const productMetrics = await chargefy.metrics.get({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
  group_by: "product",
});

// Resultado agrupado por produto
// {
//   products: [
//     { product_id: "prod_xxx", name: "Plano Pro", mrr: 2800000, subscribers: 560 },
//     { product_id: "prod_yyy", name: "Plano Basic", mrr: 1700000, subscribers: 674 }
//   ]
// }
```

## Exportação de Dados

Você pode exportar os dados de analytics em formato CSV diretamente pelo dashboard ou via API.

### Via Dashboard

1. Acesse **Analytics** no menu lateral
2. Configure os filtros desejados (período, produto, método de pagamento)
3. Clique em **Exportar CSV**
4. O arquivo será gerado e baixado automaticamente

### Via API

```typescript theme={null}
const exportResult = await chargefy.metrics.export({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
  format: "csv",
  include: ["revenue", "subscriptions", "customers"],
});

// Retorna uma URL temporária para download
console.log(exportResult.download_url);
// https://api.chargefy.io/exports/abc123.csv
// URL válida por 1 hora
```

```bash cURL theme={null}
curl -X POST "https://api.chargefy.io/api/v1/metrics/export" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-01-01",
    "end_date": "2026-03-12",
    "format": "csv",
    "include": ["revenue", "subscriptions", "customers"]
  }'
```

```typescript SDK theme={null}
const exportResult = await chargefy.metrics.export({
  start_date: "2026-01-01",
  end_date: "2026-03-12",
  format: "csv",
  include: ["revenue", "subscriptions", "customers"],
});

// Download programático
const response = await fetch(exportResult.download_url);
const csv = await response.text();
```

> [!NOTE]
>
> Exportações com grandes volumes de dados são processadas de forma assíncrona. Utilize o webhook `export.completed` para ser notificado quando o arquivo estiver pronto.

## Escopos de API

| Escopo | Permissão |
| - | - |
| `metrics:read` | Consultar métricas e exportar dados |

***

> [card] [Produtos](https://scaleup-c34c4386.mintlify.site/features/products.md)
>
> Configure produtos e preços para acompanhar no analytics

> [card] [Assinaturas](https://scaleup-c34c4386.mintlify.site/features/subscriptions.md)
>
> Gerencie assinaturas recorrentes e monitore o churn

> [card] [Vendas](https://scaleup-c34c4386.mintlify.site/features/subscriptions.md)
>
> Visualize vendas e histórico de transações via assinaturas

> [card] [Webhooks](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/events.md)
>
> Receba notificações de eventos em tempo real


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.