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

# Create Payment Reminder

> Cria um novo lembrete de pagamento. Permite criar lembretes únicos ou recorrentes com notificações via WhatsApp e Email. Requer API key para autenticação e assinatura ativa. O usuário deve ter cota disponível baseada no seu plano.

<Note>
  Este endpoint cria um novo lembrete de pagamento com notificações via WhatsApp e Email.
</Note>

## Descrição

O endpoint `POST /tools/api/create-payment-reminder` permite criar lembretes de pagamento únicos ou recorrentes. Você receberá notificações automáticas via WhatsApp e Email nos horários configurados.

## 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="title" type="string" required>
  Título do lembrete (ex: "Conta de luz", "Aluguel")
</ParamField>

<ParamField body="amount" type="number">
  Valor do pagamento em BRL (opcional)
</ParamField>

<ParamField body="dueDate" type="string" required>
  Data de vencimento no formato YYYY-MM-DD
</ParamField>

<ParamField body="reminderTime" type="string">
  Data/hora do lembrete em formato ISO 8601. Se não fornecido, será 1 dia antes do vencimento às 9h.
</ParamField>

<ParamField body="isRecurring" type="boolean">
  Se o lembrete é recorrente (padrão: false)
</ParamField>

<ParamField body="recurrencePattern" type="string">
  Padrão de recorrência: `daily`, `weekly`, `monthly`, ou `yearly`. Obrigatório se isRecurring=true.
</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-27T15:30:00Z",
      "updatedAt": "2024-11-27T15:30:00Z"
    },
    "message": "Payment reminder created successfully: Conta de luz",
    "timestamp": "2024-11-27T15:30:00Z"
  }
  ```
</ResponseExample>

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

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

  ```json Error - Missing Due Date theme={null}
  {
    "error": "Invalid or missing dueDate",
    "message": "dueDate must be provided in YYYY-MM-DD format"
  }
  ```

  ```json Error - Invalid Recurrence theme={null}
  {
    "error": "Invalid recurrence configuration",
    "message": "recurrencePattern is required when isRecurring is true"
  }
  ```
</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>

### Erro de Quota Excedida (403)

<ResponseExample>
  ```json Error theme={null}
  {
    "success": false,
    "error": "Quota exceeded",
    "message": "Limite de lembretes atingido. Você já tem 10 lembretes ativos e seu plano PRO permite até 10 lembretes."
  }
  ```
</ResponseExample>

## Campos da Resposta

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

<ResponseField name="data" type="object" required>
  Objeto com os dados do lembrete criado

  <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>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem de confirmação da criação
</ResponseField>

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

## Exemplos de Uso

### cURL

```bash theme={null}
# Criar lembrete único
curl -X POST 'https://www.pierre.finance/tools/api/create-payment-reminder' \
  -H 'Authorization: Bearer sk-your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Conta de luz",
    "amount": 150.00,
    "dueDate": "2024-12-15"
  }'

# Criar lembrete recorrente mensal
curl -X POST 'https://www.pierre.finance/tools/api/create-payment-reminder' \
  -H 'Authorization: Bearer sk-your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Aluguel",
    "amount": 1500.00,
    "dueDate": "2024-12-05",
    "isRecurring": true,
    "recurrencePattern": "monthly"
  }'
```

### JavaScript

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

async function createPaymentReminder(title, dueDate, amount = null, isRecurring = false, recurrencePattern = null) {
  const body = {
    title,
    dueDate,
    ...(amount && { amount }),
    ...(isRecurring && { isRecurring, recurrencePattern })
  };
  
  const response = await fetch(`${BASE_URL}/create-payment-reminder`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });
  
  return await response.json();
}

// Exemplos de uso
createPaymentReminder('Conta de luz', '2024-12-15', 150);
createPaymentReminder('Aluguel', '2024-12-05', 1500, true, 'monthly');
```

### Python

```python theme={null}
import requests
from datetime import datetime, timedelta

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 create_payment_reminder(title, due_date, amount=None, is_recurring=False, recurrence_pattern=None):
    data = {
        'title': title,
        'dueDate': due_date
    }
    
    if amount:
        data['amount'] = amount
    if is_recurring:
        data['isRecurring'] = is_recurring
        data['recurrencePattern'] = recurrence_pattern
    
    response = requests.post(f'{BASE_URL}/create-payment-reminder',
                           headers=headers, json=data)
    return response.json()

# Exemplos de uso
reminder = create_payment_reminder('Conta de luz', '2024-12-15', 150)
recurring = create_payment_reminder('Aluguel', '2024-12-05', 1500, True, 'monthly')
```

## Códigos de Status

* `200`: Sucesso - Lembrete criado
* `400`: Parâmetros inválidos
* `401`: Erro de autenticação ou assinatura
* `403`: Quota excedida - limite de lembretes atingido
* `500`: Erro interno do servidor

## Limites por Plano

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

## Recorrência

Os lembretes recorrentes são renovados automaticamente após a data de vencimento:

* **daily**: Todos os dias no mesmo horário
* **weekly**: Toda semana no mesmo dia da semana
* **monthly**: Todo mês no mesmo dia do mês
* **yearly**: Todo ano na mesma data

<Note>
  As notificações são enviadas via WhatsApp e Email no horário configurado. Se não especificado, o lembrete será enviado 1 dia antes do vencimento às 9h (horário de Brasília).
</Note>

<Tip>
  Para contas mensais fixas como aluguel, internet e outros serviços, use lembretes recorrentes para receber notificações automáticas todo mês.
</Tip>


## OpenAPI

````yaml POST /tools/api/create-payment-reminder
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/create-payment-reminder:
    post:
      tags:
        - Payment Reminders
      description: >-
        Cria um novo lembrete de pagamento. Permite criar lembretes únicos ou
        recorrentes com notificações via WhatsApp e Email. Requer API key para
        autenticação e assinatura ativa. O usuário deve ter cota disponível
        baseada no seu plano.
      operationId: createPaymentReminder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentReminderRequest'
      responses:
        '200':
          description: Lembrete de pagamento criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/PaymentReminder'
                  message:
                    type: string
                    example: 'Payment reminder created successfully: Conta de luz'
                  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 title
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          description: Cota de lembretes 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:
    CreatePaymentReminderRequest:
      type: object
      required:
        - title
        - dueDate
      properties:
        title:
          type: string
        amount:
          type: number
        dueDate:
          type: string
          format: date
        reminderTime:
          type: string
          format: date-time
        isRecurring:
          type: boolean
          default: false
        recurrencePattern:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - yearly
    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
    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'

````