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

# Consultar estados de documento

> Consultar el historial de estados asociados a un documento tributario específico.

## Qué hace

* Devuelve todos los estados registrados para el documento
* Permite entender qué eventos han ocurrido sobre ese documento
* Muestra la secuencia cronológica de los estados
* No modifica ninguna información

## Ejemplos de uso

* Revisar si un documento fue pagado
* Ver si tuvo rechazos o acuses
* Auditar cambios o eventos automáticos del SII
* Mostrar el historial completo en el backoffice


## OpenAPI

````yaml api-reference/openapi-v2.json GET /documents/{document_id}/states/
openapi: 3.0.0
info:
  title: Tupana API — v2
  description: >-
    API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas,
    boleta de honorarios y nómina. Los identificadores de recursos son public
    IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…).
  version: 2.0.0
servers:
  - url: https://api.tupana.ai/v2
    description: Producción (v2)
security:
  - apiKeyAuth: []
paths:
  /documents/{document_id}/states/:
    get:
      tags:
        - Estados de Documentos
      summary: Consultar historial de estados de un documento
      description: >-
        Consultar el historial de estados asociados a un documento tributario
        específico.
      operationId: listDocumentStates_v2
      parameters:
        - name: document_id
          in: path
          description: ID único del documento (integer)
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Historial de estados obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStatesResponse'
        '401':
          description: No autenticado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Sin permisos para acceder a este documento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: No tienes acceso a este documento
        '404':
          description: Documento no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    DocumentStatesResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indica si la operación fue exitosa
          example: true
        document_id:
          type: string
          description: ID del documento
          example: docu_9f2a7c1b8e4d0
        folio:
          type: string
          description: Folio del documento
          example: '123'
        states:
          type: array
          description: >-
            Lista de estados registrados para el documento, ordenados
            cronológicamente (más reciente primero)
          items:
            $ref: '#/components/schemas/DocumentState'
        document:
          $ref: '#/components/schemas/DocumentDetail'
    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
    DocumentState:
      type: object
      properties:
        event_code:
          type: string
          description: Código del evento
          example: ERM
        event_description:
          type: string
          description: Descripción del evento
          example: Acuse de Recibo
        event_date:
          type: string
          format: date-time
          description: Fecha y hora del evento (ISO 8601)
          example: '2024-01-16T10:30:00Z'
        responsable_rut:
          type: integer
          description: RUT del responsable del evento
          example: 12345678
        responsable_dv:
          type: string
          description: Dígito verificador del RUT del responsable
          example: '9'
        rejected_by_user:
          type: string
          format: email
          nullable: true
          description: >-
            Email del usuario que registró el rechazo (solo para eventos de
            rechazo)
          example: usuario@ejemplo.com
        accepted_by_user:
          type: string
          format: email
          nullable: true
          description: >-
            Email del usuario que registró la aprobación (solo para eventos de
            aprobación)
          example: usuario@ejemplo.com
    DocumentDetail:
      type: object
      properties:
        id:
          type: string
          description: ID único del documento
          example: docu_9f2a7c1b8e4d0
        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.
        json_param:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Campos propios del cliente enviados en `json_param` al crear el
            documento. `null` si no se envió.
          example:
            external_order_id: PED-123
        additional_info:
          type: string
          nullable: true
          description: >-
            Texto enviado en `additional_info` al crear el documento. `null` si
            no se envió. Solo se imprime en el PDF si la empresa usa el PDF
            propio de Tu Pana o el facturador de mercado.
          example: 'Orden de compra N° 4500123 - Centro de costo: Operaciones'
  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)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.