cURL
curl --request GET \
--url https://www.pierre.finance/tools/api/get-transactions \
--header 'Authorization: Bearer <token>'import requests
url = "https://www.pierre.finance/tools/api/get-transactions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)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))
}HttpResponse<String> response = Unirest.get("https://www.pierre.finance/tools/api/get-transactions")
.header("Authorization", "Bearer <token>")
.asString();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>'import requests
url = "https://www.pierre.finance/tools/api/get-transactions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)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))
}HttpResponse<String> response = Unirest.get("https://www.pierre.finance/tools/api/get-transactions")
.header("Authorization", "Bearer <token>")
.asString();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 endpointGET /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
clientMessagepara filtrar transações com linguagem natural - Categorização Automática: Todas as transações são categorizadas automaticamente por IA
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-hereParâ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 brutasformat=structured: Objeto com transações organizadas, agrupamentos e resumos
Show Transaction Object
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
string
required
Timestamp da requisição em formato ISO 8601
Formato Structured
Quandoformat=structured, o campo data contém um objeto com:
object
required
Transações agrupadas por conta e tipo
Show Transactions Structure
Show Transactions Structure
object
Mapa de nomes de contas para seus grupos de transação
Show Account Structure
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
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 retornadas400: Parâmetros inválidos401: Erro de autenticação ou assinatura500: 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 personalizadoformat=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
API key in Bearer token format. Example: Bearer sk-your-api-key-here
Query Parameters
Start date for filtering Start date for filtering (YYYY-MM-DD format)
End date for filtering End date for filtering (YYYY-MM-DD format)
Categories to filter by (comma-separated) Comma-separated list of category names to filter by
Minimum amount to filter by
Maximum amount to filter by
Account type to filter by
Available options:
BANK, CREDIT, INVESTMENT, LOAN Account subtype to filter by
Available options:
CHECKING_ACCOUNT, SAVINGS_ACCOUNT, CREDIT_CARD, PAYMENT_ACCOUNT Transaction statuses to include (comma-separated) Comma-separated list of transaction statuses to include (POSTED, PENDING)
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 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)
Example:
true
Raw transaction data (when format=raw or not specified)
Total number of raw transactions
Example:
150
Total number of transactions before intelligent filtering (only present when clientMessage is used)
Example:
250
The client message used for intelligent filtering (only present when clientMessage is provided)
Example:
"show me food expenses over 50 reais"
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."
Show child attributes
Show child attributes