> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pierre.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Expensive Categories

> Retorna as 3 categorias mais caras no período especificado. Por padrão, analisa os últimos 7 dias. Requer API key para autenticação e assinatura ativa.

<Note>
  Este endpoint retorna as 3 categorias de despesas mais caras em um período específico.
</Note>

## Descrição

O endpoint `GET /tools/api/get-expensive-categories` analisa suas transações e retorna um ranking das categorias onde você mais gastou. Por padrão, analisa os últimos 7 dias, mas você pode especificar o período desejado.

## Autenticação

Este endpoint requer autenticação via Bearer token.

<ParamField header="Authorization" type="string" required>
  Bearer token com a API key do usuário. Formato: `Bearer sk-your-api-key-here`
</ParamField>

## Parâmetros de Query

<ParamField query="startDate" type="string" required="false">
  Data inicial para análise no formato YYYY-MM-DD. Padrão: 7 dias atrás.
</ParamField>

<ParamField query="endDate" type="string" required="false">
  Data final para análise no formato YYYY-MM-DD. Padrão: hoje.
</ParamField>

<ParamField query="s" type="string" required="false">
  Parâmetro interno para indicar requisições via MCP. Use `s=s` para requisições MCP.
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "data": "1. Alimentação: R$ 450,00\n2. Transporte: R$ 320,50\n3. Lazer: R$ 180,00",
    "summary": {
      "totalCategories": 8,
      "top3Categories": [
        {
          "category": "Alimentação",
          "totalAmount": 450.00,
          "formattedAmount": "R$ 450,00"
        },
        {
          "category": "Transporte",
          "totalAmount": 320.50,
          "formattedAmount": "R$ 320,50"
        },
        {
          "category": "Lazer",
          "totalAmount": 180.00,
          "formattedAmount": "R$ 180,00"
        }
      ],
      "totalExpenses": 1250.75,
      "formattedTotalExpenses": "R$ 1.250,75"
    },
    "dateRange": {
      "startDate": "2024-11-20T00:00:00.000Z",
      "endDate": "2024-11-27T23:59:59.999Z"
    },
    "timestamp": "2024-11-27T16:45:00Z"
  }
  ```
</ResponseExample>

### Erro de Autenticação (401)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "Invalid or inactive API key",
    "message": "Please check your API key and try again",
    "type": "invalid_api_key"
  }
  ```
</ResponseExample>

## Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="data" type="string" required>
  Texto formatado com as top 3 categorias e valores (formato WhatsApp-friendly)
</ResponseField>

