API Reference

Bază: https://gdocs.gstack.esempla.systems. Autentificare: Authorization: Bearer <jwt> (din POST /api/authenticate), exceptând rutele publice. Erorile admin folosesc problem+json (JHipster); /api/v1 folosește {"message": …}.

Legendă acces: pub = fără auth · auth = orice autentificat · admin = ROLE_ADMIN (service + org admin) · machine = ROLE_MACHINE.

Autentificare & cont

Metodă	Cale	Acces	Descriere
POST	/api/authenticate	pub	login user/parolă → { id_token }
GET	/api/authenticate	auth	login curent (string)
POST	/api/register	pub	înregistrare
GET	/api/activate	pub	activare cont
GET	/api/account	auth	contul curent
POST	/api/account	auth	actualizare profil
POST	/api/account/change-password	auth	schimbare parolă
POST	/api/account/reset-password/init | /finish	pub	resetare parolă
GET	/api/acl/me	auth	contextul de acces (L1/L2/L3, isAdmin, hasSecret)

Documente

Metodă	Cale	Acces	Descriere
GET	/api/documents	auth	listă (filtre + paginare + sort), scopat ACL/tenant
GET	/api/documents/count	auth	număr
GET	/api/documents/{id}	auth	metadate (checkRead → 404 dacă nu are drept)
POST	/api/documents	auth	creare (JSON metadate)
PUT	/api/documents/{id}	auth	update complet
PATCH	/api/documents/{id}	auth	update parțial (application/merge-patch+json)
DELETE	/api/documents/{id}	auth	soft-delete → STERS
POST	/api/documents/upload	auth	upload multipart (file, denumire, bucketId, secret, parola, proprietarId, emitentId)
GET	/api/documents/{id}/download	auth	download binar (ACL-enforced)
POST	/api/documents/{id}/arhiveaza | /restore | /purge	auth	tranziții ciclu de viață

Versionare (istoricul conținutului)

Un document păstrează un singur conținut curent (Document.storageUri), dar istoricul versiunilor e păstrat: fiecare „încărcare versiune nouă” înlocuiește conținutul curent și adaugă o versiune, fără a suprascrie octeții vechi (cheie versionată uploads/<cod>/v<n>). Prima interogare a versiunilor face backfill automat al versiunii v1 din conținutul curent.

Metodă	Cale	Acces	Descriere
GET	/api/documents/{id}/versions	auth (read)	istoricul versiunilor (nou → vechi); backfill v1 la nevoie
POST	/api/documents/{id}/versions	auth (writer/owner)	încarcă o versiune nouă — multipart file (+ comentariu?); devine versiunea curentă
GET	/api/documents/{id}/versions/{numar}/download	auth (read)	descarcă o versiune anume (numar = 1, 2, …); verifică parola dacă documentul e protejat
POST	/api/documents/{id}/versions/{numar}/restore	auth (writer/owner)	restaurează versiunea numar → creează o versiune nouă (curentă) cu conținutul celei alese

Răspuns versiune (VersiuneView): { id, numarVersiune, dimensiune, hashSha256, extensie, format, contentType, comentariu, creatDe, creatLa, curenta }.

Note:

• Restaurarea e forward-only — nu șterge nimic: readuce conținutul unei versiuni vechi ca versiune nouă, deci istoricul (și auditul) rămâne intact. Fiecare încărcare/restaurare scrie un EvenimentDocument (MODIFICAT / RESTAURAT).
• Cifrarea la repaus a fiecărei versiuni oglindește tipSecuritate al documentului (CRIPTAT → AES; PAROLA → parola cerută și la download-ul unei versiuni).
• download de versiune trimite Content-Disposition: attachment cu numele denumire.ext (v<numar>).

Exemple

