Get Expensive Categories

cURL

curl --request GET \
  --url https://www.pierre.finance/tools/api/get-expensive-categories \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://www.pierre.finance/tools/api/get-expensive-categories"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.pierre.finance/tools/api/get-expensive-categories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.pierre.finance/tools/api/get-expensive-categories",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.pierre.finance/tools/api/get-expensive-categories"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.pierre.finance/tools/api/get-expensive-categories")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

GET

tools

api

get-expensive-categories

cURL

curl --request GET \
  --url https://www.pierre.finance/tools/api/get-expensive-categories \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://www.pierre.finance/tools/api/get-expensive-categories"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.pierre.finance/tools/api/get-expensive-categories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.pierre.finance/tools/api/get-expensive-categories",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.pierre.finance/tools/api/get-expensive-categories"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.pierre.finance/tools/api/get-expensive-categories")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

string

required

Bearer token com a API key do usuário. Formato: Bearer sk-your-api-key-here

Parâmetros de Query

string

required

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

string

required

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

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

boolean

required

Indica se a requisição foi bem-sucedida

string

required

Texto formatado com as top 3 categorias e valores (formato WhatsApp-friendly)

object

required

Resumo detalhado da análise de gastos

Show Summary Object

number

required

Número total de categorias com gastos encontradas no período

array

required

Array com as 3 categorias mais caras

Show Category Object

string

required

Nome da categoria

number

required

Valor total gasto na categoria (número)

string

required

Valor formatado em reais (string)

number

required

Valor total de despesas no período

string

required

Total de despesas formatado em reais

object

required

Período analisado

Show Date Range Object

string

required

Data/hora de início do período (ISO 8601)

string

required

Data/hora de fim do período (ISO 8601)

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

Show child attributes

dateRange

object

Show child attributes

timestamp

string<date-time>

Getting Started

Accounts & Balance

Transactions

Credit Cards

Spending Limits

Payment Reminders

Analytics

Memories

Open Finance

Synchronization

MCP Server

Descrição

Autenticação

Parâmetros de Query

Resposta

Sucesso (200)

Erro de Autenticação (401)

Campos da Resposta

Exemplos de Uso

cURL

JavaScript

Python

Códigos de Status

Casos de Uso

Análise de Gastos Mensais

Comparação de Períodos

Controle de Orçamento

Categorias Comuns

Authorizations

Query Parameters

Response

​Descrição

​Autenticação

​Parâmetros de Query

​Resposta

​Sucesso (200)

​Erro de Autenticação (401)

​Campos da Resposta

​Exemplos de Uso

​cURL

​JavaScript

​Python

​Códigos de Status

​Casos de Uso

​Análise de Gastos Mensais

​Comparação de Períodos

​Controle de Orçamento

​Categorias Comuns

Authorizations

Query Parameters

Response

Descrição

Autenticação

Parâmetros de Query

Resposta

Sucesso (200)

Erro de Autenticação (401)

Campos da Resposta

Exemplos de Uso

cURL

JavaScript

Python

Códigos de Status

Casos de Uso

Análise de Gastos Mensais

Comparação de Períodos

Controle de Orçamento

Categorias Comuns