Skip to main content
GET
/
tools
/
api
/
get-expensive-categories
cURL
curl --request GET \
  --url https://www.pierre.finance/tools/api/get-expensive-categories \
  --header 'Authorization: Bearer <token>'
{
  "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"
}
Este endpoint retorna as 3 categorias de despesas mais caras em um período específico.

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.
Authorization
string
required
Bearer token com a API key do usuário. Formato: Bearer sk-your-api-key-here

Parâmetros de Query

startDate
string
required
Data inicial para análise no formato YYYY-MM-DD. Padrão: 7 dias atrás.
endDate
string
required
Data final para análise no formato YYYY-MM-DD. Padrão: hoje.
s
string
required
Parâmetro interno para indicar requisições via MCP. Use s=s para requisições MCP.

Resposta

Sucesso (200)

{
  "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"
}

Erro de Autenticação (401)

{
  "error": "Invalid or inactive API key",
  "message": "Please check your API key and try again",
  "type": "invalid_api_key"
}

Campos da Resposta

success
boolean
required
Indica se a requisição foi bem-sucedida
data
string
required
Texto formatado com as top 3 categorias e valores (formato WhatsApp-friendly)
summary
object
required
Resumo detalhado da análise de gastos
dateRange
object
required
Período analisado
timestamp
string
required
Timestamp da requisição em formato ISO 8601

Exemplos de Uso

cURL

# 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

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

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.
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.
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.

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

Authorizations

Authorization
string
header
required

API key in Bearer token format. Example: Bearer sk-your-api-key-here

Query Parameters

startDate
string<date>

Data inicial para análise (formato YYYY-MM-DD). Padrão: 7 dias atrás.

endDate
string<date>

Data final para análise (formato YYYY-MM-DD). Padrão: hoje.

Response

Top 3 categorias mais caras

success
boolean
Example:

true

data
string

Categorias formatadas para WhatsApp

Example:

"1. Alimentação: R$ 450,00\n2. Transporte: R$ 320,50\n3. Lazer: R$ 180,00"

summary
object
dateRange
object
timestamp
string<date-time>