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

> Obtiene las listas de documentos emitidos o recibidos por una entidad específica. Soporta búsqueda por folio, nombre del receptor y filtros avanzados.

## Qué hace

* Obtiene una lista paginada de documentos emitidos o recibidos por una entidad específica
* Soporta búsqueda por folio, nombre del receptor y filtros avanzados
* Permite paginar los resultados para manejar grandes volúmenes
* Filtra documentos por estado, tipo, fecha y otros criterios

## Ejemplos de uso

* Listar todos los documentos de una entidad
* Buscar un documento específico por folio
* Filtrar documentos por fecha de emisión
* Consultar documentos por tipo (factura, boleta, etc.)
* Obtener documentos recibidos o emitidos por separado

## Eventos de la traza (opt-in)

Por defecto la respuesta solo incluye `latest_trace_info` (un resumen liviano: `has_acknowledgments`, `has_claims`, `is_rejected`, `events_count`, etc.) para mantener el payload de la lista pequeño.

Si necesitas la trazabilidad completa de cada documento — los eventos del SII como `ACD` (acuse de recibo), `RCD` / `RFP` / `RFT` (reclamos), `NCA` (nota de crédito asociada), etc. — agrega `include_trace_events=true` al query string:

```bash theme={null}
GET /v1/documents?master_entity_id=123&include_trace_events=true
```

Con la flag activa, cada documento de la respuesta incluye un array `traces`, y cada traza un array `events` (ver el schema `Trace` y `TraceEvent` en la referencia). El endpoint de detalle (`GET /v1/documents/{document_id}`) ya retorna estos eventos de forma permanente, sin necesidad de la flag.

## Datos del libro RCV del SII (opt-in)

Si necesitas los datos del **Registro de Compras y Ventas (RCV)** de cada documento — por ejemplo para reconstruir los libros de compras y ventas completos de un período — agrega `include_book_metadata=true`:

```bash theme={null}
GET /v1/documents?master_entity_id=eid_...&document_type=received&include_book_metadata=true
```

Cada documento incluye entonces el objeto `book_metadata` (o `null` si aún no aparece en el RCV) con los montos según el libro (`net_amount`, `vat_amount`, `total_amount`, `exempt_amount`), IVA no recuperable / uso común / retenido, fechas de recepción y acuse, los flags `in_sii_compra_book` / `in_sii_venta_book` y los períodos de carga `compra_loading_period` / `venta_loading_period` (YYYYMM).

Para armar el **libro de compras** de un período filtra por `in_sii_compra_book=true` y `compra_loading_period == "YYYYMM"` usando `document_type=received`; para el **libro de ventas**, `in_sii_venta_book=true` y `venta_loading_period` con `document_type=issued`. Usa el período de carga y no la fecha de emisión: un documento emitido a fin de mes puede caer en el período siguiente del libro de compras del receptor.


## OpenAPI

````yaml GET /documents
openapi: 3.0.0
info:
  title: Tupana API
  description: API para integración con el sistema Tupana - Facturación Electrónica
  version: 1.0.0
servers:
  - url: https://api.tupana.ai/v1
    description: Servidor de producción
security:
  - apiKeyAuth: []
