SIMPLYFAD API

Documentazione pubblica core

Esempio login

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@simplyfad.local",
  "password": "simplyfad123",
  "sessionId": "web-uuid-session",
  "tenantId": "11111111-1111-1111-1111-111111111111"
}

Response tipica

{
  "accessToken": "simplyfad-dev-token:tenant:user:session",
  "user": {
    "email": "admin@simplyfad.local",
    "firstName": "Admin",
    "lastName": "Tenant",
    "role": "tenant_admin"
  },
  "tenantContext": {
    "tenantId": "11111111-1111-1111-1111-111111111111",
    "companyId": "33333333-3333-3333-3333-333333333333",
    "role": "tenant_admin"
  }
}

Header standardAuthorization: Bearer <token>x-sync-api-key: <key>

Gli endpoint tecnici di handoff e sync non richiedono sessione utente, ma sono protetti da chiave applicativa. Tutti gli altri endpoint protetti lavorano con token Bearer e applicano tenant scope e controllo ruoli lato backend.

01 · Auth

Autenticazione e sessione

POST/api/v1/auth/login

Autentica un utente e restituisce token, profilo utente e contesto tenant.

Accesso

Pubblico

Body

email
password
sessionId
tenantId opzionale

POST/api/v1/auth/handoff/issue

Genera un token temporaneo di handoff per aprire una sessione learner o admin senza reinserire credenziali.

Accesso

Pubblico con x-sync-api-key

Headers

x-sync-api-key

Body

email
tenantSlug opzionale
redirectPath opzionale

POST/api/v1/auth/handoff/consume

Consuma il token di handoff e crea la sessione applicativa finale.

Accesso

Pubblico

Body

token
sessionId

GET/api/v1/auth/me

Restituisce utente autenticato e tenantScope attivo della richiesta.

Accesso

Bearer token

POST/api/v1/auth/session/heartbeat

Aggiorna tracking di sessione e presenza applicativa dell’utente.

Accesso

Bearer token

02 · Tenant

Tenant, aziende, sedi e reparti

Gestione multi-tenant del core, più endpoint pubblici minimi per risoluzione tenant.

GET/api/v1/tenants

Elenca i tenant visibili all’utente autenticato.

Accesso

super_admin, tenant_admin

GET/api/v1/tenants/current

Restituisce il tenant attivo della sessione.

Accesso

Bearer token

GET/api/v1/tenants/public/:slug

Risoluzione pubblica di un tenant tramite slug.

Accesso

Pubblico

POST/api/v1/tenants

Crea un nuovo tenant operativo.

Accesso

super_admin

Body

name
slug opzionale
status opzionale

PATCH/api/v1/tenants/:tenantId

Aggiorna tenant esistente.

Accesso

super_admin

DELETE/api/v1/tenants/:tenantId

Elimina il tenant selezionato.

Accesso

super_admin

GET/api/v1/tenants/current/companies

Elenco aziende del tenant attivo.

Accesso

super_admin, tenant_admin

POST/api/v1/tenants/current/companies

Crea una nuova azienda nel tenant attivo.

Accesso

super_admin, tenant_admin

Body

name
vatNumber opzionale

GET/api/v1/tenants/current/sites

Elenco sedi del tenant attivo.

Accesso

super_admin, tenant_admin

POST/api/v1/tenants/current/sites

Crea una nuova sede.

Accesso

super_admin, tenant_admin

Body

companyId
name
code opzionale
city opzionale

GET/api/v1/tenants/current/departments

Elenco reparti del tenant attivo.

Accesso

super_admin, tenant_admin

POST/api/v1/tenants/current/departments

Crea un nuovo reparto.

Accesso

super_admin, tenant_admin

Body

companyId
siteId opzionale
name
code opzionale

03 · Users

Utenti e profili

Anagrafica utente completa, con dati personali, gerarchia aziendale e ruolo applicativo.

GET/api/v1/users

Elenca gli utenti del tenant corrente.

