> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pierre.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Bill Summary

> 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. Requer API key para autenticação e assinatura ativa.

<Note>
  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`.
</Note>

## 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.

<ParamField header="Authorization" type="string" required>
  Bearer token com a API key do usuário. Formato: `Bearer sk-your-api-key-here`
</ParamField>

## Parâmetros de Query

<ParamField query="accountId" type="string" required="false">
  ID da conta de cartão de crédito para filtrar o cálculo (opcional)
</ParamField>

<ParamField query="closingDay" type="integer" required="false">
  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.
</ParamField>

<ParamField query="startDate" type="string" required="false">
  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`
</ParamField>

<ParamField query="endDate" type="string" required="false">
  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`
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

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

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid or inactive API key",
    "type": "invalid_api_key"
  }
  ```
</ResponseExample>

### Erro Interno (500)

<ResponseExample>
  ```json 500 Internal Server Error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>

## Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="data" type="array" required>
  Lista de resumos por conta de cartão de crédito

  <Expandable title="Bill Summary Object">
    <ResponseField name="account_id" type="string" required>
      ID da conta de cartão de crédito
    </ResponseField>

    <ResponseField name="account_name" type="string" required>
      Nome da conta de cartão de crédito
    </ResponseField>

    <ResponseField name="currency_code" type="string" required>
      Código da moeda (ex: BRL)
    </ResponseField>

    <ResponseField name="credit_limit" type="number">
      Limite total do cartão
    </ResponseField>

    <ResponseField name="available_credit_limit" type="number">
      Limite disponível para uso
    </ResponseField>

    <ResponseField name="closing_day" type="number">
      Dia de fechamento considerado para o período (quando disponível)
    </ResponseField>

    <ResponseField name="period_start" type="string" required>
      Data/hora de início do período atual (ISO 8601)
    </ResponseField>

    <ResponseField name="period_end" type="string" required>
      Data/hora de fim do período atual (ISO 8601)
    </ResponseField>

    <ResponseField name="approx_current_bill_amount" type="number" required>
      Valor aproximado da fatura (soma de transações DEBIT com status PENDING no período)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recommendations" type="string">
  Mensagens com recomendações (ex.: ausência de `closingDay` e sugestão de uso do `manage-closing-date`).
</ResponseField>

<ResponseField name="transactionsInfo" type="string" required>
  Informação sobre o número de transações consideradas no cálculo
</ResponseField>

<ResponseField name="notice" type="string" required>
  Aviso sobre valor aproximado e possíveis atrasos de sincronização
</ResponseField>

<ResponseField name="guidance" type="string" required>
  Orientação para usar `get-bills` em casos de faturas já fechadas/vencidas
</ResponseField>

<ResponseField name="filters" type="object">
  Filtros aplicados na consulta (ex.: `accountId`, `closingDay`, `startDate`, `endDate`)

  <Expandable title="Filters Object">
    <ResponseField name="accountId" type="string">
      ID da conta filtrada
    </ResponseField>

    <ResponseField name="closingDay" type="number">
      Dia de fechamento usado
    </ResponseField>

    <ResponseField name="startDate" type="string">
      Data de início do período
    </ResponseField>

    <ResponseField name="endDate" type="string">
      Data de fim do período
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  Timestamp da requisição em formato ISO 8601
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# 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

```javascript theme={null}
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

```python theme={null}
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'
)
```


## OpenAPI

````yaml GET /tools/api/get-bill-summary
openapi: 3.1.0
info:
  title: Pierre Finance API
  description: >-
    API para acessar dados financeiros do Pierre Finance, incluindo contas,
    transações, parcelas e sincronização.
  version: v1.0.0
servers:
  - url: https://www.pierre.finance
security: []
tags:
  - name: Authentication
    description: API key management and authentication
  - name: Accounts
    description: Financial accounts management
  - name: Transactions
    description: Financial transactions
  - name: Installments
    description: Credit card installments and purchases
  - name: Bills
    description: Credit card bills and current bill summaries
  - name: Balance
    description: Account balance information
  - name: Closing Dates
    description: Credit card closing date management
  - name: Sync
    description: Account synchronization
  - name: Spending Limits
    description: Personal spending limits and alerts management
  - name: Payment Reminders
    description: Payment reminders management with WhatsApp and Email notifications
  - name: Analytics
    description: Financial analytics and insights
  - name: Memories
    description: User memory management for personalized AI interactions
  - name: Open Finance
    description: Open Finance connection and integration
paths:
  /tools/api/get-bill-summary:
    get:
      tags:
        - Bills
      description: >-
        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. Requer API key para autenticação e assinatura
        ativa.
      operationId: getBillSummary
      parameters:
        - name: accountId
          in: query
          description: ID da conta de cartão de crédito para filtrar o cálculo (opcional)
          required: false
          schema:
            type: string
        - name: closingDay
          in: query
          description: >-
            Dia de fechamento manual (1–31). Se informado junto com accountId,
            será usado no cálculo deste cartão.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 31
        - name: startDate
          in: query
          description: >-
            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.
          required: false
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: >-
            Data de fim do período para cálculo da fatura (formato ISO 8601).
            Sobrescreve o cálculo automático baseado no closing day.
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Resumo da fatura corrente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indica se a requisição foi bem-sucedida
                    example: true
                  data:
                    type: array
                    description: Resumo da fatura corrente de cartão de crédito
                    items:
                      $ref: '#/components/schemas/BillSummary'
                  recommendations:
                    type: string
                    nullable: true
                    description: >-
                      Mensagens com recomendações (ex.: ausência de closingDay e
                      sugestão de uso do manage-closing-date)
                  transactionsInfo:
                    type: string
                    description: >-
                      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:
                    type: string
                    description: >-
                      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:
                    type: string
                    description: >-
                      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:
                    type: object
                    description: >-
                      Filtros aplicados na consulta (ex.: accountId, closingDay,
                      startDate, endDate)
                    properties:
                      accountId:
                        type: string
                        nullable: true
                        description: ID da conta filtrada
                      closingDay:
                        type: integer
                        nullable: true
                        description: Dia de fechamento usado
                      startDate:
                        type: string
                        format: date-time
                        nullable: true
                        description: Data de início do período
                      endDate:
                        type: string
                        format: date-time
                        nullable: true
                        description: Data de fim do período
                  timestamp:
                    type: string
                    format: date-time
                    description: Timestamp da requisição em formato ISO 8601
                    example: '2024-05-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    BillSummary: {}
    AuthError: {}
    ServerError: {}
  responses:
    AuthError:
      description: Authentication or subscription error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: 'API key in Bearer token format. Example: Bearer sk-your-api-key-here'

````