<ResponseField name="summary" type="object" required>
  Resumo detalhado da análise de gastos

  <Expandable title="Summary Object">
    <ResponseField name="totalCategories" type="number" required>
      Número total de categorias com gastos encontradas no período
    </ResponseField>

    <ResponseField name="top3Categories" type="array" required>
      Array com as 3 categorias mais caras

      <Expandable title="Category Object">
        <ResponseField name="category" type="string" required>
          Nome da categoria
        </ResponseField>

        <ResponseField name="totalAmount" type="number" required>
          Valor total gasto na categoria (número)
        </ResponseField>

        <ResponseField name="formattedAmount" type="string" required>
          Valor formatado em reais (string)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="totalExpenses" type="number" required>
      Valor total de despesas no período
    </ResponseField>

    <ResponseField name="formattedTotalExpenses" type="string" required>
      Total de despesas formatado em reais
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="dateRange" type="object" required>
  Período analisado

  <Expandable title="Date Range Object">
    <ResponseField name="startDate" type="string" required>
      Data/hora de início do período (ISO 8601)
    </ResponseField>

    <ResponseField name="endDate" type="string" required>
      Data/hora de fim do período (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  Timestamp da requisição em formato ISO 8601
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# Analisar últimos 7 dias (padrão)
curl -X GET 'https://www.pierre.finance/tools/api/get-expensive-categories' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Analisar período específico
curl -X GET 'https://www.pierre.finance/tools/api/get-expensive-categories?startDate=2024-11-01&endDate=2024-11-30' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Analisar último mês
curl -X GET 'https://www.pierre.finance/tools/api/get-expensive-categories?startDate=2024-10-01&endDate=2024-10-31' \
  -H 'Authorization: Bearer sk-your-api-key-here'
```

### JavaScript

```javascript theme={null}
const API_KEY = 'sk-your-api-key-here';
const BASE_URL = 'https://www.pierre.finance/tools/api';

async function getExpensiveCategories(startDate = null, endDate = null) {
  const params = new URLSearchParams();
  if (startDate) params.append('startDate', startDate);
  if (endDate) params.append('endDate', endDate);
  
  const url = `${BASE_URL}/get-expensive-categories${params.toString() ? '?' + params : ''}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplos de uso
getExpensiveCategories(); // Últimos 7 dias
getExpensiveCategories('2024-11-01', '2024-11-30'); // Novembro
getExpensiveCategories('2024-10-01', '2024-10-31'); // Outubro
```

### Python

```python theme={null}
import requests
from datetime import datetime, timedelta

API_KEY = 'sk-your-api-key-here'
BASE_URL = 'https://www.pierre.finance/tools/api'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def get_expensive_categories(start_date=None, end_date=None):
    params = {}
    if start_date:
        params['startDate'] = start_date
    if end_date:
        params['endDate'] = end_date
    
    response = requests.get(f'{BASE_URL}/get-expensive-categories',
                          headers=headers, params=params)
    return response.json()

# Exemplos de uso
categories = get_expensive_categories()  # Últimos 7 dias

# Mês atual
today = datetime.now()
first_day = today.replace(day=1).strftime('%Y-%m-%d')
categories_month = get_expensive_categories(first_day, today.strftime('%Y-%m-%d'))

# Novembro 2024
categories_nov = get_expensive_categories('2024-11-01', '2024-11-30')
```

## Códigos de Status

* `200`: Sucesso - Categorias retornadas
* `401`: Erro de autenticação ou assinatura
* `500`: Erro interno do servidor

## Casos de Uso

### Análise de Gastos Mensais

Identifique suas maiores despesas do mês para planejar melhor o orçamento do próximo mês.

### Comparação de Períodos

Compare os gastos de diferentes meses para identificar tendências e padrões de consumo.

### Controle de Orçamento

Use junto com os endpoints de spending limits para criar alertas nas categorias onde você mais gasta.

<Note>
  Este endpoint considera apenas transações de débito (despesas). Transações de crédito (receitas) e transferências entre contas próprias não são incluídas na análise.
</Note>

<Tip>
  Combine este endpoint com `create-spending-limit` para criar alertas automáticos nas categorias onde você mais gasta. Por exemplo, se Alimentação é sua categoria #1, crie um limite mensal para controlar melhor esses gastos.
</Tip>

## Categorias Comuns

As categorias são geradas automaticamente pela categorização inteligente de transações. Algumas categorias comuns incluem:

* **Alimentação**: Restaurantes, supermercados, delivery
* **Transporte**: Uber, gasolina, manutenção veicular
* **Lazer**: Cinema, streaming, viagens
* **Saúde**: Farmácia, consultas médicas, academia
* **Moradia**: Aluguel, condomínio, contas residenciais
* **Educação**: Cursos, livros, materiais
* **Vestuário**: Roupas, calçados, acessórios
* **Outros**: Transações não categorizadas


## OpenAPI

````yaml GET /tools/api/get-expensive-categories
openapi: 3.1.0
info:
  title: Pierre Finance API
  description: >-
    API para acessar dados financeiros do Pierre Finance, incluindo contas,
    transações, parcelas e sincronização.
  version: v1.0.0
servers:
  - url: https://www.pierre.finance
security: []
tags:
  - name: Authentication
    description: API key management and authentication
  - name: Accounts
    description: Financial accounts management
  - name: Transactions
    description: Financial transactions
  - name: Installments
    description: Credit card installments and purchases
  - name: Bills
    description: Credit card bills and current bill summaries
  - name: Balance
    description: Account balance information
  - name: Closing Dates
    description: Credit card closing date management
  - name: Sync
    description: Account synchronization
  - name: Spending Limits
    description: Personal spending limits and alerts management
  - name: Payment Reminders
    description: Payment reminders management with WhatsApp and Email notifications
  - name: Analytics
    description: Financial analytics and insights
  - name: Memories
    description: User memory management for personalized AI interactions
  - name: Open Finance
    description: Open Finance connection and integration
paths:
  /tools/api/get-expensive-categories:
    get:
      tags:
        - Analytics
      description: >-
        Retorna as 3 categorias mais caras no período especificado. Por padrão,
        analisa os últimos 7 dias. Requer API key para autenticação e assinatura
        ativa.
      operationId: getExpensiveCategories
      parameters:
        - name: startDate
          in: query
          description: >-
            Data inicial para análise (formato YYYY-MM-DD). Padrão: 7 dias
            atrás.
          required: false
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: 'Data final para análise (formato YYYY-MM-DD). Padrão: hoje.'
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Top 3 categorias mais caras
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: string
                    description: Categorias formatadas para WhatsApp
                    example: |-
                      1. Alimentação: R$ 450,00
                      2. Transporte: R$ 320,50
                      3. Lazer: R$ 180,00
                  summary:
                    type: object
                    properties:
                      totalCategories:
                        type: number
                        description: Total de categorias encontradas
                      top3Categories:
                        type: array
                        items:
                          type: object
                          properties:
                            category:
                              type: string
                            totalAmount:
                              type: number
                            formattedAmount:
                              type: string
                      totalExpenses:
                        type: number
                      formattedTotalExpenses:
                        type: string
                  dateRange:
                    type: object
                    properties:
                      startDate:
                        type: string
                        format: date-time
                      endDate:
                        type: string
                        format: date-time
                  timestamp:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  responses:
    AuthError:
      description: Authentication or subscription error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
  schemas:
    AuthError: {}
    ServerError: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: 'API key in Bearer token format. Example: Bearer sk-your-api-key-here'

````