> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pierre.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm Spending Limit

> Confirma a criação de um limite de gastos após receber aviso sobre gastos atuais. Permite agendar o limite para o próximo período se necessário. Requer API key para autenticação e assinatura ativa.

<Note>
  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.
</Note>

## 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.

<ParamField header="Authorization" type="string" required>
  Bearer token com a API key do usuário. Formato: `Bearer sk-your-api-key-here`
</ParamField>

## Parâmetros de Query

<ParamField query="s" type="string" required="false">
  Parâmetro interno para indicar requisições via MCP. Use `s=s` para requisições MCP.
</ParamField>

## Body Parameters

<ParamField body="category" type="string" required>
  Nome da categoria a ser monitorada (ex: "Alimentação", "Transporte", "Lazer")
</ParamField>

<ParamField body="limitAmount" type="number" required>
  Valor limite em BRL. Deve ser um número positivo.
</ParamField>

<ParamField body="period" type="string" required>
  Período do alerta. Valores válidos: `daily`, `weekly`, `biweekly`, `monthly`
</ParamField>

<ParamField body="isRecurring" type="boolean" required="false">
  Se `true`, o alerta se renova automaticamente a cada período. Padrão: `false`
</ParamField>

<ParamField body="startNextPeriod" type="boolean" required="false">
  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`
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success - Starting Next Period theme={null}
  {
    "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
    }
  }
  ```

  ```json Success - Starting Immediately theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

### Erro de Validação (400)

<ResponseExample>
  ```json Error - Missing Category theme={null}
  {
    "error": "Invalid or missing category",
    "message": "Category must be a non-empty string"
  }
  ```

  ```json Error - Invalid Amount theme={null}
  {
    "error": "Invalid or missing limitAmount",
    "message": "limitAmount must be a positive number"
  }
  ```

  ```json Error - Invalid Period theme={null}
  {
    "error": "Invalid or missing period",
    "message": "period must be one of: daily, weekly, biweekly, monthly"
  }
  ```
</ResponseExample>

### Erro de Autenticação (401)

<ResponseExample>
  ```json Error - Invalid API Key theme={null}
  {
    "error": "Invalid or inactive API key",
    "message": "Please check your API key and try again",
    "type": "invalid_api_key"
  }
  ```

  ```json Error - No Session theme={null}
  {
    "error": "Authentication failed",
    "message": "No user ID found in session"
  }
  ```
</ResponseExample>

### Erro de Quota Excedida (403)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "Quota exceeded",
    "message": "Plano FREE: 3/3 alertas utilizados. Limite atingido! Faça upgrade para criar mais alertas.",
    "success": false
  }
  ```
</ResponseExample>

## Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem de confirmação detalhada com informações sobre quando o alerta começará e como funcionará
</ResponseField>

<ResponseField name="limit" type="object" required>
  Objeto com os dados do alerta criado

  <Expandable title="Spending Limit Object">
    <ResponseField name="id" type="string" required>
      Identificador único do alerta criado
    </ResponseField>

    <ResponseField name="category" type="string" required>
      Categoria de gasto monitorada
    </ResponseField>

    <ResponseField name="limitAmount" type="number" required>
      Valor limite configurado em BRL
    </ResponseField>

    <ResponseField name="period" type="string" required>
      Período do alerta: `daily`, `weekly`, `biweekly`, ou `monthly`
    </ResponseField>

    <ResponseField name="isRecurring" type="boolean" required>
      Se o alerta se renova automaticamente a cada período
    </ResponseField>

    <ResponseField name="periodStart" type="string">
      Data de início do período (null se começar imediatamente, ISO 8601 se programado)
    </ResponseField>

    <ResponseField name="isActive" type="boolean" required>
      Se o alerta está ativo (sempre `true` na criação)
    </ResponseField>
  </Expandable>
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# 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

```javascript theme={null}
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

```python theme={null}
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

<Note>
  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.
</Note>

<Tip>
  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`.
</Tip>


## OpenAPI

````yaml POST /tools/api/confirm-spending-limit
openapi: 3.1.0
info:
  title: Pierre Finance API
  description: >-
    API para acessar dados financeiros do Pierre Finance, incluindo contas,
    transações, parcelas e sincronização.
  version: v1.0.0
servers:
  - url: https://www.pierre.finance
security: []
tags:
  - name: Authentication
    description: API key management and authentication
  - name: Accounts
    description: Financial accounts management
  - name: Transactions
    description: Financial transactions
  - name: Installments
    description: Credit card installments and purchases
  - name: Bills
    description: Credit card bills and current bill summaries
  - name: Balance
    description: Account balance information
  - name: Closing Dates
    description: Credit card closing date management
  - name: Sync
    description: Account synchronization
  - name: Spending Limits
    description: Personal spending limits and alerts management
  - name: Payment Reminders
    description: Payment reminders management with WhatsApp and Email notifications
  - name: Analytics
    description: Financial analytics and insights
  - name: Memories
    description: User memory management for personalized AI interactions
  - name: Open Finance
    description: Open Finance connection and integration
paths:
  /tools/api/confirm-spending-limit:
    post:
      tags:
        - Spending Limits
      description: >-
        Confirma a criação de um limite de gastos após receber aviso sobre
        gastos atuais. Permite agendar o limite para o próximo período se
        necessário. Requer API key para autenticação e assinatura ativa.
      operationId: confirmSpendingLimit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CreateSpendingLimitRequest'
                - type: object
                  properties:
                    startNextPeriod:
                      type: boolean
                      default: true
                      description: >-
                        Se deve começar o limite no próximo período (recomendado
                        quando já há gastos no período atual)
      responses:
        '200':
          description: Limite de gastos confirmado e criado
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: >-
                      ✅ Limite RECORRENTE de R$ 500.00 criado para "Alimentação"
                      (mensal) (começando no próximo mês)!
                  limit:
                    type: object
                    properties:
                      id:
                        type: string
                      category:
                        type: string
                      limitAmount:
                        type: string
                      period:
                        type: string
                      isRecurring:
                        type: boolean
                      periodStart:
                        type: string
                        format: date-time
                        nullable: true
                      isActive:
                        type: boolean
        '400':
          $ref: '#/components/responses/AuthError'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          description: Cota de limites excedida
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Quota exceeded
                  message:
                    type: string
                  success:
                    type: boolean
                    example: false
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateSpendingLimitRequest: {}
    AuthError: {}
    ServerError: {}
  responses:
    AuthError:
      description: Authentication or subscription error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: 'API key in Bearer token format. Example: Bearer sk-your-api-key-here'

````