Accesso

super_admin, tenant_admin

GET/api/v1/users/:id

Recupera il dettaglio di un utente.

Accesso

Bearer token

POST/api/v1/users

Crea un nuovo utente.

Accesso

super_admin, tenant_admin

Body

tenantId
companyId
siteId opzionale
departmentId opzionale
title
firstName
lastName
birthProvince
birthPlace
sex
birthDate
taxCode
email
phone opzionale
mobile opzionale
nationality
residence
address
city
zipCode
province
password
role
auditableCourseIds opzionale

PATCH/api/v1/users/:id

Aggiorna anagrafica, ruolo e appartenenze dell’utente.

Accesso

super_admin, tenant_admin

DELETE/api/v1/users/:id

Rimuove l’utente dal tenant corrente.

Accesso

super_admin, tenant_admin

04 · Courses

Corsi, moduli e lezioni

Authoring completo del catalogo formativo interno: corso, moduli, lezioni e propedeuticità.

GET/api/v1/courses

Elenca i corsi visibili nel tenant.

Accesso

super_admin, tenant_admin, auditor

GET/api/v1/courses/:id

Dettaglio completo del corso selezionato.

Accesso

super_admin, tenant_admin, auditor

POST/api/v1/courses

Crea un nuovo corso.

Accesso

super_admin, tenant_admin

Body

title
description opzionale
imageUrl opzionale
certificateBackgroundUrl opzionale
certificateValidityYears opzionale
category opzionale
durationMinutes opzionale
priceCents opzionale
currency opzionale
isPurchasable opzionale
deliveryCourseId opzionale
status opzionale
prerequisiteCourseId opzionale

PATCH/api/v1/courses/:id

Aggiorna dati base del corso.

Accesso

super_admin, tenant_admin

GET/api/v1/courses/:id/modules

Elenca i moduli del corso.

Accesso

super_admin, tenant_admin

POST/api/v1/courses/:id/modules

Crea un modulo del corso.

Accesso

super_admin, tenant_admin

Body

title
sortOrder
quizTitle opzionale
prerequisiteModuleId opzionale

PATCH/api/v1/courses/:id/modules/:moduleId

Aggiorna un modulo esistente.

Accesso

super_admin, tenant_admin

POST/api/v1/courses/:id/modules/:moduleId/lessons

Crea una lezione nel modulo.

Accesso

super_admin, tenant_admin

Body

title
sortOrder
contentType
contentUrl opzionale
estimatedMinutes opzionale
prerequisiteLessonId opzionale

PATCH/api/v1/courses/:id/modules/:moduleId/lessons/:lessonId

Aggiorna una lezione esistente.

Accesso

super_admin, tenant_admin

DELETE/api/v1/courses/:id/modules/:moduleId/lessons/:lessonId

Elimina una lezione.

Accesso

super_admin, tenant_admin

05 · Assignments

Assegnazioni

Collega i corsi a singoli utenti o target organizzativi: tenant, sede o reparto.

GET/api/v1/assignments

Elenca le assegnazioni del tenant.

Accesso

super_admin, tenant_admin

POST/api/v1/assignments

Crea una nuova assegnazione.

Accesso

super_admin, tenant_admin

Body

courseId
targetType = user | department | site | tenant
targetUserId opzionale
targetDepartmentId opzionale
targetSiteId opzionale
dueAt opzionale

PATCH/api/v1/assignments/:id

Aggiorna scadenza o target dell’assegnazione.

Accesso

super_admin, tenant_admin

DELETE/api/v1/assignments/:id

Elimina l’assegnazione selezionata.

Accesso

super_admin, tenant_admin

06 · Enrollments

Fruizione learner e tracking

Area learner, avanzamento, tracking sessioni, attestato e sincronizzazione controllata via email.

GET/api/v1/enrollments

Elenco enrollment filtrabile per corso lato admin.

Accesso

super_admin, tenant_admin, auditor

Query

courseId opzionale

