Changelog API - payana-docs

Pagos: nómina opcional en la lista

Cambio	Tipo	Descripción
`include_payroll`	Nuevo parámetro	`GET /payments?include_payroll=true` devuelve también los pagos de nómina junto con los pagos a proveedores. Por defecto es `false`: sin el parámetro la lista responde igual que antes.
`payable.type`	Campo	Diferencia cada pago: `supplier` (proveedor), `payroll` (nómina) o `advance` (anticipo).
`beneficiary.type`	Corrección de documentación	En el detalle `GET /payments/{reference}`, además de `supplier` puede ser `employee`: el beneficiario de un pago de nómina.

Documentos: cuentas por pagar en la respuesta

Cambio	Tipo	Descripción
`payables`	Campo expandible	Cuentas por pagar (CxP) del documento. Se piden con `fields=payables` en `GET /documents` y vienen siempre en `GET /documents/{reference}`. Cada entrada trae `reference`, `type`, `status`, `external_reference` (identificador en el ERP), `amount`, `amount_currency`, `outstanding_balance` y fechas. Es una lista porque un documento puede tener más de una CxP.
`payments[].payable_reference`	Campo	Referencia de la CxP a la que se aplicó cada pago; coincide con `payables[].reference`.
`payments[].status`	Campo	Estado del pago (`pending`, `in_process`, `processed`, `failed`). `outstanding_balance` resta solo los `processed` e `in_process`, y el 21,9% de los pagos de una CxP están `pending`: sin este campo la suma de `payments` no cuadra con el saldo y nada lo explica.
`payments`	Cambio de significado	El arreglo cubre los pagos de todas las cuentas por pagar del documento. Un documento con una sola CxP —99,6% de los casos— devuelve exactamente lo mismo que antes; los 11.409 documentos con dos o más CxP ahora incluyen los pagos de todas ellas, no los de una sola.
`outstanding_balance` negativo	Ojo	Un saldo negativo significa que la CxP se pagó de más o que alguno de sus pagos está en otra moneda y se restó a valor nominal (el cálculo no convierte). Se distinguen pidiendo `fields=payables,payments`: la moneda viene en cada pago.
Reconciliar montos	Ojo	Si venís sumando `payments[]` para compararlo contra `amount`, agrupá primero por `payable_reference`. Un documento puede tener dos CxP por la misma deuda (una creada por Payana y otra por el sync del ERP), y en ese caso la suma de los pagos supera el monto del documento sin que nadie haya pagado dos veces.
`document_support`	Corrección de documentación	El valor del expandible es `document_support` (singular) y la respuesta lo devuelve bajo esa misma llave, con los campos `reference`, `fiscal_reference`, `document_number`, `file_path`, `created_at` y `updated_at`.

Con esto, un flujo que aprueba vía POST /workflow-steps/{reference}/complete y genera CxP puede leer la cuenta por pagar resultante desde el propio documento, sin consultas adicionales.

Fiscal Sync: sincronización SAT/DIAN vía API pública

Cambio	Tipo	Descripción
`POST /fiscal-sync`	Nuevo endpoint	Dispara sincronización fiscal para la compañía de la API key. México: extracción Satws de las últimas 24 h. Colombia: inicia sync DIAN vía reenvío de correo (asíncrono). Sin parámetros en el body.
`GET /fiscal-sync/status`	Nuevo endpoint	Consulta el estado de la sync. México: estado de la extracción Satws. Colombia: `pending` / `finished` / `failed` según registros DIAN desde `started_at`.
Rate limit	Comportamiento	Máximo 1 sync fiscal por hora por compañía (`429` con `retry_after_seconds`).

Documentos: notas, aprobar por CUFE y webhooks enriquecidos

