Skip to main content
GET
/
tools
/
api
/
get-bill-summary
cURL
curl --request GET \
  --url https://www.pierre.finance/tools/api/get-bill-summary \
  --header 'Authorization: Bearer <token>'
{
  "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:
  1. Período Personalizado: Use startDate e endDate para definir um período específico
  2. Dia de Fechamento Manual: Use closingDay (1-31) junto com accountId para especificar um dia de fechamento
  3. 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.
​
Authorization
string
required
Bearer token com a API key do usuário. Formato: Bearer sk-your-api-key-here

​
Parâmetros de Query

​
accountId
string
required
ID da conta de cartão de crédito para filtrar o cálculo (opcional)
​
closingDay
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.
​
startDate
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
​
endDate
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

​
success
boolean
required
Indica se a requisição foi bem-sucedida
​
data
array
required
Lista de resumos por conta de cartão de crédito
​
recommendations
string
Mensagens com recomendações (ex.: ausência de closingDay e sugestão de uso do manage-closing-date).
​
transactionsInfo
string
required
Informação sobre o número de transações consideradas no cálculo
​
notice
string
required
Aviso sobre valor aproximado e possíveis atrasos de sincronização
​
guidance
string
required
Orientação para usar get-bills em casos de faturas já fechadas/vencidas
​
filters
object
Filtros aplicados na consulta (ex.: accountId, closingDay, startDate, endDate)
​
timestamp
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)

​
timestamp
string<date-time>

Timestamp da requisição em formato ISO 8601

Example:

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