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

> Retrieves the user's financial transaction history within a specific period with intelligent filtering and automatic categorization. Supports filtering by account type, transaction type, category, amount ranges, and natural language queries via clientMessage parameter. Applies two processing stages: 1) LLM-powered intelligent filtering (when clientMessage is provided), 2) Automatic transaction categorization (always applied). Supports two response formats: 'raw' (default) for unprocessed data, and 'structured' for organized data with groupings and summaries. Requires API key for authentication and active subscription.

<Note>
  Este endpoint retorna transações financeiras do usuário autenticado com filtros opcionais.
</Note>

## Descrição

O endpoint `GET /tools/api/get-transactions` retorna o histórico de transações financeiras do usuário autenticado com **filtragem inteligente** e **categorização automática**. Possui duas funcionalidades avançadas:

1. **Filtragem Inteligente via LLM**: Use o parâmetro `clientMessage` para filtrar transações com linguagem natural
2. **Categorização Automática**: Todas as transações são categorizadas automaticamente por IA

Suporta dois formatos de resposta: 'raw' (padrão) para dados não processados, e 'structured' para dados organizados com agrupamentos e resumos.

## 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 transações (formato YYYY-MM-DD). Se não fornecido, usa 3 meses atrás como padrão.
</ParamField>

<ParamField query="endDate" type="string" required="false">
  Data final para filtrar transações (formato YYYY-MM-DD). Se não fornecido, usa hoje como padrão.
</ParamField>

<ParamField query="categories" type="string" required="false">
  Lista de categorias separadas por vírgula para filtrar transações.
</ParamField>

<ParamField query="minAmount" type="number" required="false">
  Valor mínimo das transações para filtrar.
</ParamField>

<ParamField query="maxAmount" type="number" required="false">
  Valor máximo das transações para filtrar.
</ParamField>

<ParamField query="accountType" type="string" required="false">
  Tipo de conta para filtrar. Valores válidos: BANK, CREDIT, INVESTMENT, LOAN
</ParamField>

<ParamField query="accountSubtype" type="string" required="false">
  Subtipo de conta para filtrar. Valores válidos: CHECKING\_ACCOUNT, SAVINGS\_ACCOUNT, CREDIT\_CARD, PAYMENT\_ACCOUNT
</ParamField>

<ParamField query="includeStatus" type="string" required="false">
  Status de transação. Valores válidos: POSTED, PENDING
</ParamField>

<ParamField query="format" type="string" required="false">
  Formato da resposta. Valores válidos: 'raw' (padrão) retorna dados não processados, 'structured' retorna dados organizados com agrupamentos, resumos e breakdown por categorias.
</ParamField>

<ParamField query="clientMessage" type="string" required="false">
  Mensagem em linguagem natural para filtragem inteligente usando LLM. Permite filtrar transações baseado na intenção expressa na mensagem (ex: "mostre gastos com alimentação", "transações acima de 100 reais", "pagamentos para supermercados").
</ParamField>

## Resposta

### Sucesso (200) - Formato Raw (Padrão)

