Listar documentos

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

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

fetch('https://api.tupana.ai/v2/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/v2/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/v2/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/v2/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

{
  "data": [
    {
      "id": "docu_9f2a7c1b8e4d0",
      "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,
      "json_param": {
        "external_order_id": "PED-123"
      },
      "additional_info": "Orden de compra N° 4500123 - Centro de costo: Operaciones"
    }
  ],
  "meta": {
    "page": 123,
    "page_size": 123,
    "total": 123,
    "total_pages": 123
  },
  "links": {
    "next": "<string>",
    "prev": "<string>"
  }
}

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

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

GET

documents

Listar documentos

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

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

fetch('https://api.tupana.ai/v2/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/v2/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/v2/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/v2/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

{
  "data": [
    {
      "id": "docu_9f2a7c1b8e4d0",
      "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,
      "json_param": {
        "external_order_id": "PED-123"
      },
      "additional_info": "Orden de compra N° 4500123 - Centro de costo: Operaciones"
    }
  ],
  "meta": {
    "page": 123,
    "page_size": 123,
    "total": 123,
    "total_pages": 123
  },
  "links": {
    "next": "<string>",
    "prev": "<string>"
  }
}

{
  "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: 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 () 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: 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), puedes filtrar el listado por cualquier key de ese objeto con json_param__<key>=<valor>: 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:

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.

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. El public ID de la entidad (ment_...).

Example:

"ment_4829301923847"

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

json_param__{key}

string

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.

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

data

object[]

Show child attributes

Introducción

Entidades

Conexiones

Documentos

Estados de Documentos

Documentos Programados

Webhooks

Errores

Listar documentos

Qué hace

Ejemplos de uso

Eventos de la traza (opt-in)

Datos del libro RCV del SII (opt-in)

Filtrar por json_param (campos personalizados)

Authorizations

Query Parameters

Response

​Qué hace

​Ejemplos de uso

​Eventos de la traza (opt-in)

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

​Filtrar por json_param (campos personalizados)

Authorizations

Query Parameters

Response

Qué hace

Ejemplos de uso

Eventos de la traza (opt-in)

Datos del libro RCV del SII (opt-in)

Filtrar por json_param (campos personalizados)