> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payana.la/llms.txt
> Use this file to discover all available pages before exploring further.

# List Documents

> Lista documentos paginados con filtros opcionales.

La respuesta contiene siempre los campos **base** del documento (`reference`, montos, `fiscal_reference`, `fiscal_metadata`, `purchase_order`, `is_admited`, etc.). Para traer información adicional (beneficiario, pagos, soportes, eventos, ERP, logs, gastos, notas) utiliza el query param `fields` con una lista de campos separados por coma.

Filtros útiles:

- `is_canceled=true|false` — documentos cancelados ante el SAT/DIAN.
- `is_admited=true|false` — documentos marcados como admitidos (tag `admitido`, p. ej. vía `POST /documents/{reference}/acknowledge`).
- `tags=admitido` o `tags=1,2` — por nombre o ID de tag (equivalente a filtrar admitidos cuando usás el nombre `admitido`).

El campo `notes` (notas del documento) solo se incluye en el listado cuando lo pides explícitamente con `fields=notes`.

Ejemplo:

```
GET /documents?page=1&page_size=30&is_canceled=false&is_admited=true&fields=beneficiaries,payments,document_supports,invoice_reception_events,payment_receipt_complements,erp_document,logs,notes
```



## OpenAPI

````yaml GET /documents
openapi: 3.1.0
info:
  title: Payana Accounts Payable API
  description: >-
    API pública para gestionar cuentas por pagar (payments) y beneficiarios
    (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se
    procesan pagos.
  version: 1.0.0
servers:
  - url: https://api.prod.payana.cloud/public/api/v1
    description: Production
  - url: https://api.develop.payana.cloud/public/api/v1
    description: Develop
security:
  - apiKeyAuth: []
tags:
  - name: Payments
    description: Crear y listar pagos
  - name: Beneficiaries
    description: Crear, listar y consultar beneficiarios
  - name: Webhooks
    description: Eventos de webhooks enviados por Payana
  - name: Banks
    description: Listar y consultar bancos
  - name: Transactions In
    description: Transacciones entrantes (polling, mismo formato que webhooks)
  - name: Documents
    description: Listar, consultar y operar documentos (cuentas por pagar)
  - name: DIAN Events
    description: >-
      Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del
      bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos
      identificados por CUFE. El procesamiento es asíncrono.
  - name: Fiscal Sync
    description: >-
      Disparar y consultar sincronización de documentos fiscales desde el SAT
      (México) o la DIAN (Colombia).
  - name: Workflow Steps
    description: >-
      Resolver el paso en que está parado un documento dentro de su flujo:
      aprobación, clasificación o etiquetado.
paths:
  /documents:
    get:
      tags:
        - Documents
      summary: List documents
      description: >-
        Lista documentos paginados con filtros opcionales.


        La respuesta contiene siempre los campos **base** del documento
        (`reference`, montos, `fiscal_reference`, `fiscal_metadata`,
        `purchase_order`, `is_admited`, etc.). Para traer información adicional
        (beneficiario, pagos, soportes, eventos, ERP, logs, gastos, notas)
        utiliza el query param `fields` con una lista de campos separados por
        coma.


        Filtros útiles:


        - `is_canceled=true|false` — documentos cancelados ante el SAT/DIAN.

        - `is_admited=true|false` — documentos marcados como admitidos (tag
        `admitido`, p. ej. vía `POST /documents/{reference}/acknowledge`).

        - `tags=admitido` o `tags=1,2` — por nombre o ID de tag (equivalente a
        filtrar admitidos cuando usás el nombre `admitido`).


        El campo `notes` (notas del documento) solo se incluye en el listado
        cuando lo pides explícitamente con `fields=notes`.


        Ejemplo:


        ```

        GET
        /documents?page=1&page_size=30&is_canceled=false&is_admited=true&fields=beneficiaries,payments,document_supports,invoice_reception_events,payment_receipt_complements,erp_document,logs,notes

        ```
      parameters:
        - name: page
          in: query
          description: Página (1-indexed).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Cantidad de ítems por página.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
        - name: fields
          in: query
          description: >-
            Lista de campos expandibles a incluir en la respuesta, separados por
            coma. Si se omite, se devuelve solo el payload base.
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DocumentField'
          example: >-
            beneficiaries,line_items,payments,document_supports,invoice_reception_events,payment_receipt_complements,erp_document,logs,notes
        - name: search
          in: query
          description: >-
            Búsqueda libre por número de documento, beneficiario, identificador,
            etc.
          schema:
            type: string
            maxLength: 100
        - name: beneficiary_reference
          in: query
          description: >-
            Filtrar por referencia (UUID) del beneficiario. Acepta múltiples
            valores separados por coma (ej. `ref-123,ref-456,ref-789`).
          schema:
            type: string
        - name: beneficiary_employee_reference
          in: query
          description: >-
            Filtrar por referencia (UUID) del beneficiario empleado. Acepta
            múltiples valores separados por coma.
          schema:
            type: string
        - name: beneficiary_employee_project_reference
          in: query
          description: >-
            Filtrar por referencia (UUID) del proyecto del beneficiario
            empleado. Acepta múltiples valores separados por coma.
          schema:
            type: string
        - name: type
          in: query
          description: Filtrar por tipo de documento.
          schema:
            $ref: '#/components/schemas/DocumentType'
        - name: origin
          in: query
          description: Filtrar por origen del documento (cómo fue creado).
          schema:
            $ref: '#/components/schemas/DocumentOrigin'
        - name: state
          in: query
          description: Filtrar por estado interno del documento (máquina de estados).
          schema:
            $ref: '#/components/schemas/DocumentState'
        - name: status
          in: query
          description: Filtrar por estado compuesto del documento (aprobación + pago).
          schema:
            $ref: '#/components/schemas/DocumentStatusFilter'
        - name: approval_status
          in: query
          description: Filtrar por estado de aprobación del documento.
          schema:
            $ref: '#/components/schemas/ApprovalStatus'
        - name: is_canceled
          in: query
          description: >-
            Si es `true`, devuelve únicamente documentos cancelados ante el
            SAT/DIAN. Si es `false`, los excluye.
          schema:
            type: boolean
        - name: is_admited
          in: query
          description: >-
            Si es `true`, devuelve únicamente documentos admitidos (con el tag
            de sistema `admitido`). Si es `false`, excluye los admitidos.
            Equivalente a `tags=admitido` para el caso `true`.
          schema:
            type: boolean
        - name: only_payana_invoices
          in: query
          description: Si es `true`, devuelve únicamente facturas emitidas por Payana.
          schema:
            type: boolean
        - name: only_expenses
          in: query
          description: Si es `true`, devuelve únicamente documentos de gastos.
          schema:
            type: boolean
        - name: issue_from
          in: query
          description: Fecha de emisión desde (inclusive). Formato `yyyy-MM-dd`.
          schema:
            type: string
            format: date
        - name: issue_to
          in: query
          description: Fecha de emisión hasta (inclusive). Formato `yyyy-MM-dd`.
          schema:
            type: string
            format: date
        - name: expiration_date_from
          in: query
          description: Fecha de vencimiento desde (inclusive). Formato `yyyy-MM-dd`.
          schema:
            type: string
            format: date
        - name: expiration_date_to
          in: query
          description: Fecha de vencimiento hasta (inclusive). Formato `yyyy-MM-dd`.
          schema:
            type: string
            format: date
        - name: tags
          in: query
          description: >-
            Filtrar por IDs o nombres de tags, separados por coma (ej. `1,2` o
            `admitido`).
          schema:
            type: string
        - name: sort_by
          in: query
          description: Campo por el cual ordenar los resultados.
          schema:
            $ref: '#/components/schemas/DocumentSortBy'
        - name: sort_order
          in: query
          description: Orden de los resultados.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Documents list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
              example:
                items:
                  - reference: aaea7db4-647c-4d92-9f86-89e34a68e1aa
                    document_number: FC-2024-001
                    type: invoice
                    issue_date: '2024-04-14T10:00:00Z'
                    expiration_date: '2024-04-30T10:00:00Z'
                    fiscal_reference: >-
                      e19d3e7867371a12fd53b67a56db087faa871c9797993d9bbf7806ae4e1466ea
                    fiscal_metadata: null
                    amount: 1190000
                    amount_currency: COP
                    approval_status: pending
                    payment_status: pending
                    file_path: https://storage.payana.cloud/documents/FC-2024-001.pdf
                    is_archived: false
                    purchase_order: OC-2024-001
                    tags: []
                    is_admited: false
                    created_at: '2024-04-14T10:00:00Z'
                    updated_at: '2024-04-14T10:00:00Z'
                    created_by:
                      source: fiscal
                      user: null
                total: 1
                current_page: 1
                page_size: 30
                total_pages: 1
        '400':
          description: Bad request / validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DocumentField:
      type: string
      enum:
        - beneficiaries
        - line_items
        - payments
        - document_supports
        - invoice_reception_events
        - payment_receipt_complements
        - erp_document
        - logs
        - expenses
        - notes
      description: >-
        Campos expandibles de un documento que pueden ser solicitados mediante
        el query param `fields`.
    DocumentType:
      type: string
      enum:
        - invoice
        - debit_note
        - credit_note
        - expense
      description: Tipo de documento.
    DocumentOrigin:
      type: string
      enum:
        - fiscal
        - manual
        - legalization
        - api
        - integration
      description: 'Origen del documento: cómo fue creado en Payana.'
    DocumentState:
      type: string
      enum:
        - draft
        - pending
        - in_review
        - approved
        - rejected
        - canceled
        - paid
      description: Estado interno del documento dentro de la máquina de estados de Payana.
    DocumentStatusFilter:
      type: string
      enum:
        - pending
        - in_review
        - approved
        - rejected
        - paid
        - partial
        - overdue
        - canceled
      description: >-
        Estado compuesto del documento (aprobación + pago), usado como filtro
        agregado.
    ApprovalStatus:
      type: string
      enum:
        - pending
        - in_review
        - approved
        - rejected
      description: Estado de aprobación del documento dentro del flujo de aprobaciones.
    DocumentSortBy:
      type: string
      enum:
        - created_at
        - document_number
        - type
        - amount
        - issue_date
        - expiration_date
        - beneficiary
        - beneficiary_employee
      description: Campo de ordenamiento para el listado de documentos.
    DocumentListResponse:
      type: object
      required:
        - items
        - total
        - current_page
        - page_size
        - total_pages
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        total:
          type: integer
        current_page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorObject'
      example:
        success: false
        error:
          code: VALIDATION_ERROR
          message: The request contains invalid data
          details:
            amount:
              - Amount must be greater than 0
            beneficiary_id:
              - Beneficiary does not exist
    Document:
      type: object
      description: >-
        Documento (factura, nota crédito/débito o gasto). Los campos marcados
        como *expandibles* se incluyen únicamente cuando se solicitan vía el
        query param `fields`.
      required:
        - reference
        - document_number
        - type
        - amount
        - amount_currency
        - approval_status
        - payment_status
        - is_archived
        - created_at
        - updated_at
      properties:
        reference:
          type: string
          description: Referencia interna del documento en Payana (UUID).
        document_number:
          type: string
          description: Número del documento (ej. `FC-2024-001`).
        type:
          $ref: '#/components/schemas/DocumentType'
        issue_date:
          type:
            - string
            - 'null'
          format: date-time
          description: Fecha de emisión del documento.
        expiration_date:
          type:
            - string
            - 'null'
          format: date-time
          description: Fecha de vencimiento del documento.
        fiscal_reference:
          type:
            - string
            - 'null'
          description: Referencia fiscal (CUFE en Colombia, UUID del SAT en México).
        fiscal_metadata:
          description: Metadata fiscal complementaria proveniente de la DIAN o SAT.
          oneOf:
            - $ref: '#/components/schemas/DocumentFiscalMetadata'
            - type: 'null'
        amount:
          type: number
          description: Monto total del documento.
        amount_currency:
          $ref: '#/components/schemas/Currency'
        approval_status:
          $ref: '#/components/schemas/ApprovalStatus'
          description: >-
            Estado del flujo de aprobación del documento (pendiente, aprobado,
            rechazado). Distinto de `payment_status`, que refleja cobro/pago
            respecto al monto.
        payment_status:
          $ref: '#/components/schemas/DocumentPaymentStatus'
        file_path:
          type:
            - string
            - 'null'
          description: URL al archivo PDF/XML del documento.
        is_archived:
          type: boolean
        purchase_order:
          $ref: '#/components/schemas/DocumentPurchaseOrder'
        tags:
          type: array
          items:
            type: string
        is_admited:
          type: boolean
          description: >-
            Indica si el documento fue marcado como admitido (tag de sistema
            `admitido`), por ejemplo mediante `POST
            /documents/{reference}/acknowledge`. No modifica `approval_status`.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          anyOf:
            - $ref: '#/components/schemas/DocumentCreatedBy'
            - type: 'null'
          description: >-
            Información sobre cómo y quién creó el documento (origen fiscal
            automático, usuario manual, legalizaciones, etc.).
        beneficiary:
          description: >-
            Beneficiario asociado al documento. Expandible vía
            `fields=beneficiaries`.
          anyOf:
            - $ref: '#/components/schemas/Beneficiary'
            - type: 'null'
        payments:
          type: array
          description: Pagos asociados al documento. Expandible vía `fields=payments`.
          items:
            type: object
            properties:
              reference:
                type: string
                description: >-
                  Identificador público del pago; coincide con el listado y el
                  detalle en la API de pagos.
              date:
                type: string
                format: date-time
              amount:
                type: number
              amount_currency:
                $ref: '#/components/schemas/Currency'
              payment_method:
                type: string
        support_document:
          description: >-
            Documento soporte asociado. Expandible vía
            `fields=document_supports`.
          anyOf:
            - type: object
              properties:
                issue_date:
                  type: string
                  format: date
                document_number:
                  type: string
                fiscal_reference:
                  type: string
                pdf_file_path:
                  type: string
                xml_file_path:
                  type: string
            - type: 'null'
        invoice_reception_events:
          type: array
          description: >-
            Eventos de recepción de la factura electrónica (acuse, aceptación,
            rechazo, etc.). Expandible vía `fields=invoice_reception_events`.
          items:
            type: object
            properties:
              event:
                type: string
              issue_date:
                type: string
                format: date-time
        payment_receipt_complements:
          type: array
          description: >-
            Complementos de pago (CFDI México). Expandible vía
            `fields=payment_receipt_complements`.
          items:
            type: object
            additionalProperties: true
        expenses:
          description: >-
            Detalle de gastos asociados al documento. Expandible vía
            `fields=expenses`.
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
        logs:
          type: array
          description: Historial de eventos del documento. Expandible vía `fields=logs`.
          items:
            type: object
            properties:
              event:
                type: string
              created_at:
                type: string
                format: date-time
              actor:
                $ref: '#/components/schemas/DocumentLogActor'
              metadata:
                type: object
                additionalProperties: true
        erp_document:
          description: >-
            Información del documento en el ERP. Expandible vía
            `fields=erp_document`.
          anyOf:
            - $ref: '#/components/schemas/ErpDocument'
            - type: 'null'
        notes:
          type: array
          description: >-
            Notas (comentarios y/o adjuntos) agregadas al documento vía `POST
            /documents/{reference}/notes`. Siempre presente en `GET
            /documents/{reference}`; en el listado `GET /documents` solo se
            incluye cuando se solicita `fields=notes`.
          items:
            $ref: '#/components/schemas/PublicNote'
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
        details:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetails'
            - type: 'null'
    DocumentFiscalMetadata:
      type: object
      description: >-
        Metadata fiscal complementaria extraída del XML durante el procesamiento
        del documento (sincronización DIAN/SAT o extracción por referencia
        fiscal).
      properties:
        final_notes:
          type: string
          description: >-
            Notas del documento fiscal consolidadas desde el XML UBL
            (`cbc:Note`). En Payana se almacenan en
            `extraction_metadata.additional_sections.finalNotes` y se exponen
            aquí en snake_case.
      additionalProperties: true
    Currency:
      type: string
      enum:
        - USD
        - COP
        - MXN
        - EUR
    DocumentPaymentStatus:
      type: string
      enum:
        - pending
        - partial
        - paid
      description: Estado de pago del documento.
    DocumentPurchaseOrder:
      type:
        - string
        - 'null'
      description: >-
        Referencia de orden de compra del comprador extraída del XML fiscal (UBL
        `cac:OrderReference` / `cbc:ID`), cuando está disponible en el
        documento. Siempre se incluye en el payload base de documentos y en
        webhooks de documento; es `null` cuando el XML no trae orden de compra o
        aún no fue extraída.
    DocumentCreatedBy:
      type: object
      description: Información sobre cómo se creó el documento.
      properties:
        source:
          type: string
          enum:
            - fiscal
            - manual
            - legalization
            - api
            - integration
          description: >-
            Origen de la creación del documento. `fiscal` indica que vino de la
            DIAN o el SAT; `manual` que lo creó un usuario; `legalization` que
            proviene de una legalización de gastos.
        user:
          description: >-
            Usuario que creó el documento, si aplica. `null` cuando la creación
            fue automática (ej. ingesta fiscal).
          anyOf:
            - type: object
              properties:
                reference:
                  type: string
                  description: Referencia (UUID) del usuario.
                name:
                  type: string
                email:
                  type: string
                  format: email
            - type: 'null'
    Beneficiary:
      type: object
      required:
        - reference
        - name
        - identifier_number
      properties:
        reference:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/BeneficiaryType'
        email:
          type:
            - string
            - 'null'
        phone_number:
          type:
            - string
            - 'null'
        identifier_type:
          anyOf:
            - $ref: '#/components/schemas/IdentifierType'
            - type: 'null'
        identifier_number:
          type: string
        payment_terms:
          type:
            - integer
            - 'null'
        fiscal_address:
          anyOf:
            - type: object
              properties:
                city_code:
                  type:
                    - string
                    - 'null'
                city_name:
                  type:
                    - string
                    - 'null'
                state_code:
                  type:
                    - string
                    - 'null'
                state_name:
                  type:
                    - string
                    - 'null'
            - type: 'null'
        contact_information:
          type: array
          items:
            $ref: '#/components/schemas/ContactInformation'
        bank_accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    DocumentLogActor:
      description: >-
        Quién originó la entrada del historial. Para eventos disparados por un
        agente de Payana solo se indica el origen del log (`source`); no se
        exponen nombre ni otros datos del agente configurado.
      oneOf:
        - type: object
          title: Usuario
          required:
            - type
            - name
          properties:
            type:
              type: string
              const: user
            name:
              type:
                - string
                - 'null'
              description: Nombre del usuario en Payana.
        - type: object
          title: Agente
          required:
            - type
            - source
          properties:
            type:
              type: string
              const: agent
            source:
              type:
                - string
                - 'null'
              description: >-
                Origen del evento tal como quedó registrado en el log (p. ej.
                `agent`). No incluye el nombre del agente.
        - type: object
          title: Sistema
          required:
            - type
            - source
          properties:
            type:
              type: string
              const: system
            source:
              type:
                - string
                - 'null'
              description: Origen del evento (p. ej. `system`, `fiscal`, `api`).
    ErpDocument:
      type: object
      description: >-
        Información del documento registrada en el ERP (contabilización,
        asiento, proveedor, líneas, etc.).
      properties:
        registered:
          type: boolean
          description: Indica si el documento ya fue registrado/causado en el ERP.
        data:
          type:
            - object
            - 'null'
          description: >-
            Detalle del documento en el ERP. Presente solo cuando `registered`
            es `true`.
          properties:
            document_id:
              type: string
            document_number:
              type: string
            document_reference:
              type: string
              description: Referencia (UUID) del documento en Payana.
            document_type_id:
              type: integer
            external_reference:
              type:
                - string
                - 'null'
            origin:
              type: string
            status:
              type: string
            vendor_id:
              type:
                - integer
                - 'null'
            issue_date:
              type: string
              format: date
            due_date:
              type:
                - string
                - 'null'
              format: date
            expiration_date:
              type:
                - string
                - 'null'
              format: date
            accounting_date:
              type:
                - string
                - 'null'
              format: date
            observation:
              type:
                - string
                - 'null'
            items:
              type: array
              items:
                $ref: '#/components/schemas/ErpDocumentItem'
            summary:
              type: object
              properties:
                subtotal:
                  type: number
                gross_total:
                  type: number
                net_total:
                  type: number
                discount:
                  type: number
              additionalProperties:
                type: number
            payment_lines:
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: number
                  due_date:
                    type: string
                    format: date
                  book_account_id:
                    type:
                      - integer
                      - 'null'
            erp_journal:
              $ref: '#/components/schemas/ErpJournal'
            erp_vendor:
              $ref: '#/components/schemas/ErpVendor'
            erp_journal_entry_lines:
              type: array
              items:
                $ref: '#/components/schemas/ErpJournalEntryLine'
            erp_purchase_order_line_ids:
              type: array
              items:
                type: integer
            has_purchase_order_association:
              type: boolean
            associated_purchase_orders:
              type: array
              items:
                type: object
                additionalProperties: true
            paymentLines:
              type: array
              items:
                type: object
                additionalProperties: true
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            deleted_at:
              type:
                - string
                - 'null'
              format: date-time
    PublicNote:
      type: object
      description: Nota pública de un documento (comentario y/o archivo adjunto).
      properties:
        comment:
          type:
            - string
            - 'null'
          description: Comentario de texto de la nota.
        file_path:
          type:
            - string
            - 'null'
          description: URL del archivo adjunto, si la nota tiene uno.
        file_name:
          type:
            - string
            - 'null'
          description: Nombre del archivo adjunto, si la nota tiene uno.
        created_by:
          type: object
          description: Autor de la nota.
          properties:
            name:
              type:
                - string
                - 'null'
              description: Nombre del autor de la nota.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    ErrorCode:
      type: string
      enum:
        - VALIDATION_ERROR
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - RATE_LIMITED
        - INTERNAL_ERROR
    ErrorDetails:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    BeneficiaryType:
      type: string
      enum:
        - supplier
    IdentifierType:
      type: string
      description: Tipo de identificación (ej. NIT, CC, RFC).
    ContactInformation:
      type: object
      required:
        - type
        - value
      properties:
        reference:
          type: string
          description: Referencia del contacto (cuando aplica).
        type:
          type: string
          description: Tipo de contacto (ej. email, phone).
        value:
          type: string
    BankAccount:
      type: object
      required:
        - reference
        - bank_reference
        - bank_name
        - account_number
      properties:
        reference:
          type: string
        bank_reference:
          type: string
          description: Referencia del banco (UUID).
        bank_name:
          type:
            - string
            - 'null'
        account_number:
          type: string
        account_type:
          type: string
          enum:
            - savings
            - checking
        validation_status:
          type: string
          enum:
            - pending
            - processing
            - validated
            - rejected
            - validation_error
        account_recipient_name:
          type:
            - string
            - 'null'
        account_recipient_document_number:
          type:
            - string
            - 'null'
        account_recipient_document_type:
          anyOf:
            - $ref: '#/components/schemas/IdentifierType'
            - type: 'null'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    ErpDocumentItem:
      type: object
      description: Línea de ítem de un documento en el ERP.
      properties:
        description:
          type: string
        product_id:
          type:
            - integer
            - 'null'
        quantity:
          type: number
        unit_price:
          type: number
        discount:
          type: number
        amount_total:
          type: number
        taxes:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              base:
                type: number
        cost_centers:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              value:
                type: number
                description: Porcentaje o monto asignado al centro de costo.
    ErpJournal:
      type: object
      description: Libro/diario contable del ERP.
      properties:
        id:
          type: integer
        external_id:
          type:
            - integer
            - string
            - 'null'
        company_id:
          type:
            - integer
            - string
        code:
          type: string
        name:
          type: string
        journal_type:
          type: string
          description: Tipo de diario (ej. `purchase`, `sale`, `cash`).
        description:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
    ErpVendor:
      type: object
      description: Proveedor registrado en el ERP.
      properties:
        id:
          type: integer
        external_id:
          type:
            - integer
            - string
            - 'null'
        company_id:
          type:
            - integer
            - string
        alias_name:
          type:
            - string
            - 'null'
        legal_name:
          type:
            - string
            - 'null'
        taxpayer_identifier:
          type:
            - string
            - 'null'
        taxpayer_identifier_type:
          type:
            - string
            - 'null'
        vendor_type:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
        beneficiary_id:
          type:
            - integer
            - string
            - 'null'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
    ErpJournalEntryLine:
      type: object
      description: Línea del asiento contable generado en el ERP.
      properties:
        id:
          type: integer
        external_id:
          type:
            - integer
            - string
            - 'null'
        company_id:
          type:
            - integer
            - string
        erp_journal_entry_id:
          type: integer
        erp_book_account_id:
          type:
            - integer
            - 'null'
        erp_product_id:
          type:
            - integer
            - 'null'
        debit_cents:
          type:
            - string
            - number
          description: Monto del débito, expresado en centavos.
        credit_cents:
          type:
            - string
            - number
          description: Monto del crédito, expresado en centavos.
        description:
          type:
            - string
            - 'null'
        source:
          type: string
          description: Origen de la línea (ej. `document`, `payable_line`, `tax`).
        metadata:
          type: object
          additionalProperties: true
        erp_product:
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
        erp_book_account:
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
        erp_journal_entry_line_cost_centers:
          type: array
          items:
            type: object
            additionalProperties: true
        erp_journal_entry_line_taxes:
          type: array
          items:
            type: object
            additionalProperties: true
        erp_purchase_order_line_id:
          type:
            - integer
            - 'null'
        erp_goods_receipt_line_id:
          type:
            - integer
            - 'null'
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: API key provista por Payana.

````