# token
TOKEN=$(curl -s -X POST $BASE/api/authenticate -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' | jq -r .id_token)

# 1) încarcă o versiune nouă a documentului 42
curl -X POST "$BASE/api/documents/42/versions" -H "Authorization: Bearer $TOKEN" \
  -F "file=@raport-v2.pdf;type=application/pdf" -F "comentariu=corectat anexa 2"

# 2) listează versiunile
curl -s "$BASE/api/documents/42/versions" -H "Authorization: Bearer $TOKEN" | jq .

# 3) descarcă versiunea 1 (conținutul original)
curl -L "$BASE/api/documents/42/versions/1/download" -H "Authorization: Bearer $TOKEN" -o raport-v1.pdf

# 4) restaurează versiunea 1 (devine versiunea curentă, ex. v3)
curl -X POST "$BASE/api/documents/42/versions/1/restore" -H "Authorization: Bearer $TOKEN"

În UI (Documentele mele → deschide un document → butonul 🕘 Versiuni): listă cu nr./mărime/autor/dată/comentariu și badge „curentă”, plus Încarcă versiune nouă, ⬇ Descarcă și ⟲ Restaurează per versiune.

Conectori externi (import din servicii)

Un utilizator își leagă contul Google (Drive/Docs) sau GitLab (OAuth2 authorization-code) și importă documente specifice. Fiecare element importat e fie Copie (octeți copiați în gdocs → Document, re-sincronizabil ca versiune) fie Legătură (referință live — conținutul e adus din furnizor la cerere, fără copie).

Metodă	Cale	Acces	Descriere
GET	/api/conexiuni	auth	conexiunile utilizatorului + status
GET	/api/conexiuni/{furnizor}/authorize	auth	→ { authorizationUrl } (furnizor = google|gitlab); se deschide în popup
GET	/api/conexiuni/{furnizor}/callback?code&state	pub	callback OAuth (identitate din state semnat HS512); închide popup-ul
DELETE	/api/conexiuni/{furnizor}	auth	deconectează (șterge token-urile)
GET	/api/conexiuni/{furnizor}/fisiere?kind=&path=&ref=&q=	auth	navighează fișierele remote (GitLab kind = repo|wiki|snippet)
POST	/api/documents/import	auth	import (multi-select + mod per element)
POST	/api/documents/{id}/resync	auth	re-sincronizează un document COPIE → versiune nouă dacă sursa s-a schimbat

Body import: { "furnizor": "GOOGLE|GITLAB", "items": [ { "ref": "...", "mod": "COPIE|LEGATURA", "formatExport": "pdf|office|both", "denumire": "...", "urlWeb": "..." } ], "bucketId": null, "secret": false }.

Note:

• Fișierele native Google (Docs/Sheets/Slides) se exportă (formatExport): pdf, office (docx/xlsx/pptx) sau both (PDF document + Office ca versiune).
• Documentele SECRET nu se importă pe acest canal; o Legătură se descarcă live prin GET /api/documents/{id}/download (409 dacă conexiunea nu mai e validă) și se deschide în furnizor prin urlWeb.
• Configurare: gdocs.integrations.{google,gitlab} (client-id/secret din env) + aplicații OAuth cu redirect …/api/conexiuni/{furnizor}/callback.

Partajare & cereri de acces

Metodă	Cale	Acces	Descriere
POST	/api/documents/{id}/partajeaza	auth (writer/owner)	acordă acces: { beneficiarClientId? , beneficiarOperatorId? , drept, dataExpirare? }
POST	/api/documents/cerere	auth	cere acces după cod: { cod, drept, motivare }
POST	/api/cereri/{id}/aproba | /respinge	admin	soluționează o cerere (aprobare → grant)

Semnătură (MSign)

Metodă	Cale	Acces	Descriere
POST	/api/documents/{id}/semneaza	auth (writer)	semnează: { semnatar }
POST	/api/semnaturi/{id}/verifica	auth	reverifică (VALIDA/INVALIDA)
GET	/api/documents/{id}/semnaturi	auth	semnăturile documentului

Căutare (Elasticsearch)

Metodă	Cale	Acces	Descriere
GET	/api/search/documente?q=&size=	auth	full-text + facete pe etichete; re-filtrat prin ACL
POST	/api/admin/search/reindex	admin	reindexare

Multi-tenancy

Metodă	Cale	Acces	Descriere
GET	/api/tenant/me	auth	tier + organizatieId + bucket-uri
GET	/api/tenant/buckets	auth	bucket-urile vizibile (selector upload)
GET	/api/admin/organizatii	admin (service)	listă organizații
POST	/api/admin/organizatii	admin (service)	creare: { cod, denumire, idno }
PUT	/api/admin/organizatii/{id}	admin (service)	editare: { denumire, idno, statut }
PUT	/api/admin/organizatii/{id}/statut	admin (service)	{ statut }
GET	/api/admin/buckets	admin	listă bucket-uri (scopat)
POST	/api/admin/buckets	admin	creare: { organizatieId, cod, denumire, provider?, endpoint?, regiune?, accessKey?, secret? }
PUT	/api/admin/buckets/{id}	admin	editare / mutare între organizații / conexiune S3
PUT	/api/admin/buckets/{id}/activ	admin	{ activ }
GET	/api/admin/bucket-acces?bucketId=	admin	membrii unui bucket
POST	/api/admin/bucket-acces	admin	acordă: { bucketId, appUserId, rol } (ADMIN/OPERATOR)
DELETE	/api/admin/bucket-acces/{id}	admin	revocă
GET	/api/admin/tenant-users	admin	utilizatori + organizația lor
PUT	/api/admin/tenant-users/{id}/organizatie	admin	asignează: { organizatieId } (null = dezasignează)

Templaturi

Metodă	Cale	Acces	Descriere
GET/POST/PUT/PATCH/DELETE	/api/templates[...]	auth	CRUD standard
GET	/api/templates/{id}/export	auth	export JSON
POST	/api/templates/import	auth	import (multipart)
POST	/api/templates/render	auth	preview {{var}} → text
POST	/api/templates/{id}/genereaza	auth	generează document real (PDF/DOCX)
POST	/api/templates/{id}/descarca	auth	descarcă rezultatul generat

Transcriere / OCR

Metodă	Cale	Acces	Descriere
POST	/api/transcriere	auth	transcrie un document: { documentId, tip }
POST	/api/transcriere/upload	auth	transcrie un fișier (multipart)
GET	/api/transcriere/{id}/text | /download	auth	text / fișier rezultat
POST	/api/transcriere/{id}/salveaza	auth	salvează rezultatul ca document nou

Public (L1, fără autentificare)

Metodă	Cale	Descriere
GET	/api/public/documents?q=&format=&size=	căutare L1 (doar PUBLIC + ACTIV)
GET	/api/public/documents/{id}	metadate (404 dacă nu e public)
GET	/api/public/documents/{id}/download	download L1

API mașină /api/v1 (machine)

Metodă	Cale	Acces	Descriere
POST	/api/v1/token	pub	client-credentials → { access_token, scope, emitent, expires_in }
GET	/api/v1/documents	machine (documente.read)	listă (PUBLIC ∪ PERSONAL ale emitentului; L3 niciodată)
GET	/api/v1/documents/{cod}	machine	metadate
GET	/api/v1/documents/{cod}/continut	machine	download
POST	/api/v1/documents	machine (documente.write)	ingest (multipart)
GET	/api/v1/documents/{cod}/versiuni	machine (documente.read)	istoricul versiunilor (backfill v1 la nevoie; L3 niciodată)
POST	/api/v1/documents/{cod}/versiuni	machine (documente.write)	încarcă o versiune nouă (multipart file + comentariu?)
GET	/api/v1/documents/{cod}/versiuni/{numar}/continut	machine (documente.read)	descarcă o versiune anume (numar = 1, 2, …)
POST	/api/v1/documents/{cod}/versiuni/{numar}/restaurare	machine (documente.write)	restaurează versiunea numar (forward-only)
GET	/api/v1/templates | /{cod}	machine	templaturi publicate
POST	/api/v1/templates/{cod}/render	machine	render

Versionarea pe canalul mașină e adresată după cod (ca restul /api/v1), delimitată de scope-uri (documente.read/documente.write) și emitentul din token; documentele SECRET nu sunt niciodată expuse aici. Răspuns versiune: { numarVersiune, dimensiune, hashSha256, extensie, format, contentType, comentariu, creatDe, creatLa, curenta } (creatDe = machine:<clientId>).

MT=$(curl -s -X POST $BASE/api/v1/token -d 'grant_type=client_credentials&client_id=...&client_secret=...' | jq -r .access_token)
# încarcă o versiune nouă a documentului DOC-2026-000042
curl -X POST "$BASE/api/v1/documents/DOC-2026-000042/versiuni" -H "Authorization: Bearer $MT" \
  -F "file=@raport-v2.pdf;type=application/pdf" -F "comentariu=actualizare automată"
# listează + descarcă versiunea 1
curl -s "$BASE/api/v1/documents/DOC-2026-000042/versiuni" -H "Authorization: Bearer $MT" | jq .
curl -L "$BASE/api/v1/documents/DOC-2026-000042/versiuni/1/continut" -H "Authorization: Bearer $MT" -o v1.pdf

Administrare

Metodă	Cale	Acces	Descriere
GET/POST/PUT/DELETE	/api/admin/users[...]	admin	gestionare jhi_user
GET	/api/admin/machine-clients	admin	clienți v1 (fără secrete)
POST	/api/admin/maintenance/run	admin	rulează arhivarea/purjarea

Entități de referință (CRUD JHipster)

Fiecare are: GET (listă+filtre+paginare), GET /count, GET /{id}, POST , PUT /{id}, PATCH /{id}, DELETE /{id}.

/api/clients · /api/emitents · /api/rols · /api/app-users · /api/cerere-acces · /api/partajare-documents · /api/eveniment-documents (append-only) · /api/conversies · /api/semnatura-documents · /api/authorities

Health & Info

GET /management/health · GET /management/info · GET /management/prometheus (pub); restul /management/** = admin.