Listar documentos

curl --request GET \
  --url https://api.tupana.ai/v1/documents \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.tupana.ai/v1/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tupana.ai/v1/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tupana.ai/v1/documents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tupana.ai/v1/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
      }
    }
  ]
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

GET

documents

Listar documentos

curl --request GET \
  --url https://api.tupana.ai/v1/documents \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.tupana.ai/v1/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tupana.ai/v1/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tupana.ai/v1/documents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tupana.ai/v1/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
      }
    }
  ]
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

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.

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:

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.

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

string

required

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.

Example:

"eid_NDgyMTM6c2lnbmF0dXJl"

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.

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.

include_book_metadata

boolean

default:false

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

Response

Lista de documentos obtenida exitosamente

count

integer

Número total de documentos

string | null

URL de la siguiente página

string | null

URL de la página anterior

results

object[]

Show child attributes

Introducción

Entidades

Credenciales

Documentos

Estados de Documentos

Documentos Programados

Webhooks

Listar documentos

Qué hace

Ejemplos de uso

Eventos de la traza (opt-in)

Datos del libro RCV del SII (opt-in)

Authorizations

Query Parameters

Response

​Qué hace

​Ejemplos de uso

​Eventos de la traza (opt-in)

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

Authorizations

Query Parameters

Response

Qué hace

Ejemplos de uso

Eventos de la traza (opt-in)

Datos del libro RCV del SII (opt-in)