List documents

curl --request GET \
  --url https://api.prod.payana.cloud/public/api/v1/documents \
  --header 'api-key: <api-key>'

{
  "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
}

Documentos

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) utilizá 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).

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

GET

documents

List documents

curl --request GET \
  --url https://api.prod.payana.cloud/public/api/v1/documents \
  --header 'api-key: <api-key>'

{
  "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
}

Authorizations

api-key

string

header

required

API key provista por Payana.

Query Parameters

page

integer

default:1

Página (1-indexed).

Required range: x >= 1

page_size

integer

default:30

Cantidad de ítems por página.

Required range: 1 <= x <= 100

fields

enum<string>[]

Lista de campos expandibles a incluir en la respuesta, separados por coma. Si se omite, se devuelve solo el payload base.

Campos expandibles de un documento que pueden ser solicitados mediante el query param fields.

Available options:

beneficiaries,

line_items,

payments,

document_supports,

invoice_reception_events,

payment_receipt_complements,

erp_document,

logs,

expenses

string

Búsqueda libre por número de documento, beneficiario, identificador, etc.

Maximum string length: 100

beneficiary_reference

string

Filtrar por referencia (UUID) del beneficiario. Acepta múltiples valores separados por coma (ej. ref-123,ref-456,ref-789).

beneficiary_employee_reference

string

Filtrar por referencia (UUID) del beneficiario empleado. Acepta múltiples valores separados por coma.

beneficiary_employee_project_reference

string

Filtrar por referencia (UUID) del proyecto del beneficiario empleado. Acepta múltiples valores separados por coma.

type

enum<string>

Filtrar por tipo de documento. Tipo de documento.

Available options:

invoice,

debit_note,

credit_note,

expense

origin

enum<string>

Filtrar por origen del documento (cómo fue creado). Origen del documento: cómo fue creado en Payana.

Available options:

fiscal,

manual,

legalization,

api,

integration

state

enum<string>

Filtrar por estado interno del documento (máquina de estados). Estado interno del documento dentro de la máquina de estados de Payana.

Available options:

draft,

pending,

in_review,

approved,

rejected,

canceled,

paid

status

enum<string>

Filtrar por estado compuesto del documento (aprobación + pago). Estado compuesto del documento (aprobación + pago), usado como filtro agregado.

Available options:

pending,

in_review,

approved,

rejected,

paid,

partial,

overdue,

canceled

approval_status

enum<string>

Filtrar por estado de aprobación del documento. Estado de aprobación del documento dentro del flujo de aprobaciones.

Available options:

pending,

in_review,

approved,

rejected

is_canceled

boolean

Si es true, devuelve únicamente documentos cancelados ante el SAT/DIAN. Si es false, los excluye.

is_admited

boolean

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.

only_payana_invoices

boolean

Si es true, devuelve únicamente facturas emitidas por Payana.

only_expenses

boolean

Si es true, devuelve únicamente documentos de gastos.

issue_from

string<date>

Fecha de emisión desde (inclusive). Formato yyyy-MM-dd.

issue_to

string<date>

Fecha de emisión hasta (inclusive). Formato yyyy-MM-dd.

expiration_date_from

string<date>

Fecha de vencimiento desde (inclusive). Formato yyyy-MM-dd.

expiration_date_to

string<date>

Fecha de vencimiento hasta (inclusive). Formato yyyy-MM-dd.

Response

Documents list response

items

object[]

required

Show child attributes

total

integer

required

current_page

integer

required

page_size

integer

required

total_pages

integer

required

⌘I

Documentation Index

Authorizations

Query Parameters

Response