Get Bill Summary

cURL

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

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

fetch('https://www.pierre.finance/tools/api/get-bill-summary', 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-bill-summary",
  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-bill-summary"

	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-bill-summary")

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": [
    {
      "account_id": "acc_abc",
      "account_name": "Cartão Nubank",
      "currency_code": "BRL",
      "credit_limit": 10000,
      "available_credit_limit": 7500,
      "closing_day": 10,
      "period_start": "2024-05-10T00:00:00.000Z",
      "period_end": "2024-06-10T00:00:00.000Z",
      "approx_current_bill_amount": 1523.75
    }
  ],
  "recommendations": "Não encontramos data de fechamento cadastrada para este cartão. Usamos como referência 7 dias antes do vencimento (2024-06-17), equivalente ao dia 10. Considere cadastrar a data exata com manage-closing-date para melhorar a precisão.",
  "transactionsInfo": "Este cálculo considerou 25 transação(ões) no período da fatura atual.",
  "notice": "O valor da fatura é aproximado. Algumas transações podem ainda não ter sido lançadas e o banco pode demorar para sincronizar.",
  "guidance": "Para faturas já fechadas/atrasadas use o endpoint get-bills. O get-bill-summary é para a fatura corrente (ainda não fechada).",
  "filters": {
    "accountId": "acc_abc",
    "closingDay": null,
    "startDate": null,
    "endDate": null
  },
  "timestamp": "2024-05-15T10:30:00Z"
}

GET

tools

api

get-bill-summary

cURL

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

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

fetch('https://www.pierre.finance/tools/api/get-bill-summary', 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-bill-summary",
  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-bill-summary"

	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-bill-summary")

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": [
    {
      "account_id": "acc_abc",
      "account_name": "Cartão Nubank",
      "currency_code": "BRL",
      "credit_limit": 10000,
      "available_credit_limit": 7500,
      "closing_day": 10,
      "period_start": "2024-05-10T00:00:00.000Z",
      "period_end": "2024-06-10T00:00:00.000Z",
      "approx_current_bill_amount": 1523.75
    }
  ],
  "recommendations": "Não encontramos data de fechamento cadastrada para este cartão. Usamos como referência 7 dias antes do vencimento (2024-06-17), equivalente ao dia 10. Considere cadastrar a data exata com manage-closing-date para melhorar a precisão.",
  "transactionsInfo": "Este cálculo considerou 25 transação(ões) no período da fatura atual.",
  "notice": "O valor da fatura é aproximado. Algumas transações podem ainda não ter sido lançadas e o banco pode demorar para sincronizar.",
  "guidance": "Para faturas já fechadas/atrasadas use o endpoint get-bills. O get-bill-summary é para a fatura corrente (ainda não fechada).",
  "filters": {
    "accountId": "acc_abc",
    "closingDay": null,
    "startDate": null,
    "endDate": null
  },
  "timestamp": "2024-05-15T10:30:00Z"
}

Este endpoint retorna o resumo da fatura atual do(s) cartão(ões) de crédito do usuário: limite total, limite disponível, período considerado e o valor aproximado da fatura (soma de transações DEBIT com status PENDING entre a última e a próxima data de fechamento).Para faturas já fechadas (vencidas), use o endpoint get-bills em vez de get-bill-summary.

Descrição

O endpoint GET /tools/api/get-bill-summary retorna o resumo da fatura atual dos cartões de crédito do usuário: limite total, limite disponível, período considerado e o valor aproximado da fatura. O cálculo é baseado em transações do tipo DEBIT e status PENDING no período corrente (do último fechamento até o próximo). O período é determinado pela data de fechamento configurada para o cartão.

Parâmetros de Período

O endpoint oferece três formas de definir o período de cálculo:

Período Personalizado: Use startDate e endDate para definir um período específico
Dia de Fechamento Manual: Use closingDay (1-31) junto com accountId para especificar um dia de fechamento
Automático: Deixe os parâmetros vazios para usar as datas de fechamento cadastradas

Regras de Fallback

Quando a data de fechamento não estiver disponível:

Se o usuário informar closingDay e accountId, o cálculo usa esse dia manualmente
Se não houver closingDay manual e a conta (via accountId) não tiver data de fechamento cadastrada, usa-se por padrão 7 dias antes da próxima data de vencimento como data de fechamento
Se não houver closingDay nem accountId, e o usuário tiver somente um cartão de crédito, usa-se 7 dias antes do vencimento para essa conta
Se houver mais de um cartão e nenhum tiver fechamento cadastrado, o endpoint retornará recomendação para cadastrar datas de fechamento

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

