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

# List Payment Reminders

> Lista todos os lembretes de pagamento do usuário com informações de cota. Permite filtrar por status (active, all, upcoming, overdue). Requer API key para autenticação e assinatura ativa.

<Note>
  Este endpoint retorna todos os lembretes de pagamento do usuário autenticado, com informações sobre quota disponível.
</Note>

## Descrição

O endpoint `GET /tools/api/list-payment-reminders` retorna a lista de lembretes de pagamento com opções de filtro por status e proximidade do vencimento.

## 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="filter" type="string" required="false">
  Filtro de lembretes: `active` (padrão), `all`, `upcoming`, ou `overdue`
</ParamField>

<ParamField query="days" type="integer" required="false">
  Número de dias para filtrar lembretes próximos (usado com filter=upcoming). Padrão: 7 dias.
</ParamField>

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

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "pr_123456789",
        "title": "Conta de luz",
        "amount": 150.00,
        "dueDate": "2024-12-15",
        "reminderTime": "2024-12-14T09:00:00Z",
        "status": "active",
        "isRecurring": false,
        "recurrencePattern": null,
        "createdAt": "2024-11-20T10:00:00Z",
        "updatedAt": "2024-11-20T10:00:00Z"
      },
      {
        "id": "pr_987654321",
        "title": "Aluguel",
        "amount": 1500.00,
        "dueDate": "2024-12-05",
        "reminderTime": "2024-12-04T09:00:00Z",
        "status": "active",
        "isRecurring": true,
        "recurrencePattern": "monthly",
        "createdAt": "2024-10-05T15:30:00Z",
        "updatedAt": "2024-11-05T09:00:00Z"
      }
    ],
    "count": 2,
    "filter": "Active reminders",
    "quota": {
      "subscriptionType": "pro",
      "currentCount": 2,
      "limit": 10,
      "canCreate": true,
      "remaining": 8
    },
    "timestamp": "2024-11-27T15:30:00Z"
  }
  ```
</ResponseExample>

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

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

## Campos da Resposta

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

<ResponseField name="data" type="array" required>
  Array com os lembretes de pagamento

  <Expandable title="Payment Reminder Object">
    <ResponseField name="id" type="string" required>
      Identificador único do lembrete
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Título do lembrete
    </ResponseField>

    <ResponseField name="amount" type="number">
      Valor do pagamento em BRL (pode ser null)
    </ResponseField>

    <ResponseField name="dueDate" type="string">
      Data de vencimento (YYYY-MM-DD)
    </ResponseField>

    <ResponseField name="reminderTime" type="string">
      Data/hora do lembrete (ISO 8601)
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status: `active`, `completed`, ou `inactive`
    </ResponseField>

    <ResponseField name="isRecurring" type="boolean" required>
      Se o lembrete é recorrente
    </ResponseField>

    <ResponseField name="recurrencePattern" type="string">
      Padrão de recorrência: `daily`, `weekly`, `monthly`, ou `yearly`
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      Data de criação (ISO 8601)
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      Data da última atualização (ISO 8601)
    </ResponseField>

    <ResponseField name="completedAt" type="string">
      Data de conclusão (ISO 8601, apenas se status=completed)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number" required>
  Número total de lembretes retornados
</ResponseField>

<ResponseField name="filter" type="string" required>
  Descrição do filtro aplicado
</ResponseField>

<ResponseField name="quota" type="object" required>
  Informações sobre a quota de lembretes do plano do usuário

  <Expandable title="Quota Object">
    <ResponseField name="subscriptionType" type="string">
      Tipo de plano: `basic`, `pro`, ou `premium`
    </ResponseField>

    <ResponseField name="currentCount" type="number" required>
      Número de lembretes atualmente criados
    </ResponseField>

    <ResponseField name="limit" type="number" required>
      Limite de lembretes do plano
    </ResponseField>

    <ResponseField name="canCreate" type="boolean" required>
      Se o usuário pode criar mais lembretes
    </ResponseField>

    <ResponseField name="remaining" type="number" required>
      Número de lembretes que ainda podem ser criados
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  Timestamp da requisição em formato ISO 8601
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# Listar lembretes ativos
curl -X GET 'https://www.pierre.finance/tools/api/list-payment-reminders' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Listar lembretes próximos (próximos 7 dias)
curl -X GET 'https://www.pierre.finance/tools/api/list-payment-reminders?filter=upcoming&days=7' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Listar todos os lembretes
curl -X GET 'https://www.pierre.finance/tools/api/list-payment-reminders?filter=all' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Listar lembretes vencidos
curl -X GET 'https://www.pierre.finance/tools/api/list-payment-reminders?filter=overdue' \
  -H 'Authorization: Bearer sk-your-api-key-here'
```