paths:
  /documents:
    get:
      tags:
        - Documentos
      summary: Listar documentos
      description: >-
        Obtiene las listas de documentos emitidos o recibidos por una entidad
        específica. Soporta búsqueda por folio, nombre del receptor y filtros
        avanzados.
      operationId: listDocuments
      parameters:
        - name: master_entity_id
          in: query
          description: >-
            ID de la entidad emisora o receptora cuyos documentos quieres
            consultar. Acepta el id opaco (`eid_...`, campo `opaque_id` de
            `/master-entities?rut=`) o el id entero.
          required: true
          schema:
            type: string
            example: eid_NDgyMTM6c2lnbmF0dXJl
        - name: document_type
          in: query
          description: >-
            `issued` (por defecto) o `received`. `issued` devuelve documentos
            donde la entidad es el **emisor**. `received` devuelve documentos
            donde la entidad es el **receptor** (cuando usas `received`, el
            parámetro `search` buscará en el nombre y RUT del emisor, y
            `issuer_tax_id` permite filtrar por RUT del emisor específico).
          required: false
          schema:
            type: string
            enum:
              - issued
              - received
            default: issued
        - name: folio
          in: query
          description: >-
            Folio exacto del documento. Si se envía, se ignoran otros filtros y
            se devuelve el documento específico.
          required: false
          schema:
            type: integer
        - name: search
          in: query
          description: >-
            Busca por nombre o RUT del receptor (cuando `document_type=issued`)
            o del emisor (cuando `document_type=received`).
          required: false
          schema:
            type: string
        - name: dte_type__code__in
          in: query
          description: >-
            Lista de códigos DTE separados por coma (ej: 33,34). Opcional: si no
            se envía, se devuelven todos los tipos según document_type (emitidos
            o recibidos).
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: issuer_tax_id
          in: query
          description: RUT del emisor cuando `document_type=received`.
          required: false
          schema:
            type: string
        - name: issue_date_gte
          in: query
          description: >-
            Fecha de emisión mínima (inclusive) en formato `YYYY-MM-DD`. Filtra
            documentos cuya fecha de emisión (`date_issued`) sea igual o
            posterior a esta fecha. Ejemplo: `issue_date_gte=2026-01-01`
            devuelve documentos emitidos desde el 1 de enero de 2026 en
            adelante.
          required: false
          schema:
            type: string
            format: date
          example: '2026-01-01'
        - name: issue_date_lte
          in: query
          description: >-
            Fecha de emisión máxima (inclusive) en formato `YYYY-MM-DD`. Filtra
            documentos cuya fecha de emisión (`date_issued`) sea igual o
            anterior a esta fecha. Ejemplo: `issue_date_lte=2026-01-31` devuelve
            documentos emitidos hasta el 31 de enero de 2026. Combínalo con
            `issue_date_gte` para definir un rango de fechas.
          required: false
          schema:
            type: string
            format: date
          example: '2026-01-31'
        - name: reception_date_from
          in: query
          description: >-
            Fecha de recepción mínima (inclusive) en formato `YYYY-MM-DD`.
            Filtra documentos recibidos cuya fecha de recepción en el libro del
            SII sea igual o posterior a esta fecha. Solo aplica a documentos que
            están en el libro de compras del SII (`document_type=received`).
          required: false
          schema:
            type: string
            format: date
          example: '2026-01-01'
        - name: reception_date_to
          in: query
          description: >-
            Fecha de recepción máxima (inclusive) en formato `YYYY-MM-DD`.
            Filtra documentos recibidos cuya fecha de recepción en el libro del
            SII sea igual o anterior a esta fecha. Solo aplica a documentos que
            están en el libro de compras del SII (`document_type=received`).
            Combínalo con `reception_date_from` para definir un rango.
          required: false
          schema:
            type: string
            format: date
          example: '2026-01-31'
        - name: page
          in: query
          description: >-
            Página actual, parte de la paginación estándar. Por defecto: 1. La
            respuesta incluye `count` (total), `next`, `previous` (URLs de
            navegación) y `results` (arreglo de documentos con información de
            emisor, receptor, montos, estado, PDF y referencias).
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          description: 'Tamaño de página (máx. 100). Por defecto: 20.'
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: include_trace_events
          in: query
          description: >-
            Si es `true`, cada documento incluye el array completo `traces` con
            sus `events` (eventos de la traza del SII: ACD, ERM, RCD, etc.). Por
            defecto la lista solo trae el resumen liviano `latest_trace_info`
            para no inflar la respuesta. Úsalo solo cuando necesites
            trazabilidad detallada — el endpoint de detalle (`GET
            /documents/{document_id}`) ya retorna estos eventos siempre.
          required: false
          schema:
            type: boolean
            default: false
        - name: include_book_metadata
          in: query
          description: >-
            Si es `true`, cada documento incluye el objeto `book_metadata` con
            todos los datos del Registro de Compras y Ventas (RCV) del SII:
            montos según el libro (`net_amount`, `vat_amount`, `total_amount`,
            `exempt_amount`), IVA no recuperable/uso común/retenido, fechas de
            recepción y acuse, flags `in_sii_compra_book`/`in_sii_venta_book` y
            los períodos de carga `compra_loading_period`/`venta_loading_period`
            (YYYYMM). Es `null` si el documento aún no aparece en el RCV. Para
            reconstruir el **libro de compras** de un período usa
            `document_type=received` y filtra por `in_sii_compra_book=true` y
            `compra_loading_period`; para el **libro de ventas** usa
            `document_type=issued` con `in_sii_venta_book=true` y
            `venta_loading_period` (el período de carga del RCV puede diferir de
            la fecha de emisión en documentos de fin de mes).
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Lista de documentos obtenida exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
        '403':
          description: Sin permisos para acceder a esta entidad
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Entidad no encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    DocumentListResponse:
      type: object
      properties:
        count:
          type: integer
          description: Número total de documentos
        next:
          type: string
          nullable: true
          description: URL de la siguiente página
        previous:
          type: string
          nullable: true
          description: URL de la página anterior
        results:
          type: array
          items:
            $ref: '#/components/schemas/DocumentDetail'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
          description: Código de error
          example: VALIDATION_ERROR
          enum:
            - VALIDATION_ERROR
            - AUTHENTICATION_ERROR
            - AUTHORIZATION_ERROR
            - NOT_FOUND
            - SII_ERROR
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error
    DocumentDetail:
      type: object
      properties:
        id:
          type: integer
          description: ID único del documento
        folio:
          type: string
          nullable: true
          description: Número de folio del documento
        date_issued:
          type: string
          format: date
          description: Fecha de emisión del documento
        amount_with_iva:
          type: number
          format: float
          description: Monto total con IVA
        dte_type_code:
          type: string
          description: 'Código del tipo de DTE (ej: "33" para Factura Electrónica)'
        created_at:
          type: string
          format: date-time
          description: Fecha de creación del registro (ISO 8601)
        updated_at:
          type: string
          format: date-time
          description: Fecha de última actualización (ISO 8601)
        has_trace:
          type: boolean
          description: true si el documento tiene al menos una traza registrada del SII.
        latest_trace_info:
          $ref: '#/components/schemas/LatestTraceInfo'
    LatestTraceInfo:
      type: object
      description: >-
        Resumen liviano de la última traza del documento. Siempre se incluye en
        las respuestas de listado y detalle (es `null` cuando el documento no
        tiene trazas).
      nullable: true
      properties:
        has_acknowledgments:
          type: boolean
          description: El documento tiene un acuse de recibo (eventos ACD o ERM).
        has_claims:
          type: boolean
          description: El documento tiene al menos un reclamo (RCD, RFP o RFT).
        is_more_than_eight_days:
          type: boolean
          description: >-
            Han pasado más de 8 días desde la recepción (relevante para mérito
            ejecutivo).
        is_rejected:
          type: boolean
          description: >-
            Calculado: el documento fue rechazado (existe un evento RCD, RFP o
            RFT).
        date_reception:
          type: string
          format: date-time
          description: Fecha y hora en que el SII registró la recepción del documento.
          nullable: true
        events_count:
          type: integer
          description: >-
            Cantidad total de eventos en esta traza. Útil para decidir si vale
            la pena solicitar `?include_trace_events=true` en el listado.
  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)

````