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>",
        "description": "<string>"
      },
      "sender": {
        "id": 123,
        "name": "<string>",
        "tax_id": "<string>"
      },
      "receiver": {
        "id": 123,
        "name": "<string>",
        "tax_id": "<string>"
      },
      "pdf_base64": "<string>"
    }
  ]
}
Este endpoint permite obtener una lista paginada de documentos emitidos o recibidos por una entidad específica. Soporta búsqueda por folio, nombre del receptor y filtros avanzados.

​
Características principales

  • Paginación: Resultados paginados con control de tamaño de página
  • Búsqueda: Por folio, nombre del receptor o RUT del receptor
  • Filtros: Por tipo de DTE, monto, fecha de emisión y más
  • Documentos emitidos y recibidos: Controla qué tipo de documentos mostrar usando el parámetro document_type

​
Parámetros principales

ParámetroTipoRequeridoDescripción
master_entity_idintegerSíID de la entidad emisora o receptora cuyos documentos quieres consultar.
document_typestringNoissued (default) o received para seleccionar el rol de la entidad.
foliointegerNoFolio exacto del documento. Si se envía, se ignoran otros filtros y se devuelve el PDF en pdf_base64.
searchstringNoBusca por nombre o RUT del receptor (emitidos) o del emisor (recibidos).
dte_type__code__instringNoLista de códigos DTE separados por coma (ej: 33,34).
issuer_tax_idstringNoRUT del emisor cuando document_type=received.
pageintegerNoPágina actual, parte de la paginación estándar.
page_sizeintegerNoTamaño de página (máx. 100).

​
Respuesta exitosa

La respuesta 200 OK incluye un objeto paginado con:
  • count, next, previous para la navegación
  • results: arreglo de documentos con información de emisor, receptor, montos, estado, PDF y referencias
  • pdf_base64 únicamente cuando la búsqueda es por folio específico

​
Tipos de documentos

El parámetro document_type controla qué tipo de documentos se devuelven:
ValorDescripciónComportamiento
issued (por defecto)Documentos emitidosDevuelve documentos donde la entidad especificada es el emisor
receivedDocumentos recibidosDevuelve documentos donde la entidad especificada es el receptor
Nota importante: Cuando consultas documentos recibidos (document_type=received), los campos de búsqueda y filtros se ajustan automáticamente:
  • El parámetro search buscará en el nombre y RUT del emisor (no del receptor)
  • El parámetro issuer_tax_id permite filtrar por RUT del emisor específico

​
Paginación

El endpoint soporta paginación mediante los parámetros page y page_size: La respuesta incluye:
  • count: Total de documentos
  • next: URL para la siguiente página (si existe)
  • previous: URL para la página anterior (si existe)
  • results: Array de documentos en la página actual

Authorizations

​
Authorization
string
header
required

API Key para autenticación. Debe proporcionarse en el formato: 'Api-Key YOUR-API-KEY'

Query Parameters

​
master_entity_id
integer
required

ID de la entidad maestra

​
folio
string

Número de folio del documento a buscar. Si se proporciona, el sistema devolverá el documento junto con su PDF en formato base64.

​
issuer_tax_id
string

RUT del emisor para buscar documentos recibidos de un emisor específico (formato: 12345678-9)

​
search
string

Búsqueda de texto libre en folio, nombre del receptor o RUT del receptor

​
document_type
enum<string>
default:issued

Tipo de documentos a listar. 'issued' para documentos emitidos (por defecto), 'received' para documentos recibidos

Available options:
issued,
received
​
dte_type__code__in
string[]

Filtrar por tipos de DTE específicos. Por defecto incluye: 33, 34, 39, 61

​
page
integer
default:1

Número de página para paginación

​
page_size
integer
default:20

Cantidad de elementos por página (máximo 100)

Required range: x <= 100

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[]