Skip to main content
GET
/
tools
/
api
/
get-transactions
cURL
curl --request GET \
  --url https://www.pierre.finance/tools/api/get-transactions \
  --header 'Authorization: Bearer <token>'
{
  "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"
}
Este endpoint retorna transações financeiras do usuário autenticado com filtros opcionais.

​
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.
​
Authorization
string
required
Bearer token com a API key do usuário. Formato: Bearer sk-your-api-key-here

​
Parâmetros de Query

​
startDate
string
required
Data inicial para filtrar transações (formato YYYY-MM-DD). Se não fornecido, usa 3 meses atrás como padrão.
​
endDate
string
required
Data final para filtrar transações (formato YYYY-MM-DD). Se não fornecido, usa hoje como padrão.
​
categories
string
required
Lista de categorias separadas por vírgula para filtrar transações.
​
minAmount
number
required
Valor mínimo das transações para filtrar.
​
maxAmount
number
required
Valor máximo das transações para filtrar.
​
accountType
string
required
Tipo de conta para filtrar. Valores válidos: BANK, CREDIT, INVESTMENT, LOAN
​
accountSubtype
string
required
Subtipo de conta para filtrar. Valores válidos: CHECKING_ACCOUNT, SAVINGS_ACCOUNT, CREDIT_CARD, PAYMENT_ACCOUNT
​
includeStatus
string
required
Status de transação. Valores válidos: POSTED, PENDING
​
format
string
required
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.
​
clientMessage
string
required
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”).

​
Resposta

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

{
  "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"
}

​
Sucesso (200) - Formato Structured

{
  "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"
}

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

{
  "error": "Invalid accountType",
  "message": "Invalid accountType provided",
  "received": "INVALID_TYPE"
}

​
Erro de Autenticação (401)

{
  "error": "Invalid or inactive API key",
  "message": "Please check your API key and try again",
  "type": "invalid_api_key"
}

​
Campos da Resposta

​
success
boolean
required
Indica se a requisição foi bem-sucedida
​
data
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
​
count
number
required
Número total de transações retornadas
​
filters
object
required
Objeto com os filtros aplicados na requisição
​
timestamp
string
required
Timestamp da requisição em formato ISO 8601

​
Formato Structured

Quando format=structured, o campo data contém um objeto com:
​
transactions
object
required
Transações agrupadas por conta e tipo
​
summary
object
required
Estatísticas resumidas das transações

​
Exemplos de Uso

​
cURL

# 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

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

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

Authorizations

​
Authorization
string
header
required

API key in Bearer token format. Example: Bearer sk-your-api-key-here

Query Parameters

​
startDate
string<date>

Start date for filtering Start date for filtering (YYYY-MM-DD format)

​
endDate
string<date>

End date for filtering End date for filtering (YYYY-MM-DD format)

​
categories
string

Categories to filter by (comma-separated) Comma-separated list of category names to filter by

​
minAmount
number

Minimum amount to filter by

​
maxAmount
number

Maximum amount to filter by

​
accountType
enum<string>

Account type to filter by

Available options:
BANK,
CREDIT,
INVESTMENT,
LOAN
​
accountSubtype
enum<string>

Account subtype to filter by

Available options:
CHECKING_ACCOUNT,
SAVINGS_ACCOUNT,
CREDIT_CARD,
PAYMENT_ACCOUNT
​
includeStatus
string

Transaction statuses to include (comma-separated) Comma-separated list of transaction statuses to include (POSTED, PENDING)

​
format
enum<string>
default:raw

Response format type (default: raw) Response format: 'raw' returns unprocessed transaction data (default), 'structured' returns organized data with groupings, summaries, and category breakdowns.

Available options:
raw,
structured
​
clientMessage
string

Intelligent filter message for LLM-powered transaction filtering 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').

Response

List of transactions (format depends on 'format' parameter)

​
success
boolean
Example:

true

​
data

Raw transaction data (when format=raw or not specified)

​
count
number

Total number of raw transactions

Example:

150

​
totalBeforeFilter
number | null

Total number of transactions before intelligent filtering (only present when clientMessage is used)

Example:

250

​
clientMessageUsed
string | null

The client message used for intelligent filtering (only present when clientMessage is provided)

Example:

"show me food expenses over 50 reais"

​
message
string

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
object
​
timestamp
string<date-time>