GET/api/v1/enrollments/me

Restituisce gli enrollment del learner autenticato.

Accesso

Bearer token

GET/api/v1/enrollments/sync/by-email

Endpoint tecnico di lookup enrollment per integrazioni esterne controllate.

Accesso

Pubblico con x-sync-api-key

Headers

x-sync-api-key

Query

email opzionale
tenantSlug opzionale

GET/api/v1/enrollments/:id

Dettaglio enrollment singolo.

Accesso

Bearer token

GET/api/v1/enrollments/:id/tracking

Tracking completo di accessi, permanenza e progressione.

Accesso

Bearer token

GET/api/v1/enrollments/:id/certificate

Recupera attestato associato all’enrollment se disponibile.

Accesso

Bearer token

PATCH/api/v1/enrollments/:id/start

Segna ufficialmente l’avvio del corso learner.

Accesso

Bearer token

PATCH/api/v1/enrollments/:id/lessons/:lessonId

Aggiorna completamento della singola lezione.

Accesso

Bearer token

Body

completed boolean

07 · Quiz

Quiz authoring e tentativi learner

Gestione dei quiz lato admin e flusso tentativi lato learner per modulo, finale corso e valutazione.

POST/api/v1/courses/:courseId/quizzes

Crea un quiz sul corso.

Accesso

super_admin, tenant_admin

Body

title
kind = module | final | evaluation
moduleId opzionale
passingPercentage opzionale
questionCount opzionale
maxAttempts opzionale
timeLimitMinutes opzionale
generateDefaultQuestions opzionale

PATCH/api/v1/courses/:courseId/quizzes/:quizId

Aggiorna quiz esistente.

Accesso

super_admin, tenant_admin

DELETE/api/v1/courses/:courseId/quizzes/:quizId

Elimina il quiz selezionato.

Accesso

super_admin, tenant_admin

POST/api/v1/courses/:courseId/quizzes/:quizId/reset-attempts

Resetta i tentativi del quiz.

Accesso

super_admin, tenant_admin

POST/api/v1/courses/:courseId/quizzes/:quizId/questions

Aggiunge una domanda al quiz.

Accesso

super_admin, tenant_admin

Body

prompt
sortOrder
questionType = true_false | single_choice | rating_scale
options opzionale
correctAnswer opzionale

PATCH/api/v1/courses/:courseId/quizzes/:quizId/questions/:questionId

Aggiorna una domanda esistente.

Accesso

super_admin, tenant_admin

DELETE/api/v1/courses/:courseId/quizzes/:quizId/questions/:questionId

Elimina una domanda dal quiz.

Accesso

super_admin, tenant_admin

GET/api/v1/enrollments/:enrollmentId/quizzes

Elenca i quiz disponibili per l’enrollment learner.

Accesso

Bearer token

POST/api/v1/enrollments/:enrollmentId/quizzes/:quizId/attempts/start

Avvia un nuovo tentativo quiz.

Accesso

Bearer token

POST/api/v1/enrollments/:enrollmentId/quizzes/:quizId/attempts/:attemptId/submit

Invia le risposte del tentativo quiz.

Accesso

Bearer token

Body

answers[{ questionId, value }]

Esempio authoring

Creazione corso base

POST /api/v1/courses
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Sicurezza base in magazzino",
  "description": "Corso introduttivo per operatori warehouse",
  "category": "Compliance",
  "status": "published",
  "durationMinutes": 180,
  "prerequisiteCourseId": null
}

Convenzioni consigliate

Usa UUID reali per `tenantId`, `courseId`, `moduleId`, `lessonId`.
Invia sempre `sessionId` stabile dal client per heartbeat e login.
Limita `x-sync-api-key` solo ai servizi trusted di integrazione.
Documenta nel client anche il ruolo atteso per ciascun endpoint.

Prossimo step

Se vuoi, il passo successivo è generare anche una versione OpenAPI/Swagger machine-readable partendo da questi stessi endpoint del backend.