Create Spending Limit

Este endpoint cria um novo alerta de gastos para monitorar uma categoria específica em um período definido.

Descrição

O endpoint POST /tools/api/create-spending-limit permite criar alertas de gastos personalizados para categorias específicas. O usuário será notificado quando atingir 50%, 75% e 100% do limite configurado.

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

Parâmetro interno para indicar requisições via MCP. Use s=s para requisições MCP.

Body Parameters

string

required

Nome da categoria a ser monitorada (ex: “Alimentação”, “Transporte”, “Lazer”)

number

required

Valor limite em BRL. Deve ser um número positivo.

string

required

Período do alerta. Valores válidos: daily, weekly, biweekly, monthly

Resposta

Sucesso (200)

{
  "success": true,
  "data": {
    "id": "limit_123456789",
    "userId": "user_abc123",
    "category": "Alimentação",
    "limitAmount": 1000.00,
    "period": "monthly",
    "isActive": true,
    "isRecurring": false,
    "periodStart": null,
    "createdAt": "2024-11-04T15:30:00Z",
    "updatedAt": "2024-11-04T15:30:00Z"
  },
  "message": "Spending limit created successfully for Alimentação",
  "timestamp": "2024-11-04T15:30:00Z"
}

Erro de Validação (400)

{
  "error": "Invalid or missing category",
  "message": "Category must be a non-empty string"
}

{
  "error": "Invalid or missing limitAmount",
  "message": "limitAmount must be a positive number"
}

{
  "error": "Invalid or missing period",
  "message": "period must be one of: daily, weekly, monthly"
}

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

boolean

required

Indica se a requisição foi bem-sucedida

object

required

Objeto com os dados do alerta criado

Show Spending Limit Object

string

required

Identificador único do alerta criado

string

required

ID do usuário proprietário do alerta

string

required

Categoria de gasto monitorada

number

required

Valor limite configurado em BRL

string

required

Período do alerta: daily, weekly, biweekly, ou monthly

boolean

required

Se o alerta está ativo (sempre true na criação)

boolean

required

Se o alerta se renova automaticamente

string

Data de início do período (null se começar imediatamente)

string

required

Data de criação do alerta (ISO 8601)

string

required

Data da última atualização (ISO 8601)

string

required

Mensagem de confirmação da criação

string

required

Timestamp da requisição em formato ISO 8601

Exemplos de Uso

cURL

# Criar alerta mensal para Alimentação
curl -X POST 'https://www.pierre.finance/tools/api/create-spending-limit' \
  -H 'Authorization: Bearer sk-your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "Alimentação",
    "limitAmount": 1000,
    "period": "monthly"
  }'

# Criar alerta semanal para Transporte
curl -X POST 'https://www.pierre.finance/tools/api/create-spending-limit' \
  -H 'Authorization: Bearer sk-your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "Transporte",
    "limitAmount": 300,
    "period": "weekly"
  }'

JavaScript

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

async function createSpendingLimit(category, limitAmount, period) {
  const response = await fetch(`${BASE_URL}/create-spending-limit`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ category, limitAmount, period })
  });
  
  return await response.json();
}

// Exemplos de uso
createSpendingLimit('Alimentação', 1000, 'monthly');
createSpendingLimit('Transporte', 300, 'weekly');
createSpendingLimit('Lazer', 500, 'biweekly');

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 create_spending_limit(category, limit_amount, period):
    data = {
        'category': category,
        'limitAmount': limit_amount,
        'period': period
    }
    response = requests.post(f'{BASE_URL}/create-spending-limit',
                           headers=headers, json=data)
    return response.json()

# Exemplos de uso
limit = create_spending_limit('Alimentação', 1000, 'monthly')
limit = create_spending_limit('Transporte', 300, 'weekly')
limit = create_spending_limit('Lazer', 500, 'biweekly')

Códigos de Status

200: Sucesso - Alerta criado
400: Parâmetros inválidos
401: Erro de autenticação ou assinatura
403: Quota excedida - limite de alertas atingido
500: Erro interno do servidor

Períodos Disponíveis

daily: Alerta renovado diariamente às 00:00 UTC
weekly: Alerta renovado semanalmente às segundas-feiras 00:00 UTC
biweekly: Alerta renovado a cada duas semanas
monthly: Alerta renovado mensalmente no dia 1º às 00:00 UTC

Limites por Plano

FREE: 3 alertas de gastos
PRO: 10 alertas de gastos
PREMIUM: 30 alertas de gastos

Os alertas enviam notificações automáticas quando você atinge 50%, 75% e 100% do limite configurado. Use categorias consistentes com as suas transações para melhor precisão.

Para criar alertas que começam no próximo período (e não imediatamente), use o endpoint confirm-spending-limit com o parâmetro startNextPeriod.

Authorizations

Authorization

string

header

required

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

Body

application/json

The body is of type any.

Response

Limite de gastos criado com sucesso

success

boolean

Example:

true

data

any

message

string

Example:

"Spending limit created successfully for Alimentação"

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

Body Parameters

Resposta

Sucesso (200)

Erro de Validação (400)

Erro de Autenticação (401)

Erro de Quota Excedida (403)

Campos da Resposta

Exemplos de Uso

cURL

JavaScript

Python

Códigos de Status

Períodos Disponíveis

Limites por Plano

Authorizations

Body

Response

​Descrição

​Autenticação

​Parâmetros de Query

​Body Parameters

​Resposta

​Sucesso (200)

​Erro de Validação (400)

​Erro de Autenticação (401)

​Erro de Quota Excedida (403)

​Campos da Resposta

​Exemplos de Uso

​cURL

​JavaScript

​Python

​Códigos de Status

​Períodos Disponíveis

​Limites por Plano

Authorizations

Body

Response

Descrição

Autenticação

Parâmetros de Query

Body Parameters

Resposta

Sucesso (200)

Erro de Validação (400)

Erro de Autenticação (401)

Erro de Quota Excedida (403)

Campos da Resposta

Exemplos de Uso

cURL

JavaScript

Python

Códigos de Status

Períodos Disponíveis

Limites por Plano