Cierre mensual del registro

Congela el registro de jornada mensual inalterable, séllalo con una firma digital y exporta el informe o el fichero de incidencias para nóminas.

Un cierre mensual congela el registro de jornada de un (año, mes) finalizado. Toma un snapshot de los totales de saldo y del desglose de ausencias de cada empleado activo —reutilizando el contrato de balances, sin recalcular— y bloquea el periodo contra fichajes retroactivos y correcciones. Es el paso que convierte un ledger en curso en un registro mensual defendible.

Todos los endpoints viven bajo https://api.factuarea.com/v1; cerrar y reabrir usan time_entries:write, las lecturas y exportaciones usan time_entries:read (las exportaciones para nóminas usan payroll_exports:read).

Cerrar un mes

POST /v1/monthly-register-closes cierra un mes finalizado. year y month (1–12) son obligatorios. Un mes que aún no ha terminado devuelve 422; un periodo ya cerrado devuelve 409. El cierre se crea en estado closed y la respuesta lleva una cabecera Location que apunta a él.

curl -X POST https://api.factuarea.com/v1/monthly-register-closes \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2026, "month": 1 }'

Un cierre se mueve entre dos estados, closed ⇄ reopened; ninguno es terminal. Reabrir (POST /v1/monthly-register-closes/{close}/reopen) es una recuperación auditada de un cierre erróneo que vuelve a permitir escrituras en el periodo. Re-cerrar un mes reabierto conserva su id original — el cierre reabierto y re-cerrado es el mismo recurso.

Lista cierres con GET /v1/monthly-register-closes (ordenados por periodo descendente, filtrables por year) y obtén uno con GET /v1/monthly-register-closes/{close}.

Sellarlo con una firma digital

POST /v1/monthly-register-closes/{close}/seal sella un registro closed: congela un digest SHA-256 canónico del snapshot y una firma RSA-SHA256 separada hecha con el certificado de la empresa. El registro queda a prueba de manipulación y verificable de forma independiente por un tercero.

Hay un sello por cierre — volver a sellar devuelve 409. Sellar un cierre que no está closed devuelve 422, y una empresa sin certificado activo y usable devuelve 422. Recupera el sello y su estado de verificación en vivo con GET /v1/monthly-register-closes/{close}/seal: verified es true cuando el snapshot y la firma están intactos; en caso contrario, verification_reason explica el desajuste (snapshot_mismatch, signature_invalid o certificate_unreadable).

curl -X POST https://api.factuarea.com/v1/monthly-register-closes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/seal \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

El sello es opcional pero recomendable: el cierre por sí solo bloquea el periodo, y el sello añade una firma criptográfica que permite a un auditor probar que el snapshot no ha cambiado desde que se firmó.

Informe y exportaciones

Tres salidas de lectura se construyen desde el snapshot congelado, de modo que los totales nunca se desvían de la hoja del momento del cierre.

Salida	Endpoint	Qué obtienes
Informe mensual	`GET /v1/monthly-register-closes/{close}/report`	Totales agregados de la empresa más una fila por empleado (totales, desglose de ausencias, saldos) y el detalle diario. Totales en minutos.
Exportación del registro diario	`GET /v1/monthly-register-closes/{close}/export`	El registro diario como hoja de cálculo en el formato `rdley_8_2019`, leído del ledger bloqueado. Descarga binaria.
Incidencias para nómina	`GET /v1/monthly-register-closes/{close}/payroll-export`	Una fila por empleado (identidad fiscal, minutos trabajados vs esperados, horas extra, saldo, ausencias aprobadas por tipo) en `a3`, `sage` o `nominasol`. Descarga binaria.

El informe es un recurso computado: expone close_id, nunca un id propio. Para los ficheros de exportación y de nómina, format es opcional (por defecto rdley_8_2019 y a3 respectivamente); un valor fuera del catálogo devuelve 422, y un periodo sin cierre devuelve 404. Lista el software de nómina soportado con GET /v1/payroll-export-formats.

curl -G https://api.factuarea.com/v1/monthly-register-closes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/payroll-export \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "format=a3" \
  --output payroll-2026-01.xlsx

Consulta los esquemas en la Referencia de API.

Flujo típico

Cierra el mes finalizado (POST .../monthly-register-closes).
Séllalo si necesitas un registro firmado y verificable (POST .../{close}/seal).
Informa o exporta para auditoría (/report), el fichero de inspección (/export) o nómina (/payroll-export).
Si detectas un error, reabre, corrige las entradas y re-cierra — el id se mantiene igual.

Próximos pasos

Fichajes — las entradas y correcciones que el cierre fotografía.
Ausencias — las ausencias aprobadas que aparecen en el informe.