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

> Retrieve all installments transactions of the period. Fetches ALL installments (past, current, and future) for purchases made within the specified period. Requires API key for authentication and active subscription.

<Note>
  Este endpoint retorna informações sobre compras parceladas do usuário autenticado.
</Note>

## Descrição

O endpoint `GET /tools/api/get-installments` retorna informações detalhadas sobre compras parceladas do usuário autenticado. Busca TODAS as parcelas (passadas, atuais e futuras) para compras realizadas dentro do período especificado, incluindo cronograma de pagamentos, valores das parcelas e datas de vencimento.

## 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="startDate" type="string" required="false">
  Data inicial para filtrar compras parceladas (formato YYYY-MM-DD). Se não fornecido, usa o primeiro dia de 3 meses atrás como padrão.
</ParamField>

<ParamField query="endDate" type="string" required="false">
  Data final para filtrar compras parceladas (formato YYYY-MM-DD). Se não fornecido, usa o último dia do mês atual como padrão.
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "data": {
      "summary": {
        "totalAmount": 5000.00,
        "totalInstallments": 12,
        "totalPurchases": 3,
        "installmentDistribution": [
          {
            "totalInstallments": 12,
            "count": 1,
            "totalAmount": 3000.00
          },
          {
            "totalInstallments": 6,
            "count": 2,
            "totalAmount": 2000.00
          }
        ]
      },
      "purchases": [
        {
          "purchaseDate": "2024-01-10",
          "totalAmount": 3000.00,
          "installments": [
            {
              "description": "Compra parcelada - Eletrônicos",
              "amount": 250.00,
              "installmentNumber": 1,
              "totalInstallments": 12,
              "dueDate": "2024-02-10",
              "category": "Eletrônicos",
              "status": "POSTED"
            },
            {
              "description": "Compra parcelada - Eletrônicos",
              "amount": 250.00,
              "installmentNumber": 2,
              "totalInstallments": 12,
              "dueDate": "2024-03-10",
              "category": "Eletrônicos",
              "status": "PENDING"
            }
          ]
        },
        {
          "purchaseDate": "2024-01-15",
          "totalAmount": 1200.00,
          "installments": [
            {
              "description": "Compra parcelada - Roupas",
              "amount": 200.00,
              "installmentNumber": 1,
              "totalInstallments": 6,
              "dueDate": "2024-02-15",
              "category": "Roupas",
              "status": "POSTED"
            }
          ]
        }
      ]
    },
    "summary": {
      "totalAmount": 5000.00,
      "totalInstallments": 12,
      "totalPurchases": 3,
      "installmentDistribution": [
        {
          "totalInstallments": 12,
          "count": 1,
          "totalAmount": 3000.00
        },
        {
          "totalInstallments": 6,
          "count": 2,
          "totalAmount": 2000.00
        }
      ]
    },
    "dateRange": {
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z"
    },
    "timestamp": "2024-01-15T10: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="object" required>
  Objeto com os dados das compras parceladas

  <Expandable title="InstallmentStats Object">
    <ResponseField name="summary" type="object" required>
      Resumo das compras parceladas

      <Expandable title="InstallmentSummary Object">
        <ResponseField name="totalAmount" type="number" required>
          Valor total de todas as compras parceladas
        </ResponseField>

        <ResponseField name="totalInstallments" type="number" required>
          Número total de parcelas
        </ResponseField>

        <ResponseField name="totalPurchases" type="number" required>
          Número total de compras parceladas
        </ResponseField>

        <ResponseField name="installmentDistribution" type="array" required>
          Distribuição das parcelas por número de parcelas

          <Expandable title="Distribution Object">
            <ResponseField name="totalInstallments" type="number" required>
              Número total de parcelas neste grupo
            </ResponseField>

            <ResponseField name="count" type="number" required>
              Quantidade de compras neste grupo
            </ResponseField>

            <ResponseField name="totalAmount" type="number" required>
              Valor total deste grupo
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="purchases" type="array" required>
      Array com as compras parceladas

      <Expandable title="InstallmentPurchase Object">
        <ResponseField name="purchaseDate" type="string" required>
          Data da compra no formato YYYY-MM-DD
        </ResponseField>

        <ResponseField name="totalAmount" type="number" required>
          Valor total da compra
        </ResponseField>

        <ResponseField name="installments" type="array" required>
          Array com as parcelas da compra

          <Expandable title="Installment Object">
            <ResponseField name="description" type="string" required>
              Descrição da parcela
            </ResponseField>

            <ResponseField name="amount" type="number" required>
              Valor da parcela
            </ResponseField>

            <ResponseField name="installmentNumber" type="number" required>
              Número da parcela atual
            </ResponseField>

            <ResponseField name="totalInstallments" type="number" required>
              Número total de parcelas
            </ResponseField>

            <ResponseField name="dueDate" type="string" required>
              Data de vencimento da parcela no formato YYYY-MM-DD
            </ResponseField>

            <ResponseField name="category" type="string">
              Categoria da compra (pode ser null)
            </ResponseField>

            <ResponseField name="status" type="string" required>
              Status da parcela (POSTED, PENDING)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object" required>
  Resumo geral das compras parceladas (mesmo objeto do data.summary)
