cURL

curl --request GET \
  --url https://www.pierre.finance/tools/api/get-transactions \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.pierre.finance/tools/api/get-transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.pierre.finance/tools/api/get-transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.pierre.finance/tools/api/get-transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.pierre.finance/tools/api/get-transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

Transactions

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.

GET

tools

api

get-transactions

cURL

curl --request GET \
  --url https://www.pierre.finance/tools/api/get-transactions \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.pierre.finance/tools/api/get-transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.pierre.finance/tools/api/get-transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.pierre.finance/tools/api/get-transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.pierre.finance/tools/api/get-transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

Filtragem Inteligente via LLM: Use o parâmetro clientMessage para filtrar transações com linguagem natural
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.

string

required

Bearer token com a API key do usuário. Formato: Bearer sk-your-api-key-here

Parâmetros de Query

string

required

Data inicial para filtrar transações (formato YYYY-MM-DD). Se não fornecido, usa 3 meses atrás como padrão.

string

required

Data final para filtrar transações (formato YYYY-MM-DD). Se não fornecido, usa hoje como padrão.

string

required

Lista de categorias separadas por vírgula para filtrar transações.

number

required

Valor mínimo das transações para filtrar.

number

required

Valor máximo das transações para filtrar.

string

required

Tipo de conta para filtrar. Valores válidos: BANK, CREDIT, INVESTMENT, LOAN

string

required

Subtipo de conta para filtrar. Valores válidos: CHECKING_ACCOUNT, SAVINGS_ACCOUNT, CREDIT_CARD, PAYMENT_ACCOUNT

string

required

Status de transação. Valores válidos: POSTED, PENDING

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.

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

boolean

required

Indica se a requisição foi bem-sucedida

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

Show Transaction Object

string

required

Identificador único da transação

string

required

Descrição da transação

string

Categoria da transação (pode ser null)

string

required

Código da moeda da transação (ex: BRL, USD)

number

required

Valor da transação (negativo para débitos, positivo para créditos)

number

Saldo da conta após a transação (pode ser null)

string

required

Data da transação no formato YYYY-MM-DD

string

required

Tipo da transação (DEBIT, CREDIT)

string

required

Status da transação (POSTED, PENDING)

string

required

Nome da conta onde ocorreu a transação

string

required

Tipo da conta (BANK, CREDIT)

string

required

Subtipo da conta (SAVINGS_ACCOUNT, CHECKING_ACCOUNT, CREDIT_CARD)

string

required

Nome de marketing da conta

number

required

Número total de transações retornadas

object

required

Objeto com os filtros aplicados na requisição

Show Filters Object

string

Data inicial do filtro

string

Data final do filtro

array

Array de categorias filtradas

number

Valor mínimo filtrado

number

Valor máximo filtrado

string

Tipo de conta filtrado

string

Subtipo de conta filtrado

string

Formato usado na resposta (raw ou structured)

string

required

Timestamp da requisição em formato ISO 8601

Formato Structured

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

object

required

Transações agrupadas por conta e tipo

Show Transactions Structure

object

Mapa de nomes de contas para seus grupos de transação

Show Account Structure

object

Transações de cartão de crédito agrupadas por cartão

array

Transações de transferência bancária

array

Transações de dinheiro recebido

number

Total de pagamentos de cartão para esta conta

number

Total de compras de cartão para esta conta

number

Total de transferências bancárias

number

Total recebido

object

required

Estatísticas resumidas das transações

Show Summary Structure

number

Total gasto (compras + transferências, excluindo pagamentos de fatura)

number

Total recebido

number

Total de transferências bancárias

string

Descrição do período coberto

object

Top 10 categorias por valor gasto

array

Top 10 transações por valor

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)

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

Show child attributes

timestamp

string<date-time>

Getting Started

Accounts & Balance

Transactions

Credit Cards

Spending Limits

Payment Reminders

Analytics

Memories

Open Finance

Synchronization

MCP Server

Get Transactions

Descrição

Autenticação

Parâmetros de Query

Resposta

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

Sucesso (200) - Formato Structured

Erro de Parâmetros Inválidos (400)

Erro de Autenticação (401)

Campos da Resposta

Formato Structured

Exemplos de Uso

cURL

JavaScript

Python

Códigos de Status

Funcionalidades Avançadas

Filtragem Inteligente (clientMessage)

Formato de Resposta

Authorizations

Query Parameters

Response

​Descrição

​Autenticação

​Parâmetros de Query

​Resposta

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

​Sucesso (200) - Formato Structured

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

​Erro de Autenticação (401)

​Campos da Resposta

​Formato Structured

​Exemplos de Uso

​cURL

​JavaScript

​Python

​Códigos de Status

​Funcionalidades Avançadas

​Filtragem Inteligente (clientMessage)

​Formato de Resposta

Authorizations

Query Parameters

Response

Descrição

Autenticação

Parâmetros de Query

Resposta

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

Sucesso (200) - Formato Structured

Erro de Parâmetros Inválidos (400)

Erro de Autenticação (401)

Campos da Resposta

Formato Structured

Exemplos de Uso

cURL

JavaScript

Python

Códigos de Status

Funcionalidades Avançadas

Filtragem Inteligente (clientMessage)

Formato de Resposta