Changelog API - payana-docs

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.

​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