Tancament mensual del registre

Congela el registre de jornada mensual inalterable, segella'l amb una signatura digital i exporta l'informe o el fitxer d'incidències per a nòmines.

Un tancament mensual congela el registre de jornada d'un (any, mes) finalitzat. Pren un snapshot dels totals de saldo i del desglossament d'absències de cada empleat actiu —reutilitzant el contracte de balanços, sense recalcular— i bloqueja el període contra fitxatges retroactius i correccions. És el pas que converteix un ledger en curs en un registre mensual defensable.

Tots els endpoints viuen sota https://api.factuarea.com/v1; tancar i reobrir usen time_entries:write, les lectures i exportacions usen time_entries:read (les exportacions per a nòmines usen payroll_exports:read).

Tancar un mes

POST /v1/monthly-register-closes tanca un mes finalitzat. year i month (1–12) són obligatoris. Un mes que encara no ha acabat retorna 422; un període ja tancat retorna 409. El tancament es crea en estat closed i la resposta porta una capçalera Location que hi apunta.

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 tancament es mou entre dos estats, closed ⇄ reopened; cap no és terminal. Reobrir (POST /v1/monthly-register-closes/{close}/reopen) és una recuperació auditada d'un tancament erroni que torna a permetre escriptures al període. Re-tancar un mes reobert conserva el seu id original — el tancament reobert i re-tancat és el mateix recurs.

Llista tancaments amb GET /v1/monthly-register-closes (ordenats per període descendent, filtrables per year) i obtén-ne un amb GET /v1/monthly-register-closes/{close}.

Segellar-lo amb una signatura digital

POST /v1/monthly-register-closes/{close}/seal segella un registre closed: congela un digest SHA-256 canònic del snapshot i una signatura RSA-SHA256 separada feta amb el certificat de l'empresa. El registre queda a prova de manipulació i verificable de manera independent per un tercer.

Hi ha un segell per tancament — tornar a segellar retorna 409. Segellar un tancament que no està closed retorna 422, i una empresa sense certificat actiu i usable retorna 422. Recupera el segell i el seu estat de verificació en viu amb GET /v1/monthly-register-closes/{close}/seal: verified és true quan el snapshot i la signatura estan intactes; en cas contrari, verification_reason explica el desajust (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 segell és opcional però recomanable: el tancament per si sol bloqueja el període, i el segell afegeix una signatura criptogràfica que permet a un auditor provar que el snapshot no ha canviat des que es va signar.

Informe i exportacions

Tres sortides de lectura es construeixen des del snapshot congelat, de manera que els totals mai es desvien del full del moment del tancament.

Sortida	Endpoint	Què obtens
Informe mensual	`GET /v1/monthly-register-closes/{close}/report`	Totals agregats de l'empresa més una fila per empleat (totals, desglossament d'absències, saldos) i el detall diari. Totals en minuts.
Exportació del registre diari	`GET /v1/monthly-register-closes/{close}/export`	El registre diari com a full de càlcul en el format `rdley_8_2019`, llegit del ledger bloquejat. Descàrrega binària.
Incidències per a nòmina	`GET /v1/monthly-register-closes/{close}/payroll-export`	Una fila per empleat (identitat fiscal, minuts treballats vs esperats, hores extra, saldo, absències aprovades per tipus) en `a3`, `sage` o `nominasol`. Descàrrega binària.

L'informe és un recurs computat: exposa close_id, mai un id propi. Per als fitxers d'exportació i de nòmina, format és opcional (per defecte rdley_8_2019 i a3 respectivament); un valor fora del catàleg retorna 422, i un període sense tancament retorna 404. Llista el programari de nòmina suportat amb 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 els esquemes a la Referència d'API.

Flux típic

Tanca el mes finalitzat (POST .../monthly-register-closes).
Segella'l si necessites un registre signat i verificable (POST .../{close}/seal).
Informa o exporta per a auditoria (/report), el fitxer d'inspecció (/export) o nòmina (/payroll-export).
Si detectes un error, reobre, corregeix les entrades i re-tanca — l'id es manté igual.

Pròxims passos

Fitxatges — les entrades i correccions que el tancament fotografia.
Absències — les absències aprovades que apareixen a l'informe.