> ## 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. export const props_0 = undefined ## 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: 
  
    {props_0.exTraceEvents}
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 ({props_0.exDetailPath}) 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`: 
  
    {props_0.exBookMetadata}
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. ## Filtrar por json\_param (campos personalizados) Si al crear el documento guardaste datos propios en `json_param` (ver el campo `json_param` en [Crear documentos](/api-reference/documents/batch)), puedes filtrar el listado por cualquier key de ese objeto con `json_param__=`: 
  
    {props_0.exJsonParam}
Esto devuelve solo los documentos donde `json_param` contiene esa key con exactamente ese valor (coincidencia exacta, no búsqueda parcial). Puedes combinar varias keys en la misma request — se aplican con AND: 
  
    {props_0.exJsonParamAnd}
* La key es abierta (es tu propio campo, no algo predefinido por Pana), pero solo acepta letras, números y `_` (`^[a-zA-Z0-9_]{1,64}$`). Una key con otros caracteres devuelve `400`. * El valor de la query siempre se compara como string, así que hoy este filtro solo funciona para keys cuyo valor en `json_param` también sea un string (ej. `{"external_order_id": "PED-123"}`). Si guardaste un booleano o número (ej. `{"active": true}`), esa key no es filtrable todavía por esta vía — no hay coincidencia de tipo entre el string de la query y el booleano/número guardado. * Documentos sin `json_param`, o cuyo `json_param` no tiene esa key, quedan fuera del resultado. ## OpenAPI ````yaml api-reference/openapi-v2.json GET /documents/ 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: /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_v2 parameters: - name: master_entity_id in: query description: >- ID de la entidad emisora o receptora cuyos documentos quieres consultar. El public ID de la entidad (`ment_...`). required: true schema: type: string example: ment_4829301923847 - 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 no incluye la traza detallada 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: json_param__{key} in: query description: >- Filtra por cualquier key del objeto `json_param` que guardaste al crear el documento (ver `json_param` en el endpoint de creación). Reemplaza `{key}` por el nombre real de tu campo, ej. `json_param__external_order_id=PED-123`. Coincidencia exacta (no búsqueda parcial); puedes repetir el parámetro con distintas keys en la misma request y se combinan con AND. La key solo acepta `[a-zA-Z0-9_]` (máx. 64 caracteres) — otro caracter devuelve 400. El valor de la query siempre se compara como string, así que solo sirve para keys cuyo valor en `json_param` también sea un string; valores booleanos o numéricos no son filtrables por esta vía todavía. required: false schema: type: string example: PED-123 - 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: data: type: array items: $ref: '#/components/schemas/DocumentDetail' 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 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: string description: ID único del documento example: docu_9f2a7c1b8e4d0 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. json_param: type: object additionalProperties: true nullable: true description: >- Campos propios del cliente enviados en `json_param` al crear el documento. `null` si no se envió. example: external_order_id: PED-123 additional_info: type: string nullable: true description: >- Texto enviado en `additional_info` al crear el documento. `null` si no se envió. Solo se imprime en el PDF si la empresa usa el PDF propio de Tu Pana o el facturador de mercado. example: 'Orden de compra N° 4500123 - Centro de costo: Operaciones' 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.