ID da conta de cartão de crédito para filtrar o cálculo (opcional)

integer

required

Dia de fechamento manual (1–31). Se informado junto com accountId, será usado no cálculo deste cartão. Deve ser um número inteiro entre 1 e 31.

string

required

Data de início do período para cálculo da fatura (formato ISO 8601). Sobrescreve o cálculo automático baseado no closing day. Exemplo: 2024-05-01T00:00:00Z

string

required

Data de fim do período para cálculo da fatura (formato ISO 8601). Sobrescreve o cálculo automático baseado no closing day. Exemplo: 2024-05-31T23:59:59Z

Resposta

Sucesso (200)

{
  "success": true,
  "data": [
    {
      "account_id": "acc_abc",
      "account_name": "Cartão Nubank",
      "currency_code": "BRL",
      "credit_limit": 10000,
      "available_credit_limit": 7500,
      "closing_day": 10,
      "period_start": "2024-05-10T00:00:00.000Z",
      "period_end": "2024-06-10T00:00:00.000Z",
      "approx_current_bill_amount": 1523.75
    }
  ],
  "recommendations": "Não encontramos data de fechamento cadastrada para este cartão. Usamos como referência 7 dias antes do vencimento (2024-06-17), equivalente ao dia 10. Considere cadastrar a data exata com manage-closing-date para melhorar a precisão.",
  "transactionsInfo": "Este cálculo considerou 25 transação(ões) no período da fatura atual.",
  "notice": "O valor da fatura é aproximado. Algumas transações podem ainda não ter sido lançadas e o banco pode demorar para sincronizar.",
  "guidance": "Para faturas já fechadas/atrasadas use o endpoint get-bills. O get-bill-summary é para a fatura corrente (ainda não fechada).",
  "filters": {
    "accountId": "acc_abc",
    "closingDay": null,
    "startDate": null,
    "endDate": null
  },
  "timestamp": "2024-05-15T10:30:00Z"
}

Erro de Autenticação/Assinatura (401)

{
  "error": "Invalid or inactive API key",
  "type": "invalid_api_key"
}

Erro Interno (500)

{
  "error": "Internal server error"
}

Campos da Resposta

boolean

required

Indica se a requisição foi bem-sucedida

array

required

Lista de resumos por conta de cartão de crédito

Show Bill Summary Object

string

required

ID da conta de cartão de crédito

string

required

Nome da conta de cartão de crédito

string

required

Código da moeda (ex: BRL)

number

Limite total do cartão

number

Limite disponível para uso

number

Dia de fechamento considerado para o período (quando disponível)

string

required

Data/hora de início do período atual (ISO 8601)

string

required

Data/hora de fim do período atual (ISO 8601)

number

required

Valor aproximado da fatura (soma de transações DEBIT com status PENDING no período)

string

Mensagens com recomendações (ex.: ausência de closingDay e sugestão de uso do manage-closing-date).

string

required

Informação sobre o número de transações consideradas no cálculo

string

required

Aviso sobre valor aproximado e possíveis atrasos de sincronização

string

required

Orientação para usar get-bills em casos de faturas já fechadas/vencidas

object

Filtros aplicados na consulta (ex.: accountId, closingDay, startDate, endDate)

Show Filters Object

string

ID da conta filtrada

number

Dia de fechamento usado

string

Data de início do período

string

Data de fim do período

string

required

Timestamp da requisição em formato ISO 8601

Exemplos de Uso

cURL

# Resumo da fatura atual (todas as contas)
curl -X GET 'https://www.pierre.finance/tools/api/get-bill-summary' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Resumo da fatura atual de uma conta específica
curl -X GET 'https://www.pierre.finance/tools/api/get-bill-summary?accountId=acc_abc' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Resumo com dia de fechamento manual
curl -X GET 'https://www.pierre.finance/tools/api/get-bill-summary?accountId=acc_abc&closingDay=10' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Resumo com período personalizado
curl -X GET 'https://www.pierre.finance/tools/api/get-bill-summary?accountId=acc_abc&startDate=2024-05-01T00:00:00Z&endDate=2024-05-31T23:59:59Z' \
  -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 getBillSummary({ accountId, closingDay, startDate, endDate } = {}) {
  const params = new URLSearchParams();
  if (accountId) params.set('accountId', accountId);
  if (closingDay) params.set('closingDay', String(closingDay));
  if (startDate) params.set('startDate', startDate);
  if (endDate) params.set('endDate', endDate);

  const response = await fetch(`${BASE_URL}/get-bill-summary?${params}`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  });
  return await response.json();
}

