> ## 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. # Get Document > Obtiene un documento por referencia (UUID) con el payload completo: incluye beneficiario, ítems de línea, pagos, soporte, eventos de recepción, complementos de pago, asiento ERP asociado, logs, gastos/proyectos y notas cuando apliquen. A diferencia del listado, el detalle siempre incluye el campo `notes` con las notas del documento (creadas vía `POST /documents/{reference}/notes`). ## OpenAPI ````yaml GET /documents/{reference} 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/{reference}: get: tags: - Documents summary: Get document description: >- Obtiene un documento por referencia (UUID) con el payload completo: incluye beneficiario, ítems de línea, pagos, soporte, eventos de recepción, complementos de pago, asiento ERP asociado, logs, gastos/proyectos y notas cuando apliquen. A diferencia del listado, el detalle siempre incluye el campo `notes` con las notas del documento (creadas vía `POST /documents/{reference}/notes`). parameters: - name: reference in: path required: true description: Referencia del documento (UUID). schema: type: string responses: '200': description: Document response content: application/json: schema: $ref: '#/components/schemas/Document' example: 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: final_notes: >- Factura sujeta a retención en la fuente según artículo 383 del E.T. amount: 1190000 amount_currency: COP approval_status: approved payment_status: partial file_path: https://storage.payana.cloud/documents/FC-2024-001.pdf is_archived: false purchase_order: OC-2024-001 tags: [] is_admited: true created_at: '2024-04-14T10:00:00Z' updated_at: '2024-04-14T12:30:00Z' created_by: source: fiscal user: null beneficiary: reference: 616263a5-a677-4ad1-92ca-7e120adad8d4 origin: fiscal name: Proveedor Ejemplo S.A.S identifier_type: NIT identifier_number: '900123456' is_deleted: false deleted_at: null contact_information: [] payments: - reference: 9c1e2f3a-4b5c-6d7e-8f90-1234567890ab date: '2024-04-20T10:00:00Z' amount: 600000 amount_currency: COP payment_method: bank_transfer support_document: issue_date: '2024-04-14' document_number: FV-0001 invoice_reception_events: - event: acuse issue_date: '2024-04-14T10:30:00Z' payment_receipt_complements: [] line_items: - reference: c3f5c8e1-8b2d-4e6f-9a0b-1c2d3e4f5a6b name: Servicio de consultoría técnica description: null code: '43232313' quantity: 1 unit_code: E48 unit_price: 1000000 currency: COP subtotal: 1000000 total: 1190000 position: 0 metadata: externalId: line-001 adjustments: - type: tax code: IVA rate: 0.19 rate_percentage: 19 base_amount: 1000000 amount: 190000 is_inclusive: false metadata: {} created_at: '2024-04-14T10:00:00Z' updated_at: '2024-04-14T10:00:00Z' expenses: null logs: - event: document.created created_at: '2024-04-14T10:00:00Z' actor: type: system source: fiscal metadata: {} - event: document.approved created_at: '2024-04-14T12:30:00Z' actor: type: user name: María García metadata: {} - event: document.updated created_at: '2024-04-14T14:00:00Z' actor: type: agent source: agent metadata: {} erp_document: registered: true data: document_id: '7256571' document_number: E341-37582 document_reference: aaea7db4-647c-4d92-9f86-89e34a68e1aa document_type_id: 4 external_reference: '' origin: API status: draft vendor_id: 113 issue_date: '2026-04-13' due_date: '2026-07-09' expiration_date: '2026-07-09' accounting_date: '2026-04-13' observation: Pago a término en 1 cuotas CxP items: - description: Servicio de consultoría técnica product_id: 6 quantity: 1 unit_price: 1000000 discount: 0 amount_total: 1190000 taxes: - id: 3 base: 1000000 cost_centers: - id: 14 value: 50 - id: 13 value: 40 summary: subtotal: 1000000 gross_total: 1000000 net_total: 1190000 discount: 0 iva_8: 0 iva_16: 0 payment_lines: - amount: 1190000 due_date: '2026-05-09' book_account_id: 1558 erp_journal: id: 4 external_id: 12 company_id: 4 code: BILL name: Facturas de proveedores journal_type: purchase description: null metadata: {} created_at: '2026-04-13T09:48:40.905-03:00' updated_at: '2026-04-13T09:48:40.905-03:00' deleted_at: null erp_vendor: id: 113 external_id: 60 company_id: 4 alias_name: Proveedor Ejemplo legal_name: Proveedor Ejemplo S.A.S taxpayer_identifier: null taxpayer_identifier_type: null vendor_type: company metadata: id: 60 name: Proveedor Ejemplo active: true taxpayer_identifier_type: NIT created_at: '2026-04-13T09:48:36.109-03:00' updated_at: '2026-04-13T09:48:36.109-03:00' deleted_at: null beneficiary_id: null erp_journal_entry_lines: - id: 17 external_id: null company_id: '4' erp_journal_entry_id: 11 erp_book_account_id: null erp_product_id: 6 debit_cents: '119000000' credit_cents: '0' description: Servicio de consultoría técnica source: document metadata: taxes: - id: 3 base: 1000000 source: document discount: 0 quantity: 1 line_order: 1 unit_price: 1000000 amount_total: 1190000 cost_centers: - id: 14 value: 50 - id: 13 value: 40 erp_product: id: 6 external_id: 24 company_id: 4 sku: TRANS & ACC name: Viaje y alojamiento unit_type: Unidades default_price_cents: '100' ac_account_id: null tax_id: 3 product_category_id: 1 metadata: type: service active: true created_at: '2026-04-13T09:48:38.337-03:00' updated_at: '2026-04-13T09:48:38.337-03:00' deleted_at: null erp_book_account: null erp_journal_entry_line_cost_centers: - id: 7 erp_journal_entry_line_id: 17 erp_cost_center_id: 14 value: 5000 created_at: '2026-04-13T10:59:06.866-03:00' updated_at: '2026-04-13T10:59:06.866-03:00' erpCostCenter: id: 14 external_id: 6 company_id: 4 code: null name: Bogotá description: null parent_id: null metadata: planId: 3 created_at: null updated_at: null deleted_at: null erp_journal_entry_line_taxes: - id: 7 erp_journal_entry_line_id: 17 erp_tax_id: 3 base_cents: 100000000 created_at: '2026-04-13T10:59:06.865-03:00' updated_at: '2026-04-13T10:59:06.865-03:00' erpTax: id: 3 external_id: 3 company_id: 4 code: 19% IVA name: IVA Compra 19% rate: '19.0000' base_cents: null tax_type: 0 purchase_ac_account_code: null sales_ac_account_code: null default_book_account_id: null metadata: {} created_at: '2026-04-13T09:48:37.620-03:00' updated_at: '2026-04-13T09:48:37.620-03:00' deleted_at: null erp_purchase_order_line_id: null erp_goods_receipt_line_id: null created_at: '2026-04-13T10:59:06.860-03:00' updated_at: '2026-04-13T10:59:06.860-03:00' deleted_at: null - id: 18 external_id: null company_id: '4' erp_journal_entry_id: 11 erp_book_account_id: 1558 erp_product_id: null debit_cents: '0' credit_cents: '119000000' description: Cuota CxP 1 source: payable_line metadata: amount: 1190000 source: payable_line due_date: '2026-05-09' line_order: 1 erp_product: null erp_book_account: id: 1558 external_id: '916' company_id: '4' code: '20501255' name: Test CxP description: null parent_id: null account_type: liability normal_balance: credit metadata: odooAccountType: liability_payable created_at: '2026-04-13T09:48:37.052-03:00' updated_at: '2026-04-13T09:48:37.052-03:00' deleted_at: null erp_journal_entry_line_cost_centers: [] erp_journal_entry_line_taxes: [] erp_purchase_order_line_id: null erp_goods_receipt_line_id: null created_at: '2026-04-13T10:59:06.868-03:00' updated_at: '2026-04-13T10:59:06.868-03:00' deleted_at: null erp_purchase_order_line_ids: [] has_purchase_order_association: false associated_purchase_orders: [] paymentLines: [] created_at: '2026-04-13T10:34:23.981-03:00' updated_at: '2026-04-13T10:59:06.857-03:00' deleted_at: null notes: - comment: Documento revisado y aprobado por el área contable. file_path: https://storage.payana.cloud/documents/notes/soporte.pdf file_name: soporte.pdf created_by: name: Integración ERP created_at: '2026-06-12T13:05:00.000+00:00' updated_at: '2026-06-12T13:05:00.000+00:00' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found 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: 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' 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 DocumentType: type: string enum: - invoice - debit_note - credit_note - expense description: Tipo de documento. 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 ApprovalStatus: type: string enum: - pending - in_review - approved - rejected description: Estado de aprobación del documento dentro del flujo de aprobaciones. 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 ErrorObject: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: anyOf: - $ref: '#/components/schemas/ErrorDetails' - type: 'null' 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 ErrorCode: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR ErrorDetails: type: object additionalProperties: type: array items: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: api-key description: API key provista por Payana. ````