Cambio	Tipo	Descripción
`POST /documents/{reference}/notes`	Nuevo endpoint	Agrega una nota (comentario y/o archivo adjunto) a un documento. Acepta `application/json` con `comment`/`file_path` o `multipart/form-data` con un archivo en el campo `file`. Adjuntos: `pdf`, `jpg`, `jpeg`, `png` (máx. 5 MB).
`notes`	Campo expandible	`GET /documents/{reference}` ahora incluye siempre las notas del documento. En el listado `GET /documents` se incluyen solo al pedir `fields=notes`.
`POST /documents/{reference}/approve`	Comportamiento	El path `{reference}` acepta UUID de Payana o referencia fiscal (CUFE en Colombia, UUID del SAT en México).
Webhooks `document.created` / `document.accounted`	Campo	`fiscal_metadata.final_notes` cuando el XML trae notas UBL (`cbc:Note`).
Webhook `document.accounted`	Campo	`accounting_entry` incluye detalle de causación: asiento ERP V2 (`registration_payload`, `journal_entry`, `advance_crossings`) o campos legacy (`products`, `causation_state`, etc.).

Documentos: filtros y campos adicionales

GET /documents y GET /documents/{reference} incorporan mejoras para integraciones:

Cambio	Tipo	Descripción
`is_admited`	Filtro + campo en respuesta	`true` si el documento tiene el tag `admitido` (p. ej. tras `POST /documents/{reference}/acknowledge`). Filtra con `?is_admited=true` o `?is_admited=false`.
`is_canceled`	Filtro	`?is_canceled=true` devuelve solo facturas canceladas ante el SAT/DIAN; `false` las excluye.
`fiscal_metadata`	Campo	Objeto complementario (`null` si no aplica). Hoy incluye `final_notes` (notas UBL `cbc:Note` del XML fiscal).
`purchase_order`	Campo	Referencia de orden de compra del XML (`null` si no viene en el documento).
`tags`	Filtro	Acepta IDs o nombres separados por coma (ej. `admitido` o `1,2`).

Listado de pagos con filtros avanzados

GET /payments acepta los siguientes parámetros opcionales de filtro:

Parámetro	Tipo	Descripción
`status`	`string`	Filtra por estado: `pending`, `in_process`, `processed`, `failed`
`state`	`string`	`active` (por defecto) o `archived`. Con `archived` se ignora `status`
`beneficiary_reference`	`string`	Referencia (UUID) del beneficiario; acepta varios separados por coma
`document_reference`	`string`	Referencia (UUID) del documento; acepta varios separados por coma
`payable_reference`	`string`	Referencia (UUID) del payable
`batch_reference`	`string`	Referencia (UUID) del lote; acepta varios separados por coma
`expiration_date_from` / `expiration_date_to`	`string` (`YYYY-MM-DD`)	Rango por fecha de vencimiento del payable
`payment_method`	`string`	Métodos separados por coma (ej. `card,banking_correspondent`)
`tags`	`string`	IDs de etiquetas separados por coma
`only_expenses`	`boolean`	Solo pagos de gastos

Webhooks: nuevo evento `payment.rescheduled`

Se agregó el evento payment.rescheduled al catálogo de webhooks. Se dispara cuando un pago cambia su fecha de vencimiento desde la plataforma.Payload:

{
  "event": "payment.rescheduled",
  "payment_id": "pay_abc123",
  "previous_due_date": "2026-03-10",
  "new_due_date": "2026-03-25"
}

Autenticación: soporte para tokens con scopes

La API ahora acepta tokens con scopes específicos (payments:read, payments:write, beneficiaries:read). Los tokens sin scope siguen funcionando con acceso completo para mantener compatibilidad.

API

​Pagos: nómina opcional en la lista

​Documentos: cuentas por pagar en la respuesta

​Fiscal Sync: sincronización SAT/DIAN vía API pública

​Documentos: notas, aprobar por CUFE y webhooks enriquecidos

​Documentos: filtros y campos adicionales

​Listado de pagos con filtros avanzados

​Webhooks: nuevo evento payment.rescheduled

​Autenticación: soporte para tokens con scopes