// Uso
await getBillSummary();
await getBillSummary({ accountId: 'acc_abc' });
await getBillSummary({ accountId: 'acc_abc', closingDay: 10 });
await getBillSummary({ 
  accountId: 'acc_abc', 
  startDate: '2024-05-01T00:00:00Z', 
  endDate: '2024-05-31T23:59:59Z' 
});

Python

import requests

API_KEY = 'sk-your-api-key-here'
BASE_URL = 'https://www.pierre.finance/tools/api'

headers = {
    'Authorization': f'Bearer {API_KEY}',
}

def get_bill_summary(account_id=None, closing_day=None, start_date=None, end_date=None):
    params = {}
    if account_id:
        params['accountId'] = account_id
    if closing_day:
        params['closingDay'] = closing_day
    if start_date:
        params['startDate'] = start_date
    if end_date:
        params['endDate'] = end_date
    response = requests.get(f'{BASE_URL}/get-bill-summary', headers=headers, params=params)
    return response.json()

# Uso
get_bill_summary()
get_bill_summary(account_id='acc_abc')
get_bill_summary(account_id='acc_abc', closing_day=10)
get_bill_summary(
    account_id='acc_abc', 
    start_date='2024-05-01T00:00:00Z', 
    end_date='2024-05-31T23:59:59Z'
)

Authorizations

Authorization

string

header

required

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

Query Parameters

accountId

string

ID da conta de cartão de crédito para filtrar o cálculo (opcional)

closingDay

integer

Dia de fechamento manual (1–31). Se informado junto com accountId, será usado no cálculo deste cartão.

Required range: 1 <= x <= 31

startDate

string<date-time>

Data de início do período para cálculo da fatura (formato ISO 8601). Sobrescreve o cálculo automático baseado no closing day.

endDate

string<date-time>

Data de fim do período para cálculo da fatura (formato ISO 8601). Sobrescreve o cálculo automático baseado no closing day.

Response

Resumo da fatura corrente

success

boolean

Indica se a requisição foi bem-sucedida

Example:

true

data

any[]

Resumo da fatura corrente de cartão de crédito

recommendations

string | null

Mensagens com recomendações (ex.: ausência de closingDay e sugestão de uso do manage-closing-date)

transactionsInfo

string

Informação sobre o número de transações consideradas no cálculo

Example:

"Este cálculo considerou 25 transação(ões) no período da fatura atual."

notice

string

Aviso sobre valor aproximado e possíveis atrasos de sincronização

Example:

"O valor da fatura é aproximado. Algumas transações podem ainda não ter sido lançadas e o banco pode demorar para sincronizar."

guidance

string

Orientação para usar get-bills em casos de faturas já fechadas/vencidas

Example:

"Para faturas já fechadas/atrasadas use o endpoint get-bills. O get-bill-summary é para a fatura corrente (ainda não fechada)."

filters

object

Filtros aplicados na consulta (ex.: accountId, closingDay, startDate, endDate)

Show child attributes

timestamp

string<date-time>

Timestamp da requisição em formato ISO 8601

Example:

"2024-05-15T10:30:00Z"

Getting Started

Accounts & Balance

Transactions

Credit Cards

Spending Limits

Payment Reminders

Analytics

Memories

Open Finance

Synchronization

MCP Server

Descrição

Parâmetros de Período

Regras de Fallback

Autenticação

Parâmetros de Query

Resposta

Sucesso (200)

Erro de Autenticação/Assinatura (401)

Erro Interno (500)

Campos da Resposta

Exemplos de Uso

cURL

JavaScript

Python

Authorizations

Query Parameters

Response

​Descrição

​Parâmetros de Período

​Regras de Fallback

​Autenticação

​Parâmetros de Query

​Resposta

​Sucesso (200)

​Erro de Autenticação/Assinatura (401)

​Erro Interno (500)

​Campos da Resposta

​Exemplos de Uso

​cURL

​JavaScript

​Python

Authorizations

Query Parameters

Response

Descrição

Parâmetros de Período

Regras de Fallback

Autenticação

Parâmetros de Query

Resposta

Sucesso (200)

Erro de Autenticação/Assinatura (401)

Erro Interno (500)

Campos da Resposta

Exemplos de Uso

cURL

JavaScript

Python