> ## 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.

# Changelog API

> Cambios, nuevos endpoints y mejoras en la API pública de Payana.

<Update label="Junio 2026">
  ## 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`).                                                                                                                    |
</Update>

<Update label="Junio 2026">
  ## 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.).                                              |
</Update>

<Update label="Mayo 2026">
  ## 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`).                                                                                            |
</Update>

<Update label="Abril 2026">
  ## 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                                                   |
</Update>

<Update label="Marzo 2026">
  ## 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:**

  ```json theme={null}
  {
    "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.
</Update>