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

# Obtener documento específico

> Obtiene toda la información completa de un documento tributario específico, incluyendo:

- **PDF y XML** cuando están disponibles (el PDF siempre se incluye en la respuesta, campo `pdf_url`)
- **Detalles (productos/líneas)** del documento (campo `details`)
- **Header completo** con información de transacción, pago y tipo de compra (campo `header`)
- **Información del emisor** completa (campo `document_issuer`)
- **Información del receptor** completa (campo `document_receiver`)
- **Referencias** a otros documentos, como notas de crédito (campo `references`)

Este endpoint es útil para consultar detalles completos de un documento ya emitido o recibido.

**Seguridad:** El usuario solo puede acceder al documento si es emisor (sender) o receptor (receiver) del documento. Si el usuario no tiene acceso, se retorna un error 403 Forbidden.

## Qué hace

Obtiene toda la información completa de un documento tributario específico, incluyendo PDF, XML, productos, información del emisor y receptor, header, y referencias. Este endpoint es útil para consultar detalles completos de un documento ya emitido o recibido.

## Ejemplos de uso

* Consultar detalles completos de un documento ya emitido
* Descargar el PDF de un documento específico
* Obtener el XML para procesos de integración
* Verificar información de un documento recibido
* Auditar documentos antes de procesarlos

## Trazabilidad SII

La respuesta incluye siempre el array `traces` con cada traza del documento en el SII y, dentro de cada una, la lista `events` con los eventos registrados (acuse de recibo, reclamos, notas de crédito asociadas, etc.). Revisa los schemas `Trace` y `TraceEvent` en la referencia para el detalle de cada campo.

A diferencia del endpoint de listado — donde estos eventos son opt-in vía `include_trace_events=true` — aquí no necesitas ningún flag adicional.


## OpenAPI

````yaml GET /documents/{document_id}
openapi: 3.0.0
info:
  title: Tupana API
  description: API para integración con el sistema Tupana - Facturación Electrónica
  version: 1.0.0
servers:
  - url: https://api.tupana.ai/v1
    description: Servidor de producción
security:
  - apiKeyAuth: []