</ResponseField>

<ResponseField name="dateRange" type="object" required>
  Período dos dados retornados

  <Expandable title="DateRange Object">
    <ResponseField name="startDate" type="string" required>
      Data inicial do período em formato ISO 8601
    </ResponseField>

    <ResponseField name="endDate" type="string" required>
      Data final do período em formato ISO 8601
    </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}
# Obter todas as compras parceladas
curl -X GET 'https://www.pierre.finance/tools/api/get-installments' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Obter compras parceladas de um período específico
curl -X GET 'https://www.pierre.finance/tools/api/get-installments?startDate=2024-01-01&endDate=2024-12-31' \
  -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 getInstallments(filters = {}) {
  const params = new URLSearchParams(filters);
  const response = await fetch(`${BASE_URL}/get-installments?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplos de uso
getInstallments();
getInstallments({ startDate: '2024-01-01', endDate: '2024-12-31' });
```

### 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 get_installments(filters=None):
    if filters is None:
        filters = {}
    
    response = requests.get(f'{BASE_URL}/get-installments', 
                          headers=headers, params=filters)
    return response.json()

# Exemplos de uso
installments = get_installments()
installments = get_installments({
    'startDate': '2024-01-01',
    'endDate': '2024-12-31'
})
```

## Códigos de Status

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

<Note>
  Este endpoint retorna TODAS as parcelas (passadas, atuais e futuras) para compras realizadas no período especificado. Para dados mais recentes, use o endpoint de sincronização manual.
</Note>


## OpenAPI

````yaml GET /tools/api/get-installments
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-installments:
    get:
      tags:
        - Installments
      description: >-
        Retrieve all installments transactions of the period. Fetches ALL
        installments (past, current, and future) for purchases made within the
        specified period. Requires API key for authentication and active
        subscription.
      operationId: getInstallments
      parameters:
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: Start date for filtering (YYYY-MM-DD format)
          description: >-
            Start date for filtering. Defaults to first day 3 months ago if not
            provided.
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
            description: End date for filtering (YYYY-MM-DD format)
          description: >-
            End date for filtering. Defaults to last day of current month if not
            provided.
      responses:
        '200':
          description: Installments data and statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InstallmentStats'
                  summary:
                    $ref: '#/components/schemas/InstallmentSummary'
                  purchases:
                    type: array
                    items:
                      $ref: '#/components/schemas/InstallmentPurchase'
                  dateRange:
                    type: object
                    properties:
                      startDate:
                        type: string
                        format: date-time
                      endDate:
                        type: string
                        format: date-time
                  timestamp:
                    type: string
                    format: date-time
        '401':
          description: Authentication or subscription error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    InstallmentStats: {}
    InstallmentSummary: {}
    InstallmentPurchase: {}
    AuthError: {}
    ServerError: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: 'API key in Bearer token format. Example: Bearer sk-your-api-key-here'

````