> ## 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 liquidaciones de recaudación

> Lista las liquidaciones y depósitos de lo recaudado con link de pago en Tupana.

## ¿Para qué se usa?

Obtiene la lista paginada de liquidaciones (payouts) del destinatario: cada liquidación agrupa los cobros con tarjeta de un período y representa el monto neto que se depositó (o se va a depositar) al destinatario.

## Qué hace

* Retorna las liquidaciones del destinatario ordenadas por fecha de payout descendente (más reciente primero).
* Incluye totales por liquidación: bruto cobrado, comisión total (base + IVA) y neto a depositar.
* Pagina con `page` (1-indexed) y `page_size` (default 25, máximo 100).

## Estados

| Estado | Significado |
| - | - |
| `pending` | La liquidación está generada pero el depósito al banco del destinatario aún no se ejecuta. |
| `paid` | El depósito al destinatario está confirmado. `paid_at` indica cuándo. |
| `failed` | El depósito falló. Contactar a soporte si ocurre. |

## Consideraciones importantes

### Comisión

La comisión es 2% sobre el bruto de cada cobro, más 19% de IVA sobre esa comisión. Se calcula por item y luego se agrega, con redondeo hacia abajo sin decimales por item.

### Scope por API Key

La API Key debe pertenecer a un usuario con acceso a la master entity indicada en la URL. Si no, el endpoint responde `403`.


## OpenAPI

````yaml api-reference/openapi-payment-requests-v2.json GET /master-entities/{master_entity_id}/settlements/
openapi: 3.0.0
info:
  title: Tupana API - Recaudación (v2)
  description: >-
    API de Cobros — Crea sesiones de pago, procesa cobros y emite DTE
    automáticamente.
  version: 1.0.0
servers:
  - url: https://api.tupana.ai/v2
    description: Producción (v2)
security:
  - apiKeyAuth: []
paths:
  /master-entities/{master_entity_id}/settlements/:
    get:
      tags:
        - Liquidaciones
      summary: Listar liquidaciones
      description: >-
        Retorna las liquidaciones (payouts) ejecutadas y pendientes para el
        destinatario. Cada liquidación agrupa los cobros con tarjeta de un
        período y el monto neto depositado al destinatario.
      operationId: listSettlements
      parameters:
        - name: master_entity_id
          in: path
          required: true
          description: >-
            ID del destinatario (`ment_…`), el mismo `company_id` que devuelve
            `GET /v2/connections/`.
          schema:
            type: string
            example: ment_4829301923847
        - name: page
          in: query
          required: false
          description: 'Número de página (1-indexed). Por defecto: 1.'
          schema:
            type: integer
            minimum: 1
        - name: page_size
          in: query
          required: false
          description: 'Tamaño de página. Por defecto: 25, máximo: 100.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Lista paginada de liquidaciones
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementListResponse'
              example:
                data:
                  - settlement_id: sett_7719203845512
                    period_date: '2026-04-30'
                    status: paid
                    gross_total: '150000.00'
                    commission_total: '3570.00'
                    net_total: '146430.00'
                    paid_at: '2026-05-02T15:00:00+00:00'
                meta:
                  page: 1
                  page_size: 25
                  total: 1
                  total_pages: 1
                links:
                  next: null
                  prev: null
        '401':
          description: API key inválida o no proporcionada
        '403':
          description: La API key no pertenece a un usuario con acceso a este destinatario
        '404':
          description: Destinatario no encontrado
      security:
        - apiKeyAuth: []
components:
  schemas:
    SettlementListResponse:
      type: object
      description: Envelope único de listas v2.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SettlementListRow'
        meta:
          type: object
          properties:
            page:
              type: integer
              nullable: true
            page_size:
              type: integer
              nullable: true
            total:
              type: integer
            total_pages:
              type: integer
              nullable: true
        links:
          type: object
          properties:
            next:
              type: string
              nullable: true
            prev:
              type: string
              nullable: true
    SettlementListRow:
      type: object
      properties:
        settlement_id:
          type: string
          example: sett_7719203845512
        period_date:
          type: string
          format: date
          nullable: true
          description: Fecha del payout (cuándo se deposita el neto al destinatario).
          example: '2026-04-30'
        status:
          type: string
          enum:
            - pending
            - paid
            - failed
          example: paid
        gross_total:
          type: string
          description: Monto bruto total cobrado (suma de los cobros incluidos).
          example: '150000.00'
        commission_total:
          type: string
          description: Comisión total (base + IVA) descontada al destinatario.
          example: '3570.00'
        net_total:
          type: string
          description: >-
            Monto neto depositado al destinatario (`gross_total -
            commission_total`).
          example: '146430.00'
        paid_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Cuándo se confirmó el depósito al destinatario (`null` mientras no
            esté `paid`).
          example: '2026-05-02T15:00:00+00:00'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key para autenticación. Formato: `Api-Key YOUR-API-KEY`'

````

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