paths:
  /documents/{document_id}:
    get:
      tags:
        - Documentos
      summary: Obtener documento específico
      description: >-
        Obtiene toda la información completa de un documento tributario
        específico, incluyendo:


        - **PDF y XML** cuando están disponibles (el PDF siempre se incluye en
        la respuesta, campo `pdf_url`)

        - **Detalles (productos/líneas)** del documento (campo `details`)

        - **Header completo** con información de transacción, pago y tipo de
        compra (campo `header`)

        - **Información del emisor** completa (campo `document_issuer`)

        - **Información del receptor** completa (campo `document_receiver`)

        - **Referencias** a otros documentos, como notas de crédito (campo
        `references`)


        Este endpoint es útil para consultar detalles completos de un documento
        ya emitido o recibido.


        **Seguridad:** El usuario solo puede acceder al documento si es emisor
        (sender) o receptor (receiver) del documento. Si el usuario no tiene
        acceso, se retorna un error 403 Forbidden.
      operationId: getDocument
      parameters:
        - name: document_id
          in: path
          description: ID único del documento a consultar (entero)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: >-
            Documento obtenido exitosamente con toda la información completa:
            PDF, XML, detalles (productos), header, información del emisor y
            receptor, y referencias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDetailWithFiles'
        '400':
          description: Parámetros inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: API Key faltante o inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Sin permisos para acceder al documento. El usuario debe ser emisor
            (sender) o receptor (receiver) del documento.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: No tienes acceso a este documento
        '404':
          description: Documento o entidad no encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    DocumentDetailWithFiles:
      type: object
      allOf:
        - $ref: '#/components/schemas/DocumentDetail'
        - type: object
          properties:
            amount_iva:
              type: number
              format: float
              description: Monto del IVA
              nullable: true
            amount_without_iva:
              type: number
              format: float
              description: Monto sin IVA
              nullable: true
            currency:
              type: string
              description: Moneda del documento
              enum:
                - CLP
                - UF
                - USD
                - EUR
              example: CLP
            sender_id:
              type: integer
              description: ID de la entidad emisora
            sender_name:
              type: string
              description: Nombre de la entidad emisora
            sender_tax_id:
              type: string
              description: RUT de la entidad emisora
            receiver_id:
              type: string
              description: >-
                ID de la entidad receptora (como string, puede ser null para
                algunos tipos de documentos)
              nullable: true
            receiver_name:
              type: string
              description: Nombre de la entidad receptora
              nullable: true
            receiver_tax_id:
              type: string
              description: RUT de la entidad receptora
              nullable: true
            has_credit_note:
              type: boolean
              description: Indica si el documento tiene una nota de crédito asociada
            is_paid:
              type: boolean
              description: Indica si el documento está marcado como pagado
            json_param:
              type: object
              additionalProperties: true
              description: Parámetros JSON almacenados del documento
              nullable: true
            traces:
              type: array
              description: >-
                Array de trazas del documento en el SII, cada una con su lista
                de `events`. En el endpoint de detalle siempre se incluye; en el
                endpoint de listado solo se incluye cuando se pasa
                `include_trace_events=true`.
              items:
                $ref: '#/components/schemas/Trace'
            trace_update_log:
              type: object
              description: Log de actualización de trazas
              nullable: true
            document_states:
              type: array
              description: >-
                Array de estados del documento (rechazado, con NC, acuse,
                pagado, mérito ejecutivo)
              items:
                type: object
                properties:
                  label:
                    type: string
                    description: Etiqueta del estado
                  description:
                    type: string
                  state_type:
                    type: string
                    description: Tipo de estado del documento
            vat_withheld:
              type: boolean
              description: Indica si se retuvo IVA
              nullable: true
            exchange_rate:
              type: string
              description: Tipo de cambio para facturas internacionales
              nullable: true
            original_amount:
              type: string
              description: >-
                Monto original en moneda extranjera para facturas
                internacionales
              nullable: true
            state:
              type: string
              description: Estado del documento (draft, issued, etc.)
              nullable: true
            dte_type_description:
              type: string
              description: Descripción del tipo de DTE
            pdf:
              type: string
              format: uri
              description: >-
                URL presignada al PDF del documento (válida por tiempo limitado,
                generalmente 1 hora)
              nullable: true
            xml:
              type: string
              description: Contenido completo del XML del documento tributario electrónico
              nullable: true
            xml_error:
              type: string
              description: >-
                Mensaje de error si no se pudo obtener el XML (null si está
                disponible)
              nullable: true
            references:
              type: array
              description: Array de documentos referenciados (para notas de crédito, etc.)
              items:
                $ref: '#/components/schemas/ReferenceItem'
            details:
              type: array
              description: Array de productos/líneas del documento
              items:
                $ref: '#/components/schemas/DetailItem'
              nullable: true
            header:
              $ref: '#/components/schemas/DocumentHeader'
              description: >-
                Información del encabezado del documento (transacción, pago,
                etc.)
              nullable: true
            document_issuer:
              $ref: '#/components/schemas/DocumentIssuer'
              description: Información completa del emisor del documento
              nullable: true
            document_receiver:
              $ref: '#/components/schemas/DocumentReceiver'
              description: Información completa del receptor del documento
              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: integer
          description: ID único del documento
        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.
        latest_trace_info:
          $ref: '#/components/schemas/LatestTraceInfo'
    Trace:
      type: object
      description: >-
        Traza del documento en el SII. Contiene los flags de acceso/estado y la
        lista de `events` con el detalle de cada hito (recepción, acuse,
        reclamo, etc.).
      properties:
        date_reception:
          type: string
          format: date-time
          description: Fecha y hora en que el SII registró la recepción del documento.
          nullable: true
        has_receiver_access:
          type: boolean
          description: El receptor tiene acceso al documento en el portal del SII.
        has_issuer_access:
          type: boolean
          description: El emisor tiene acceso al documento en el portal del SII.
        has_holder_access:
          type: boolean
          description: El tenedor vigente tiene acceso al documento.
        is_paid_cash:
          type: boolean
          description: Documento marcado como pagado al contado en el SII.
        has_claims:
          type: boolean
          description: El documento tiene al menos un reclamo registrado (RCD, RFP o RFT).
        is_more_than_eight_days:
          type: boolean
          description: >-
            Han pasado más de 8 días desde la recepción (relevante para mérito
            ejecutivo).
        has_acknowledgments:
          type: boolean
          description: El documento tiene un acuse de recibo (ACD o ERM).
        has_guide_reference:
          type: boolean
          description: El documento referencia una guía de despacho.
          nullable: true
        is_rejected:
          type: boolean
          description: >-
            Calculado: el documento fue rechazado (existe un evento RCD, RFP o
            RFT).
        days_until_executive_merit:
          type: integer
          description: >-
            Días que faltan para que el documento entre en mérito ejecutivo
            (negativo si ya pasó). `null` si no aplica (sin recepción, con acuse
            o rechazado).
          nullable: true
        executive_merit_alert_level:
          type: string
          description: Nivel de alerta para mérito ejecutivo.
          enum:
            - none
            - warning
            - critical
        events:
          type: array
          description: >-
            Eventos registrados en el SII para esta traza (ordenados por fecha
            descendente).
          items:
            $ref: '#/components/schemas/TraceEvent'
    ReferenceItem:
      type: object
      required:
        - reference_folio
        - reference_date
        - dte_type_code
      properties:
        reference_folio:
          type: integer
          description: Folio de referencia
        reference_date:
          type: string
          format: date
          description: Fecha de referencia
        reference_reason:
          type: string
          description: >-
            Razón de referencia. Para notas de crédito totales debe ser 'ANULA
            DOCUMENTO DE LA REFERENCIA'.
          example: ANULA DOCUMENTO DE LA REFERENCIA
        dte_type_code:
          type: string
          description: Código del tipo de DTE del documento referenciado
    DetailItem:
      type: object
      required:
        - item_name
        - quantity
        - unit_price
      properties:
        item_name:
          type: string
          description: Nombre del ítem
        quantity:
          type: number
          description: Cantidad
        unit_price:
          type: number
          format: float
          minimum: 0
          description: Precio unitario neto, sin IVA (no puede ser negativo)
        gross_unit_price:
          type: number
          format: float
          description: >-
            Precio unitario bruto, con IVA incluido. Solo válido para boletas
            electrónicas (dte_type 39 y 41); en cualquier otro tipo de documento
            la API responde 422. No se puede combinar con unit_price en el mismo
            documento: todas las líneas deben usar uno u otro. Si se envía, se
            usa como unit_price para calcular item_total, y el neto/IVA del
            documento se derivan a partir del bruto.
        item_description:
          type: string
          description: Descripción del ítem
        discount_percent:
          type: number
          format: float
          description: Porcentaje de descuento
        item_code:
          type: string
          description: Código del ítem
        unit:
          type: string
          description: Unidad de medida
        other_tax:
          type: number
          format: float
          description: Otros impuestos
        item_type_code:
          type: integer
          description: Código de tipo de ítem
    DocumentHeader:
      type: object
      properties:
        purchase_transaction_type:
          type: string
          description: Tipo de transacción de compra
          nullable: true
        sale_transaction_type:
          type: string
          description: Tipo de transacción de venta
          nullable: true
        payment_method:
          type: string
          description: Método de pago
          enum:
            - '1'
            - '2'
            - '3'
          nullable: true
        due_date:
          type: string
          format: date
          description: Fecha de vencimiento
          nullable: true
        vat_withheld:
          type: boolean
          description: >-
            Indica si el IVA está retenido. Solo aplicable para facturas de
            compra (DTE 46) y notas de crédito que referencian facturas de
            compra.
          example: false
          nullable: true
        retention_type:
          type: string
          description: >-
            Tipo de retención obligatorio para boletas de honorarios (DTE 80,
            90). Define quién retiene el 14,5% legal.
          enum:
            - RETRECEPTOR
            - RETCONTRIBUYENTE
          example: RETRECEPTOR
          nullable: true
        purchase_type:
          type: string
          description: Tipo de compra para facturas recibidas en el SII
          enum:
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
          example: '1'
          nullable: true
    DocumentIssuer:
      type: object
      required:
        - rut
      properties:
        rut:
          type: string
          description: >-
            RUT sin puntos y con guion, ej: 76543210-K. Si X-Use-Defaults es
            true, los demás campos se rellenarán automáticamente según la
            configuración.
          pattern: ^[0-9]{7,8}-[0-9K]$
        business_name:
          type: string
          description: Razón social
        phone_number:
          type: string
          description: Número de teléfono
        email:
          type: string
          description: Correo electrónico
        business_activity:
          type: string
          description: Giro comercial
        activity_code:
          type: integer
          description: Código de actividad económica
        sii_branch_code:
          type: string
          description: Código de sucursal SII
        address:
          type: string
          description: Dirección
        district:
          type: string
          description: Comuna
        city:
          type: string
          description: Ciudad
    DocumentReceiver:
      type: object
      required:
        - rut
      properties:
        rut:
          type: string
          description: >-
            RUT sin puntos y con guion, ej: 76543210-K. Si X-Use-Defaults es
            true, los demás campos se rellenarán automáticamente según la
            configuración.
          pattern: ^[0-9]{7,8}-[0-9K]$
        business_name:
          type: string
          description: Razón social
        contact:
          type: string
          description: Contacto
        business_activity:
          type: string
          description: Giro comercial
        address:
          type: string
          description: Dirección
        district:
          type: string
          description: Comuna
        city:
          type: string
          description: Ciudad
    LatestTraceInfo:
      type: object
      description: >-
        Resumen liviano de la última traza del documento. Siempre se incluye en
        las respuestas de listado y detalle (es `null` cuando el documento no
        tiene trazas).
      nullable: true
      properties:
        has_acknowledgments:
          type: boolean
          description: El documento tiene un acuse de recibo (eventos ACD o ERM).
        has_claims:
          type: boolean
          description: El documento tiene al menos un reclamo (RCD, RFP o RFT).
        is_more_than_eight_days:
          type: boolean
          description: >-
            Han pasado más de 8 días desde la recepción (relevante para mérito
            ejecutivo).
        is_rejected:
          type: boolean
          description: >-
            Calculado: el documento fue rechazado (existe un evento RCD, RFP o
            RFT).
        date_reception:
          type: string
          format: date-time
          description: Fecha y hora en que el SII registró la recepción del documento.
          nullable: true
        events_count:
          type: integer
          description: >-
            Cantidad total de eventos en esta traza. Útil para decidir si vale
            la pena solicitar `?include_trace_events=true` en el listado.
    TraceEvent:
      type: object
      description: >-
        Evento de trazabilidad del SII para un documento (ej: aceptación,
        reclamo, acuse).
      properties:
        event_code:
          type: string
          description: >-
            Código del evento del SII. Algunos comunes: `ACD` (acepta
            contenido), `ERM` (acuse de recibo), `RCD` (reclamo de contenido),
            `RFP` (reclamo forma de pago), `RFT` (reclamo forma de transporte),
            `NCA` (nota de crédito asociada).
          example: ACD
        event_description:
          type: string
          description: Descripción del evento entregada por el SII.
          example: Acepta Contenido del Documento
        event_date:
          type: string
          format: date-time
          description: Fecha y hora del evento en zona horaria de Chile.
        responsable_rut:
          type: integer
          description: RUT (sin DV) de quien registró el evento en el SII.
          nullable: true
        responsable_dv:
          type: string
          description: Dígito verificador del RUT del responsable.
          nullable: true
  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)

````