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

# Get Spending Limit Transactions

> Retorna o status detalhado de um limite de gastos específico, incluindo valor gasto atual, porcentagem do limite, próximos alertas e histórico de transações. Calcula automaticamente o período baseado na configuração do limite. Requer API key para autenticação e assinatura ativa.

> [!NOTE]
>
> Retorna o status detalhado de um limite de gastos específico, incluindo valor gasto atual, porcentagem do limite, próximos alertas e histórico de transações.

## Descrição

O endpoint `GET /tools/api/get-spending-limit-transactions` fornece informações detalhadas sobre um limite específico, calculando automaticamente:

* Período atual baseado na configuração do limite
* Valor gasto e porcentagem de uso
* Próximos alertas (50%, 75%, 100%)
* Histórico de alertas enviados
* Número de transações no período

## Autenticação

Este endpoint requer autenticação via Bearer token e assinatura ativa.

**Authorization** `string` *required*

Bearer token com a API key do usuário. Formato: `Bearer sk-your-api-key-here`

## Parâmetros de Query

**limitId** `string` *required*

ID do limite de gastos para consultar o status

## Resposta

### Sucesso (200)

```json Success theme={null}
{
  "success": true,
  "data": {
    "limit": {
      "id": "sl_123abc",
      "category": "Alimentação",
      "limitAmount": 500.00,
      "period": "monthly",
      "periodText": "neste mês",
      "isActive": true,
      "createdAt": "2024-10-15T10:30:00Z",
      "periodStart": "2024-11-01T00:00:00.000Z"
    },
    "spending": {
      "currentSpent": 325.50,
      "percentage": 65.1,
      "remaining": 174.50,
      "transactionCount": 12
    },
    "status": {
      "level": "warning",
      "nextAlert": "75%",
      "alerts": {
        "alertHistory": [
          {
            "alertType": "50%",
            "sentAt": "2024-11-15T08:30:00Z",
            "amount": 250.00
          }
        ]
      }
    }
  },
  "timestamp": "2024-11-04T15:30:00Z"
}
```

### Limite Não Encontrado (404)

```json Not Found theme={null}
{
  "error": "Spending limit not found",
  "message": "No spending limit found with ID: sl_123abc"
}
```

### Acesso Negado (403)

```json Access Denied theme={null}
{
  "error": "Access denied",
  "message": "You can only view your own spending limits"
}
```

## Níveis de Status

O campo `status.level` indica a situação atual:

* **`ok`**: Abaixo de 50% do limite
* **`warning`**: Entre 50% e 99% do limite
* **`danger`**: 100% ou mais do limite

## Próximos Alertas

O campo `status.nextAlert` mostra qual será o próximo alerta:

* **`"50%"`**: Quando atingir 50% do limite
* **`"75%"`**: Quando atingir 75% do limite
* **`"100%"`**: Quando atingir 100% do limite
* **`null`**: Já excedeu 100% (sem próximos alertas)

## Exemplos de Uso

```bash cURL theme={null}
curl -X GET "https://www.pierre.finance/tools/api/get-spending-limit-transactions?limitId=sl_123abc" \
  -H "Authorization: Bearer sk-your-api-key-here"
```

```javascript JavaScript theme={null}
const limitId = 'sl_123abc';
const response = await fetch(`https://www.pierre.finance/tools/api/get-spending-limit-transactions?limitId=${limitId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here'
  }
});

const data = await response.json();
const { limit, spending, status } = data.data;

console.log(`${limit.category}: R$ ${spending.currentSpent.toFixed(2)} / R$ ${limit.limitAmount.toFixed(2)}`);
console.log(`Progresso: ${spending.percentage.toFixed(1)}%`);
console.log(`Restante: R$ ${spending.remaining.toFixed(2)}`);

if (status.nextAlert) {
  console.log(`Próximo alerta: ${status.nextAlert}`);
} else {
  console.log('Limite já excedido');
}
```

```python Python theme={null}
import requests

limit_id = "sl_123abc"
url = f"https://www.pierre.finance/tools/api/get-spending-limit-transactions"
headers = {
    "Authorization": "Bearer sk-your-api-key-here"
}
params = {"limitId": limit_id}

response = requests.get(url, headers=headers, params=params)
data = response.json()

if response.status_code == 200:
    limit = data['data']['limit']
    spending = data['data']['spending']
    status = data['data']['status']
    
    print(f"📊 {limit['category']} ({limit['periodText']})")
    print(f"💰 Gasto: R$ {spending['currentSpent']:.2f} / R$ {limit['limitAmount']:.2f}")
    print(f"📈 Progresso: {spending['percentage']:.1f}%")
    print(f"💳 Transações: {spending['transactionCount']}")
    
    if status['nextAlert']:
        print(f"⚠️  Próximo alerta: {status['nextAlert']}")
    
    # Status com emoji
    status_emoji = {
        'ok': '🟢',
        'warning': '🟡',
        'danger': '🔴'
    }
    print(f"{status_emoji.get(status['level'], '⚪')} Status: {status['level']}")
else:
    print(f"Erro: {data.get('message', 'Limite não encontrado')}")
```


## OpenAPI

````yaml GET /tools/api/get-spending-limit-transactions
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/get-spending-limit-transactions:
    get:
      tags:
        - Spending Limits
      description: >-
        Retorna o status detalhado de um limite de gastos específico, incluindo
        valor gasto atual, porcentagem do limite, próximos alertas e histórico
        de transações. Calcula automaticamente o período baseado na configuração
        do limite. Requer API key para autenticação e assinatura ativa.
      operationId: getSpendingLimitTransactions
      parameters:
        - name: limitId
          in: query
          description: ID do limite de gastos para consultar o status
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Status detalhado do limite de gastos
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/SpendingLimitStatus'
                  timestamp:
                    type: string
                    format: date-time
        '400':
          description: Parâmetros inválidos
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid or missing limitId
                  message:
                    type: string
                    example: limitId must be provided as a query parameter
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          description: Acesso negado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Access denied
                  message:
                    type: string
                    example: You can only view your own spending limits
        '404':
          description: Limite não encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Spending limit not found
                  message:
                    type: string
                    example: 'No spending limit found with ID: sl_123abc'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    SpendingLimitStatus: {}
    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'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.