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

# Listar estados de cuenta

> Las cartolas de una tarjeta o las cartolas importadas de una cuenta corriente, con la misma forma, más nuevas primero.

Los estados de cuenta de una cuenta: las cartolas de una tarjeta
(`kind: "credit_card"`) o las cartolas importadas de una cuenta corriente
(`kind: "bank_account"`), con la misma forma, más nuevos primero.

```bash theme={null}
curl "https://api.tupana.ai/v2/bank-accounts/bacc_7Hk2938475610293/statements/?period=202610" \
  -H "Authorization: Api-Key TU_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "ccs_7382910465728",
      "account_id": "bacc_7Hk2938475610293",
      "kind": "credit_card",
      "period": "2026-10",
      "period_start": null,
      "period_end": "2026-10-25",
      "statement_date": "2026-10-25",
      "opening_balance": null,
      "closing_balance": 968146,
      "total_billed": 968146,
      "due_date": null,
      "minimum_payment": null,
      "items_count": 3,
      "file_url": "https://....s3.amazonaws.com/bank_statements/...?X-Amz-Expires=3600&..."
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 },
  "links": { "next": null, "prev": null }
}
```

## Qué trae

* `period` es el mes del estado de cuenta (`YYYY-MM`); `?period=YYYYMM` filtra.
* En una tarjeta, `closing_balance` y `total_billed` son lo facturado del
  período; `opening_balance` no aplica. En una cuenta corriente, `opening_balance`
  y `closing_balance` son los saldos inicial y final de la cartola y
  `total_billed` es `null`.
* `due_date` y `minimum_payment` vienen `null` hasta que la fuente los entregue.
* `items_count` es cuántos cargos o movimientos trajo.
* `file_url` es un enlace al **PDF original**, firmado por tiempo (una hora).
  Pídelo cuando lo vayas a usar; no lo guardes. `null` si no hay archivo.

Solo salen las cartolas confirmadas y vigentes: una cartola reemplazada por una
re-subida del mismo mes no aparece.


## OpenAPI

````yaml api-reference/openapi-v2.json GET /bank-accounts/{account_id}/statements/
openapi: 3.0.0
info:
  title: Tupana API — v2
  description: >-
    API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas,
    boleta de honorarios y nómina. Los identificadores de recursos son public
    IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…).
  version: 2.0.0
servers:
  - url: https://api.tupana.ai/v2
    description: Producción (v2)
security:
  - apiKeyAuth: []
paths:
  /bank-accounts/{account_id}/statements/:
    get:
      tags:
        - Estados de cuenta
      summary: Listar estados de cuenta
      description: >-
        Las cartolas de una tarjeta o las cartolas importadas de una cuenta
        corriente, con la misma forma, más nuevas primero.
      operationId: listBankAccountStatements_v2
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
            example: bacc_7Hk2938475610293
        - name: period
          in: query
          required: false
          schema:
            type: string
            pattern: ^\d{6}$
            example: '202610'
          description: Mes, `YYYYMM`.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 200
      responses:
        '200':
          description: Estados de cuenta
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Statement'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total:
                        type: integer
                      total_pages:
                        type: integer
                  links:
                    type: object
                    properties:
                      next:
                        type: string
                        nullable: true
                      prev:
                        type: string
                        nullable: true
        '400':
          description: '`period` inválido (`parameter_invalid`)'
        '403':
          description: >-
            La API key no tiene `banking:read` explícito (`code:
            banking_permission_required`)
        '404':
          description: La cuenta no existe para esta API key
      security:
        - apiKeyAuth: []
components:
  schemas:
    Statement:
      type: object
      properties:
        id:
          type: string
          example: ccs_7382910465728
          description: '`ccs_…` en una tarjeta, `bsu_…` en una cuenta corriente.'
        account_id:
          type: string
          example: bacc_7Hk2938475610293
        kind:
          type: string
          enum:
            - credit_card
            - bank_account
        period:
          type: string
          example: 2026-10
        period_start:
          type: string
          format: date
          nullable: true
        period_end:
          type: string
          format: date
          nullable: true
        statement_date:
          type: string
          format: date
          nullable: true
        opening_balance:
          type: number
          nullable: true
        closing_balance:
          type: number
          nullable: true
          description: En una tarjeta, lo facturado del período.
        total_billed:
          type: number
          nullable: true
        due_date:
          type: string
          format: date
          nullable: true
        minimum_payment:
          type: number
          nullable: true
        items_count:
          type: integer
        file_url:
          type: string
          format: uri
          nullable: true
          description: PDF original, firmado por tiempo (1 h).
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API Key para autenticación. Debe proporcionarse en el header
        Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo
        'Api-Key ' seguido de tu API key)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.