Skip to main content
POST
/
tools
/
api
/
confirm-spending-limit
cURL
curl --request POST \
  --url https://www.pierre.finance/tools/api/confirm-spending-limit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "startNextPeriod": true
}
'
{
  "success": true,
  "message": "✅ Limite RECORRENTE de R$ 1000.00 criado para \"Alimentação\" (mensal) (começando no próximo mês)!\n\n📅 Este limite começará a valer a partir de 01/12/2024 às 00:00h.\n💡 Você será notificado quando atingir 50%, 75% e 100% do limite a partir de então.",
  "limit": {
    "id": "limit_123456789",
    "category": "Alimentação",
    "limitAmount": 1000.00,
    "period": "monthly",
    "isRecurring": true,
    "periodStart": "2024-12-01T00:00:00.000Z",
    "isActive": true
  }
}
Este endpoint cria um alerta de gastos com opções avançadas, incluindo alertas recorrentes e início programado para o próximo período.

​
Descrição

O endpoint POST /tools/api/confirm-spending-limit é uma versão avançada do endpoint de criação, permitindo configurar alertas recorrentes e programar o início do monitoramento para o próximo período. É particularmente útil quando integrado com assistentes de IA que coletam confirmação do usuário antes de criar o alerta.

​
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

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

​
Body Parameters

​
category
string
required
Nome da categoria a ser monitorada (ex: “Alimentação”, “Transporte”, “Lazer”)
​
limitAmount
number
required
Valor limite em BRL. Deve ser um número positivo.
​
period
string
required
Período do alerta. Valores válidos: daily, weekly, biweekly, monthly
​
isRecurring
boolean
required
Se true, o alerta se renova automaticamente a cada período. Padrão: false
​
startNextPeriod
boolean
required
Se true, o alerta começa apenas no próximo período (não conta gastos do período atual). Se false, começa imediatamente. Padrão: true

​
Resposta

​
Sucesso (200)

{
  "success": true,
  "message": "✅ Limite RECORRENTE de R$ 1000.00 criado para \"Alimentação\" (mensal) (começando no próximo mês)!\n\n📅 Este limite começará a valer a partir de 01/12/2024 às 00:00h.\n💡 Você será notificado quando atingir 50%, 75% e 100% do limite a partir de então.",
  "limit": {
    "id": "limit_123456789",
    "category": "Alimentação",
    "limitAmount": 1000.00,
    "period": "monthly",
    "isRecurring": true,
    "periodStart": "2024-12-01T00:00:00.000Z",
    "isActive": true
  }
}

​
Erro de Validação (400)

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

​
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
​
message
string
required
Mensagem de confirmação detalhada com informações sobre quando o alerta começará e como funcionará
​
limit
object
required
Objeto com os dados do alerta criado

​
Exemplos de Uso

​
cURL

# Criar alerta recorrente mensal começando no próximo mês
curl -X POST 'https://www.pierre.finance/tools/api/confirm-spending-limit' \
  -H 'Authorization: Bearer sk-your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "Alimentação",
    "limitAmount": 1000,
    "period": "monthly",
    "isRecurring": true,
    "startNextPeriod": true
  }'

# Criar alerta único começando imediatamente
curl -X POST 'https://www.pierre.finance/tools/api/confirm-spending-limit' \
  -H 'Authorization: Bearer sk-your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "Transporte",
    "limitAmount": 300,
    "period": "weekly",
    "isRecurring": false,
    "startNextPeriod": false
  }'

​
JavaScript

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

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

// Exemplos de uso
// Alerta recorrente mensal
confirmSpendingLimit({
  category: 'Alimentação',
  limitAmount: 1000,
  period: 'monthly',
  isRecurring: true,
  startNextPeriod: true
});

// Alerta único semanal imediato
confirmSpendingLimit({
  category: 'Transporte',
  limitAmount: 300,
  period: 'weekly',
  isRecurring: false,
  startNextPeriod: false
});

​
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 confirm_spending_limit(category, limit_amount, period, 
                          is_recurring=False, start_next_period=True):
    data = {
        'category': category,
        'limitAmount': limit_amount,
        'period': period,
        'isRecurring': is_recurring,
        'startNextPeriod': start_next_period
    }
    response = requests.post(f'{BASE_URL}/confirm-spending-limit',
                           headers=headers, json=data)
    return response.json()

# Exemplos de uso
# Alerta recorrente mensal
result = confirm_spending_limit(
    'Alimentação', 1000, 'monthly',
    is_recurring=True, start_next_period=True
)

# Alerta único semanal imediato
result = confirm_spending_limit(
    'Transporte', 300, 'weekly',
    is_recurring=False, start_next_period=False
)

​
Códigos de Status

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

​
Diferenças entre create-spending-limit e confirm-spending-limit

Característicacreate-spending-limitconfirm-spending-limit
Alertas recorrentes❌ Não suporta✅ Suporta via isRecurring
Início programado❌ Sempre imediato✅ Programável via startNextPeriod
Uso típicoAPIs e integrações simplesAssistentes IA com confirmação
MensagensSimplesDetalhadas e formatadas

​
Comportamento do startNextPeriod

Quando startNextPeriod: true:
  • daily: Começa amanhã às 00:00 UTC
  • weekly: Começa na próxima segunda-feira às 00:00 UTC
  • biweekly: Começa na próxima quinzena
  • monthly: Começa no dia 1º do próximo mês às 00:00 UTC
Quando startNextPeriod: false:
  • O alerta começa imediatamente e conta gastos do período atual

​
Alertas Recorrentes

Quando isRecurring: true, o alerta:
  • Se renova automaticamente a cada período
  • Mantém as mesmas configurações (categoria, valor, período)
  • Não precisa ser recriado manualmente
  • Continua ativo até ser desativado ou deletado
Este endpoint é ideal para uso em assistentes de IA que interagem com o usuário antes de criar o alerta, permitindo confirmar detalhes como se o alerta deve ser recorrente e quando deve começar.
Para alertas que devem se renovar automaticamente (como limites mensais de gastos), sempre use isRecurring: true. Para alertas pontuais (como limite de gastos em uma viagem), use isRecurring: false.

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
startNextPeriod
boolean
default:true

Se deve começar o limite no próximo período (recomendado quando já há gastos no período atual)

Response

Limite de gastos confirmado e criado

​
success
boolean
Example:

true

​
message
string
Example:

"✅ Limite RECORRENTE de R$ 500.00 criado para \"Alimentação\" (mensal) (começando no próximo mês)!"

​
limit
object