### JavaScript

```javascript theme={null}
const API_KEY = 'sk-your-api-key-here';
const BASE_URL = 'https://www.pierre.finance/tools/api';

async function listPaymentReminders(filter = 'active', days = 7) {
  const params = new URLSearchParams({ filter });
  if (filter === 'upcoming') {
    params.append('days', days);
  }
  
  const response = await fetch(`${BASE_URL}/list-payment-reminders?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplos de uso
listPaymentReminders(); // Lembretes ativos
listPaymentReminders('upcoming', 7); // Próximos 7 dias
listPaymentReminders('all'); // Todos
listPaymentReminders('overdue'); // Vencidos
```

### 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 list_payment_reminders(filter='active', days=7):
    params = {'filter': filter}
    if filter == 'upcoming':
        params['days'] = days
    
    response = requests.get(f'{BASE_URL}/list-payment-reminders', 
                          headers=headers, params=params)
    return response.json()

# Exemplos de uso
reminders = list_payment_reminders()  # Ativos
upcoming = list_payment_reminders('upcoming', 7)  # Próximos 7 dias
all_reminders = list_payment_reminders('all')  # Todos
overdue = list_payment_reminders('overdue')  # Vencidos
```

## Códigos de Status

* `200`: Sucesso - Lembretes retornados
* `401`: Erro de autenticação ou assinatura
* `500`: Erro interno do servidor

## Filtros Disponíveis

* **active**: Retorna apenas lembretes ativos (padrão)
* **all**: Retorna todos os lembretes (ativos, completados e inativos)
* **upcoming**: Retorna lembretes com vencimento nos próximos X dias
* **overdue**: Retorna lembretes vencidos e não pagos

## Limites por Plano

* **BASIC**: 5 lembretes ativos
* **PRO**: 10 lembretes ativos
* **PREMIUM**: 30 lembretes ativos

<Note>
  Os lembretes recorrentes são renovados automaticamente após a data de vencimento. Lembretes completados não contam para o limite de quota.
</Note>

<Tip>
  Use `filter=upcoming&days=3` para ver os lembretes que vencem nos próximos 3 dias e se planejar melhor.
</Tip>


## OpenAPI

````yaml GET /tools/api/list-payment-reminders
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/list-payment-reminders:
    get:
      tags:
        - Payment Reminders
      description: >-
        Lista todos os lembretes de pagamento do usuário com informações de
        cota. Permite filtrar por status (active, all, upcoming, overdue).
        Requer API key para autenticação e assinatura ativa.
      operationId: listPaymentReminders
      parameters:
        - name: filter
          in: query
          description: 'Filtro de lembretes: active (padrão), all, upcoming, overdue'
          required: false
          schema:
            type: string
            enum:
              - active
              - all
              - upcoming
              - overdue
            default: active
        - name: days
          in: query
          description: >-
            Número de dias para filtrar lembretes próximos (usado com
            filter=upcoming)
          required: false
          schema:
            type: integer
            default: 7
      responses:
        '200':
          description: Lista de lembretes de pagamento
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentReminder'
                  count:
                    type: number
                    example: 3
                  filter:
                    type: string
                    example: Active reminders
                  quota:
                    $ref: '#/components/schemas/PaymentReminderQuota'
                  timestamp:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    PaymentReminder:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        amount:
          type: number
          nullable: true
        dueDate:
          type: string
          format: date
          nullable: true
        reminderTime:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum:
            - active
            - completed
            - inactive
        isRecurring:
          type: boolean
        recurrencePattern:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
    PaymentReminderQuota:
      type: object
      properties:
        subscriptionType:
          type: string
          enum:
            - basic
            - pro
            - premium
        currentCount:
          type: number
        limit:
          type: number
        canCreate:
          type: boolean
        remaining:
          type: number
    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'

````