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

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

## ¿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.json GET /master-entities/{master_entity_id}/settlements/
openapi: 3.0.0
info:
  title: Tupana API - Recaudación
  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/v1
    description: Servidor de producción
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 (MasterEntity).
          schema:
            type: integer
        - 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:
                count: 1
                next: null
                previous: null
                results:
                  - settlement_id: 1042
                    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'
        '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
      properties:
        count:
          type: integer
          example: 1
        next:
          type: string
          nullable: true
          example: null
        previous:
          type: string
          nullable: true
          example: null
        results:
          type: array
          items:
            $ref: '#/components/schemas/SettlementListRow'
    SettlementListRow:
      type: object
      properties:
        settlement_id:
          type: integer
          example: 1042
        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`'

````