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
}
'

import requests

url = "https://www.pierre.finance/tools/api/confirm-spending-limit"

payload = { "startNextPeriod": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({startNextPeriod: true})
};

fetch('https://www.pierre.finance/tools/api/confirm-spending-limit', 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/confirm-spending-limit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'startNextPeriod' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.pierre.finance/tools/api/confirm-spending-limit"

	payload := strings.NewReader("{\n  \"startNextPeriod\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.pierre.finance/tools/api/confirm-spending-limit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"startNextPeriod\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.pierre.finance/tools/api/confirm-spending-limit")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"startNextPeriod\": true\n}"

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

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

{
  "success": true,
  "message": "✅ Limite de R$ 500.00 criado para \"Transporte\" (semanal)!",
  "limit": {
    "id": "limit_987654321",
    "category": "Transporte",
    "limitAmount": 500.00,
    "period": "weekly",
    "isRecurring": false,
    "periodStart": null,
    "isActive": true
  }
}

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
}
'

import requests

url = "https://www.pierre.finance/tools/api/confirm-spending-limit"

payload = { "startNextPeriod": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({startNextPeriod: true})
};

fetch('https://www.pierre.finance/tools/api/confirm-spending-limit', 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/confirm-spending-limit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'startNextPeriod' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.pierre.finance/tools/api/confirm-spending-limit"

	payload := strings.NewReader("{\n  \"startNextPeriod\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.pierre.finance/tools/api/confirm-spending-limit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"startNextPeriod\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.pierre.finance/tools/api/confirm-spending-limit")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"startNextPeriod\": true\n}"

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

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

{
  "success": true,
  "message": "✅ Limite de R$ 500.00 criado para \"Transporte\" (semanal)!",
  "limit": {
    "id": "limit_987654321",
    "category": "Transporte",
    "limitAmount": 500.00,
    "period": "weekly",
    "isRecurring": false,
    "periodStart": null,
    "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.

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

boolean

required

Se true, o alerta se renova automaticamente a cada período. Padrão: false

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

{
  "success": true,
  "message": "✅ Limite de R$ 500.00 criado para \"Transporte\" (semanal)!",
  "limit": {
    "id": "limit_987654321",
    "category": "Transporte",
    "limitAmount": 500.00,
    "period": "weekly",
    "isRecurring": false,
    "periodStart": null,
    "isActive": true
  }
}

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, biweekly, 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"
}

{
  "error": "Authentication failed",
  "message": "No user ID found in session"
}

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

string

required

Mensagem de confirmação detalhada com informações sobre quando o alerta começará e como funcionará

object

required

Objeto com os dados do alerta criado

Show Spending Limit Object

string

required

Identificador único do alerta criado

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 se renova automaticamente a cada período

string

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

boolean

required

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

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ística	create-spending-limit	confirm-spending-limit
Alertas recorrentes	❌ Não suporta	✅ Suporta via `isRecurring`
Início programado	❌ Sempre imediato	✅ Programável via `startNextPeriod`
Uso típico	APIs e integrações simples	Assistentes IA com confirmação
Mensagens	Simples	Detalhadas 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

Show child attributes

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

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

Comportamento do `startNextPeriod`

Alertas Recorrentes

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

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

​Comportamento do startNextPeriod

​Alertas Recorrentes

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

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

Comportamento do `startNextPeriod`

Alertas Recorrentes