Skip to main content
GET
/
documents
Listar documentos
curl --request GET \
  --url https://api.tupana.ai/v1/documents \
  --header 'Authorization: <api-key>'
{
  "count": 123,
  "next": "<string>",
  "previous": "<string>",
  "results": [
    {
      "id": 123,
      "folio": "<string>",
      "date_issued": "2023-12-25",
      "amount_with_iva": 123,
      "dte_type_code": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "has_trace": true,
      "latest_trace_info": {
        "has_acknowledgments": true,
        "has_claims": true,
        "is_more_than_eight_days": true,
        "is_rejected": true,
        "date_reception": "2023-11-07T05:31:56Z",
        "events_count": 123
      }
    }
  ]
}

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

Authorizations

​
Authorization
string
header
required

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)

Query Parameters

​
master_entity_id
integer
required

ID de la entidad emisora o receptora cuyos documentos quieres consultar.

​
document_type
enum<string>
default:issued

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

Available options:
issued,
received
​
folio
integer

Folio exacto del documento. Si se envía, se ignoran otros filtros y se devuelve el documento específico.

​
search
string

Busca por nombre o RUT del receptor (cuando document_type=issued) o del emisor (cuando document_type=received).

​
dte_type__code__in
string[]

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

​
issuer_tax_id
string

RUT del emisor cuando document_type=received.

​
issue_date_gte
string<date>

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.

​
issue_date_lte
string<date>

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.

​
reception_date_from
string<date>

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

​
reception_date_to
string<date>

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.

​
page
integer
default:1

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

​
page_size
integer
default:20

Tamaño de página (máx. 100). Por defecto: 20.

Required range: x <= 100
​
include_trace_events
boolean
default:false

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.

Response

Lista de documentos obtenida exitosamente

​
count
integer

Número total de documentos

​
next
string | null

URL de la siguiente página

​
previous
string | null

URL de la página anterior

​
results
object[]