<ResponseExample>
  ```json Success Raw Format theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "txn_123456789",
        "description": "Pagamento de conta de luz",
        "category": "Contas",
        "currency_code": "BRL",
        "amount": -150.00,
        "balance": 1350.50,
        "date": "2024-01-15",
        "type": "DEBIT",
        "status": "POSTED",
        "account_name": "Conta Corrente",
        "account_type": "BANK",
        "account_subtype": "CHECKING_ACCOUNT",
        "account_marketing_name": "Nubank Conta"
      },
      {
        "id": "txn_987654321",
        "description": "Depósito salário",
        "category": "Receitas",
        "currency_code": "BRL",
        "amount": 3000.00,
        "balance": 4500.50,
        "date": "2024-01-10",
        "type": "CREDIT",
        "status": "POSTED",
        "account_name": "Conta Corrente",
        "account_type": "BANK",
        "account_subtype": "CHECKING_ACCOUNT",
        "account_marketing_name": "Nubank Conta"
      }
    ],
    "count": 2,
    "filters": {
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "categories": ["Contas", "Receitas"],
      "minAmount": -500,
      "maxAmount": 5000,
      "accountType": "BANK",
      "accountSubtype": "CHECKING_ACCOUNT",
      "format": "raw"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

### Sucesso (200) - Formato Structured

<ResponseExample>
  ```json Success Structured Format theme={null}
  {
    "success": true,
    "data": {
      "transactions": {
        "accounts": {
          "Nubank": {
            "credit_cards": {
              "Nubank Mastercard": {
                "payments": [
                  {
                    "date": "2024-01-15",
                    "category": "Pagamento de Fatura",
                    "amount": 1523.75,
                    "currency": "BRL",
                    "account_info": {
                      "name": "Nubank",
                      "type": "CREDIT",
                      "subtype": "CREDIT_CARD",
                      "brand": "MASTERCARD",
                      "level": "Gold",
                      "status": "ACTIVE"
                    },
                    "type": "DEBIT",
                    "merchant": "Pagamento da Fatura",
                    "description": "Pagamento de fatura do cartão",
                    "transaction_type": "credit_card",
                    "transaction_subtype": "payment"
                  }
                ],
                "purchases": [
                  {
                    "date": "2024-01-10",
                    "category": "Alimentação",
                    "amount": 125.50,
                    "currency": "BRL",
                    "account_info": {
                      "name": "Nubank",
                      "type": "CREDIT",
                      "subtype": "CREDIT_CARD",
                      "brand": "MASTERCARD",
                      "level": "Gold",
                      "status": "ACTIVE"
                    },
                    "type": "DEBIT",
                    "merchant": "Supermercado Exemplo",
                    "description": "Compra no supermercado",
                    "transaction_type": "credit_card",
                    "transaction_subtype": "purchase"
                  }
                ],
                "total_payments": 1523.75,
                "total_purchases": 125.50
              }
            },
            "total_credit_card_payments": 1523.75,
            "total_credit_card_purchases": 125.50,
            "total_bank_transfer": 0,
            "total_received": 0
          }
        }
      },
      "summary": {
        "total_spent": 125.50,
        "total_received": 0,
        "total_bank_transfer": 0,
        "period": "1 mês",
        "by_category": {
          "Alimentação": {
            "total": 125.50,
            "count": 1
          }
        },
        "top_transactions": [
          {
            "date": "2024-01-10",
            "category": "Alimentação",
            "amount": 125.50,
            "currency": "BRL",
            "account_info": {
              "name": "Nubank",
              "type": "CREDIT",
              "subtype": "CREDIT_CARD"
            },
            "type": "DEBIT",
            "merchant": "Supermercado Exemplo",
            "description": "Compra no supermercado",
            "transaction_type": "credit_card",
            "transaction_subtype": "purchase"
          }
        ]
      }
    },
    "count": 2,
    "filters": {
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "categories": null,
      "minAmount": null,
      "maxAmount": null,
      "accountType": null,
      "accountSubtype": null,
      "format": "structured"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

### Erro de Parâmetros Inválidos (400)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "Invalid accountType",
    "message": "Invalid accountType provided",
    "received": "INVALID_TYPE"
  }
  ```
</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|object" required>
  Dados das transações. Formato varia conforme parâmetro `format`:

  * `format=raw` (padrão): Array com transações financeiras brutas
  * `format=structured`: Objeto com transações organizadas, agrupamentos e resumos

  <Expandable title="Transaction Object">
    <ResponseField name="id" type="string" required>
      Identificador único da transação
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Descrição da transação
    </ResponseField>

    <ResponseField name="category" type="string">
      Categoria da transação (pode ser null)
    </ResponseField>

    <ResponseField name="currency_code" type="string" required>
      Código da moeda da transação (ex: BRL, USD)
    </ResponseField>

    <ResponseField name="amount" type="number" required>
      Valor da transação (negativo para débitos, positivo para créditos)
    </ResponseField>

    <ResponseField name="balance" type="number">
      Saldo da conta após a transação (pode ser null)
    </ResponseField>

    <ResponseField name="date" type="string" required>
      Data da transação no formato YYYY-MM-DD
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Tipo da transação (DEBIT, CREDIT)
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status da transação (POSTED, PENDING)
    </ResponseField>

    <ResponseField name="account_name" type="string" required>
      Nome da conta onde ocorreu a transação
    </ResponseField>

    <ResponseField name="account_type" type="string" required>
      Tipo da conta (BANK, CREDIT)
    </ResponseField>

    <ResponseField name="account_subtype" type="string" required>
      Subtipo da conta (SAVINGS\_ACCOUNT, CHECKING\_ACCOUNT, CREDIT\_CARD)
    </ResponseField>

    <ResponseField name="account_marketing_name" type="string" required>
      Nome de marketing da conta
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number" required>
  Número total de transações retornadas
</ResponseField>

<ResponseField name="filters" type="object" required>
  Objeto com os filtros aplicados na requisição

  <Expandable title="Filters Object">
    <ResponseField name="startDate" type="string">
      Data inicial do filtro
    </ResponseField>

    <ResponseField name="endDate" type="string">
      Data final do filtro
    </ResponseField>

    <ResponseField name="categories" type="array">
      Array de categorias filtradas
    </ResponseField>

    <ResponseField name="minAmount" type="number">
      Valor mínimo filtrado
    </ResponseField>

    <ResponseField name="maxAmount" type="number">
      Valor máximo filtrado
    </ResponseField>

    <ResponseField name="accountType" type="string">
      Tipo de conta filtrado
    </ResponseField>

    <ResponseField name="accountSubtype" type="string">
      Subtipo de conta filtrado
    </ResponseField>

    <ResponseField name="format" type="string">
      Formato usado na resposta (raw ou structured)
    </ResponseField>
  </Expandable>
</ResponseField>

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

## Formato Structured

Quando `format=structured`, o campo `data` contém um objeto com:

<ResponseField name="transactions" type="object" required>
  Transações agrupadas por conta e tipo

  <Expandable title="Transactions Structure">
    <ResponseField name="accounts" type="object">
      Mapa de nomes de contas para seus grupos de transação

      <Expandable title="Account Structure">
        <ResponseField name="credit_cards" type="object">
          Transações de cartão de crédito agrupadas por cartão
        </ResponseField>

        <ResponseField name="bank_transfer" type="array">
          Transações de transferência bancária
        </ResponseField>

        <ResponseField name="received" type="array">
          Transações de dinheiro recebido
        </ResponseField>

        <ResponseField name="total_credit_card_payments" type="number">
          Total de pagamentos de cartão para esta conta
        </ResponseField>

        <ResponseField name="total_credit_card_purchases" type="number">
          Total de compras de cartão para esta conta
        </ResponseField>

        <ResponseField name="total_bank_transfer" type="number">
          Total de transferências bancárias
        </ResponseField>

        <ResponseField name="total_received" type="number">
          Total recebido
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object" required>
  Estatísticas resumidas das transações

  <Expandable title="Summary Structure">
    <ResponseField name="total_spent" type="number">
      Total gasto (compras + transferências, excluindo pagamentos de fatura)
    </ResponseField>

    <ResponseField name="total_received" type="number">
      Total recebido
    </ResponseField>

    <ResponseField name="total_bank_transfer" type="number">
      Total de transferências bancárias
    </ResponseField>

    <ResponseField name="period" type="string">
      Descrição do período coberto
    </ResponseField>

    <ResponseField name="by_category" type="object">
      Top 10 categorias por valor gasto
    </ResponseField>

    <ResponseField name="top_transactions" type="array">
      Top 10 transações por valor
    </ResponseField>
  </Expandable>
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# Obter todas as transações
curl -X GET 'https://www.pierre.finance/tools/api/get-transactions' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Obter transações de um período específico
curl -X GET 'https://www.pierre.finance/tools/api/get-transactions?startDate=2024-01-01&endDate=2024-01-31' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Obter transações por categoria
curl -X GET 'https://www.pierre.finance/tools/api/get-transactions?categories=Contas,Alimentação' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Obter transações por valor
curl -X GET 'https://www.pierre.finance/tools/api/get-transactions?minAmount=100&maxAmount=1000' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Obter transações em formato estruturado
curl -X GET 'https://www.pierre.finance/tools/api/get-transactions?format=structured' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Filtragem inteligente com linguagem natural
curl -X GET 'https://www.pierre.finance/tools/api/get-transactions?clientMessage=mostre%20gastos%20com%20alimentação%20acima%20de%2050%20reais' \
  -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 getTransactions(filters = {}) {
  const params = new URLSearchParams(filters);
  const response = await fetch(`${BASE_URL}/get-transactions?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplos de uso
getTransactions({ startDate: '2024-01-01', endDate: '2024-01-31' });
getTransactions({ categories: 'Contas,Alimentação' });
getTransactions({ minAmount: 100, maxAmount: 1000 });
getTransactions({ format: 'structured' }); // Dados organizados com resumos
getTransactions({ clientMessage: 'mostre gastos com supermercados' }); // Filtragem inteligente
```

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

# Exemplos de uso
transactions = get_transactions({
    'startDate': '2024-01-01',
    'endDate': '2024-01-31'
})

transactions = get_transactions({
    'categories': 'Contas,Alimentação'
})

transactions = get_transactions({
    'minAmount': 100,
    'maxAmount': 1000
})

# Obter dados estruturados com resumos
structured_data = get_transactions({
    'format': 'structured',
    'startDate': '2024-01-01'
})

# Filtragem inteligente com linguagem natural
smart_filtered = get_transactions({
    'clientMessage': 'gastos com alimentação dos últimos 30 dias',
    'format': 'structured'
})
```

## Códigos de Status

* `200`: Sucesso - Transações retornadas
* `400`: Parâmetros inválidos
* `401`: Erro de autenticação ou assinatura
* `500`: Erro interno do servidor

## Funcionalidades Avançadas

### Filtragem Inteligente (clientMessage)

Use linguagem natural para filtrar transações. Exemplos:

* `"gastos com alimentação"` - Encontra transações de restaurantes, supermercados, etc.
* `"transações acima de 100 reais"` - Filtra por valor automaticamente
* `"pagamentos do mês passado"` - Combina período e tipo de transação

### Formato de Resposta

* **`format=raw`** (padrão): Retorna array de transações brutas, ideal para processamento personalizado
* **`format=structured`**: Retorna dados organizados com:
  * Agrupamento por conta e tipo de transação
  * Separação inteligente entre pagamentos e compras
  * Resumos e estatísticas automáticas
  * Top transações e breakdown por categoria
  * Ideal para análises, relatórios e dashboards

<Note>
  Este endpoint retorna dados em tempo real das transações conectadas. Para dados mais recentes, use o endpoint de sincronização manual. Use `format=structured` para análises financeiras avançadas.
</Note>


## OpenAPI

````yaml GET /tools/api/get-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-transactions:
    get:
      tags:
        - Transactions
      description: >-
        Retrieves the user's financial transaction history within a specific
        period with intelligent filtering and automatic categorization. Supports
        filtering by account type, transaction type, category, amount ranges,
        and natural language queries via clientMessage parameter. Applies two
        processing stages: 1) LLM-powered intelligent filtering (when
        clientMessage is provided), 2) Automatic transaction categorization
        (always applied). Supports two response formats: 'raw' (default) for
        unprocessed data, and 'structured' for organized data with groupings and
        summaries. Requires API key for authentication and active subscription.
      operationId: getTransactions
      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
        - 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
        - name: categories
          in: query
          required: false
          schema:
            type: string
            description: Comma-separated list of category names to filter by
          description: Categories to filter by (comma-separated)
        - name: minAmount
          in: query
          required: false
          schema:
            type: number
            description: Minimum amount to filter by
          description: Minimum amount to filter by
        - name: maxAmount
          in: query
          required: false
          schema:
            type: number
            description: Maximum amount to filter by
          description: Maximum amount to filter by
        - name: accountType
          in: query
          required: false
          schema:
            type: string
            enum:
              - BANK
              - CREDIT
              - INVESTMENT
              - LOAN
            description: Account type to filter by
          description: Account type to filter by
        - name: accountSubtype
          in: query
          required: false
          schema:
            type: string
            enum:
              - CHECKING_ACCOUNT
              - SAVINGS_ACCOUNT
              - CREDIT_CARD
              - PAYMENT_ACCOUNT
            description: Account subtype to filter by
          description: Account subtype to filter by
        - name: includeStatus
          in: query
          required: false
          schema:
            type: string
            description: >-
              Comma-separated list of transaction statuses to include (POSTED,
              PENDING)
          description: Transaction statuses to include (comma-separated)
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - raw
              - structured
            default: raw
            description: >-
              Response format: 'raw' returns unprocessed transaction data
              (default), 'structured' returns organized data with groupings,
              summaries, and category breakdowns.
          description: 'Response format type (default: raw)'
        - name: clientMessage
          in: query
          required: false
          schema:
            type: string
            description: >-
              Natural language message to apply intelligent filtering using LLM.
              When provided, filters transactions based on the intent expressed
              in the message (e.g., 'show me food expenses', 'transactions over
              100 reais', 'payments to supermarkets').
          description: Intelligent filter message for LLM-powered transaction filtering
      responses:
        '200':
          description: List of transactions (format depends on 'format' parameter)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    oneOf:
                      - type: array
                        description: >-
                          Raw transaction data (when format=raw or not
                          specified)
                        items:
                          $ref: '#/components/schemas/Transaction'
                      - $ref: '#/components/schemas/FriendlyTransactionData'
                        description: Structured formatted data (when format=structured)
                  count:
                    type: number
                    example: 150
                    description: Total number of raw transactions
                  totalBeforeFilter:
                    type: number
                    nullable: true
                    description: >-
                      Total number of transactions before intelligent filtering
                      (only present when clientMessage is used)
                    example: 250
                  clientMessageUsed:
                    type: string
                    nullable: true
                    description: >-
                      The client message used for intelligent filtering (only
                      present when clientMessage is provided)
                    example: show me food expenses over 50 reais
                  message:
                    type: string
                    description: >-
                      Descriptive message about the filtering results and
                      processing applied
                    example: >-
                      Encontradas 150 transações (de 250 totais após aplicar
                      filtro inteligente baseado na sua mensagem). Os dados
                      foram estruturados para facilitar a análise.
                  filters:
                    type: object
                    properties:
                      startDate:
                        type: string
                      endDate:
                        type: string
                      categories:
                        type: array
                        items:
                          type: string
                      minAmount:
                        type: number
                      maxAmount:
                        type: number
                      accountType:
                        type: string
                      accountSubtype:
                        type: string
                      format:
                        type: string
                        enum:
                          - raw
                          - structured
                        description: Indicates the format used for the response data
                      clientMessage:
                        type: string
                        nullable: true
                        description: >-
                          The client message used for intelligent filtering
                          (null if not provided)
                        example: show me food expenses over 50 reais
                  timestamp:
                    type: string
                    format: date-time
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid accountType
                  message:
                    type: string
                  received:
                    type: string
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    Transaction: {}
    FriendlyTransactionData: {}
    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'

````