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

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

<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="limitId" type="string" required>
  ID do limite de gastos para consultar o status
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>

### Limite Não Encontrado (404)

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

### Acesso Negado (403)

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

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

<CodeGroup>
  ```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')}")
  ```
</CodeGroup>


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

````