{
  "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.",
  "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 },
  "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 calcula o valor aproximado da fatura atual com base 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. 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, e isso é informado ao usuário.
  • Se não houver closingDay nem accountId, e nenhuma conta tiver fechamento cadastrado, e o usuário tiver somente um cartão de crédito, usa-se 7 dias antes do vencimento para essa conta, com aviso de ausência de fechamento cadastrado.
  • Se houver mais de um cartão e nenhum tiver fechamento cadastrado, o endpoint retornará recomendação para cadastrar datas de fechamento (sem calcular o resumo).

​
Autenticação

Este endpoint requer autenticação via Bearer token.
​
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
number
required
Dia de fechamento manual (1–31). Se informado junto com accountId, será usado no cálculo deste cartão.

​
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.",
  "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 },
  "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).
​
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)
​
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://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://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://pierre.finance/tools/api/get-bill-summary?accountId=acc_abc&closingDay=10' \
  -H 'Authorization: Bearer sk-your-api-key-here'

​
JavaScript

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

async function getBillSummary({ accountId, closingDay } = {}) {
  const params = new URLSearchParams();
  if (accountId) params.set('accountId', accountId);
  if (closingDay) params.set('closingDay', String(closingDay));

  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 });

​
Python

import requests

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

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

def get_bill_summary(account_id=None, closing_day=None):
    params = {}
    if account_id:
        params['accountId'] = account_id
    if closing_day:
        params['closingDay'] = closing_day
    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)