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

> Retorna faturas de cartão de crédito vencidas (apenas faturas já fechadas e com vencimento passado) do usuário autenticado. Requer API key para autenticação e assinatura ativa.

<Note>
  Este endpoint retorna faturas de cartão de crédito vencidas (apenas faturas já fechadas e com vencimento passado) do usuário autenticado. É possível filtrar por conta específica usando o parâmetro `accountId`.
</Note>

## Descrição

O endpoint `GET /tools/api/get-bills` retorna as faturas de cartão de crédito já vencidas. Se `accountId` for fornecido, retorna apenas as faturas daquela conta; caso contrário, retorna todas as faturas vencidas do usuário.

## 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 as faturas (opcional)
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "bill_123",
        "userId": "usr_123",
        "itemId": "itm_123",
        "accountId": "acc_abc",
        "dueDate": "2024-05-10T00:00:00.000Z",
        "totalAmount": 1523.75,
        "totalAmountCurrencyCode": "BRL",
        "minimumPaymentAmount": 230.00,
        "allowsInstallments": true,
        "createdAt": "2024-05-01T00:00:00.000Z",
        "updatedAt": "2024-05-01T00:00:00.000Z"
      }
    ],
    "count": 1,
    "filters": { "accountId": null, "onlyPastDue": true },
    "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 faturas de cartão de crédito vencidas

  <Expandable title="Bill Object">
    <ResponseField name="id" type="string" required>
      Identificador único da fatura
    </ResponseField>

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

    <ResponseField name="dueDate" type="string" required>
      Data de vencimento (ISO 8601)
    </ResponseField>

    <ResponseField name="totalAmount" type="number" required>
      Valor total da fatura
    </ResponseField>

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

    <ResponseField name="minimumPaymentAmount" type="number">
      Valor mínimo para pagamento
    </ResponseField>

    <ResponseField name="allowsInstallments" type="boolean">
      Indica se permite parcelamento
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number" required>
  Número de faturas retornadas
</ResponseField>

<ResponseField name="filters" type="object" required>
  Filtros aplicados na consulta
</ResponseField>

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

## Exemplos de Uso

### cURL

```bash theme={null}
# Todas as faturas vencidas do usuário
curl -X GET 'https://www.pierre.finance/tools/api/get-bills' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Faturas vencidas de uma conta específica
curl -X GET 'https://www.pierre.finance/tools/api/get-bills?accountId=acc_abc' \
  -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 getBills(accountId) {
  const params = new URLSearchParams();
  if (accountId) params.set('accountId', accountId);

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

// Uso
await getBills();
await getBills('acc_abc');
```

### 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_bills(account_id=None):
    params = {}
    if account_id:
        params['accountId'] = account_id
    response = requests.get(f'{BASE_URL}/get-bills', headers=headers, params=params)
    return response.json()

# Uso
get_bills()
get_bills('acc_abc')
```


## OpenAPI

````yaml GET /tools/api/get-bills
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-bills:
    get:
      tags:
        - Bills
      description: >-
        Retorna faturas de cartão de crédito vencidas (apenas faturas já
        fechadas e com vencimento passado) do usuário autenticado. Requer API
        key para autenticação e assinatura ativa.
      operationId: getBills
      parameters:
        - name: accountId
          in: query
          description: ID da conta de cartão de crédito para filtrar as faturas (opcional)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Lista de faturas de cartão de crédito vencidas
          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: Lista de faturas de cartão de crédito vencidas
                    items:
                      $ref: '#/components/schemas/Bill'
                  count:
                    type: number
                    description: Número de faturas retornadas
                    example: 1
                  filters:
                    type: object
                    description: Filtros aplicados na consulta
                    properties:
                      accountId:
                        type: string
                        nullable: true
                        description: ID da conta filtrada (null se não especificado)
                      onlyPastDue:
                        type: boolean
                        description: Indica que apenas faturas vencidas são retornadas
                        example: true
                  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:
    Bill: {}
    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'

````