Skip to main content
GET
/
tools
/
api
/
list-spending-limits
cURL
curl --request GET \
  --url https://www.pierre.finance/tools/api/list-spending-limits \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": [
    {
      "id": "limit_123456789",
      "userId": "user_abc123",
      "category": "Alimentação",
      "limitAmount": 1000.00,
      "period": "monthly",
      "isActive": true,
      "isRecurring": true,
      "periodStart": "2024-11-01T00:00:00.000Z",
      "createdAt": "2024-10-15T10:30:00Z",
      "updatedAt": "2024-10-15T10:30:00Z",
      "currentSpending": 450.75,
      "remainingAmount": 549.25,
      "percentageUsed": 45.08,
      "status": "ok"
    },
    {
      "id": "limit_987654321",
      "userId": "user_abc123",
      "category": "Transporte",
      "limitAmount": 500.00,
      "period": "weekly",
      "isActive": true,
      "isRecurring": false,
      "periodStart": "2024-10-28T00:00:00.000Z",
      "createdAt": "2024-10-20T14:00:00Z",
      "updatedAt": "2024-10-20T14:00:00Z",
      "currentSpending": 380.00,
      "remainingAmount": 120.00,
      "percentageUsed": 76.00,
      "status": "warning"
    }
  ],
  "count": 2,
  "quota": {
    "subscriptionType": "pro",
    "currentCount": 2,
    "limit": 10,
    "canCreate": true,
    "remaining": 8,
    "message": "Plano PRO: 2/10 alertas utilizados. Você pode criar mais 8 alertas.",
    "upgradeMessage": null
  },
  "filters": {
    "includeInactive": false
  },
  "timestamp": "2024-11-04T15:30:00Z"
}
Este endpoint retorna todos os alertas de gastos (spending limits) do usuário autenticado, com informações sobre gastos atuais e status de quota.

​
Descrição

O endpoint GET /tools/api/list-spending-limits retorna a lista completa de alertas de gastos configurados pelo usuário, incluindo o gasto atual de cada período, percentual utilizado e informações sobre a quota disponível no plano do usuário.

​
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

​
includeInactive
boolean
required
Se true, retorna também os alertas inativos. Por padrão, retorna apenas alertas ativos (false).
​
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": [
    {
      "id": "limit_123456789",
      "userId": "user_abc123",
      "category": "Alimentação",
      "limitAmount": 1000.00,
      "period": "monthly",
      "isActive": true,
      "isRecurring": true,
      "periodStart": "2024-11-01T00:00:00.000Z",
      "createdAt": "2024-10-15T10:30:00Z",
      "updatedAt": "2024-10-15T10:30:00Z",
      "currentSpending": 450.75,
      "remainingAmount": 549.25,
      "percentageUsed": 45.08,
      "status": "ok"
    },
    {
      "id": "limit_987654321",
      "userId": "user_abc123",
      "category": "Transporte",
      "limitAmount": 500.00,
      "period": "weekly",
      "isActive": true,
      "isRecurring": false,
      "periodStart": "2024-10-28T00:00:00.000Z",
      "createdAt": "2024-10-20T14:00:00Z",
      "updatedAt": "2024-10-20T14:00:00Z",
      "currentSpending": 380.00,
      "remainingAmount": 120.00,
      "percentageUsed": 76.00,
      "status": "warning"
    }
  ],
  "count": 2,
  "quota": {
    "subscriptionType": "pro",
    "currentCount": 2,
    "limit": 10,
    "canCreate": true,
    "remaining": 8,
    "message": "Plano PRO: 2/10 alertas utilizados. Você pode criar mais 8 alertas.",
    "upgradeMessage": null
  },
  "filters": {
    "includeInactive": false
  },
  "timestamp": "2024-11-04T15:30: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"
}

​
Erro de Quota Excedida (403)

{
  "error": "Quota exceeded",
  "message": "Plano FREE: 3/3 alertas utilizados. Limite atingido! Faça upgrade para criar mais alertas.",
  "success": false
}

​
Campos da Resposta

​
success
boolean
required
Indica se a requisição foi bem-sucedida
​
data
array
required
Array com os alertas de gastos configurados
​
count
number
required
Número total de alertas retornados
​
quota
object
required
Informações sobre a quota de alertas do plano do usuário
​
filters
object
required
Filtros aplicados na requisição
​
timestamp
string
required
Timestamp da requisição em formato ISO 8601

​
Exemplos de Uso

​
cURL

# Listar todos os alertas ativos
curl -X GET 'https://www.pierre.finance/tools/api/list-spending-limits' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Listar todos os alertas (incluindo inativos)
curl -X GET 'https://www.pierre.finance/tools/api/list-spending-limits?includeInactive=true' \
  -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 listSpendingLimits(includeInactive = false) {
  const params = new URLSearchParams({ includeInactive });
  const response = await fetch(`${BASE_URL}/list-spending-limits?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplos de uso
listSpendingLimits(); // Apenas alertas ativos
listSpendingLimits(true); // Incluindo inativos

​
Python

import requests

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 list_spending_limits(include_inactive=False):
    params = {'includeInactive': str(include_inactive).lower()}
    response = requests.get(f'{BASE_URL}/list-spending-limits', 
                          headers=headers, params=params)
    return response.json()

# Exemplos de uso
limits = list_spending_limits()  # Apenas ativos
all_limits = list_spending_limits(include_inactive=True)  # Todos

​
Códigos de Status

  • 200: Sucesso - Alertas retornados
  • 401: Erro de autenticação ou assinatura
  • 403: Quota excedida (ao tentar criar novos alertas)
  • 500: Erro interno do servidor

​
Limites por Plano

  • FREE: 3 alertas de gastos
  • PRO: 10 alertas de gastos
  • PREMIUM: 30 alertas de gastos
Os alertas são calculados em tempo real com base nas transações do período especificado. O status é atualizado automaticamente: ok para 0-49%, warning para 50-74%, e danger para 75% ou mais do limite.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
includeInactive
boolean
default:false

Se deve incluir limites inativos na resposta

Response

Lista de limites de gastos

​
success
boolean
Example:

true

​
data
any[]
​
count
number

Número de limites retornados

Example:

3

​
quota
any
​
filters
object
​
timestamp
string<date-time>