API HTTP¶

L'applicazione api/ espone in JSON le stesse operazioni dell'interfaccia web, in lettura e in scrittura. Tutte le rotte stanno sotto /v1/: le rotte senza versione delle release precedenti sono state rimosse e rispondono 404.

La specifica completa, in OpenAPI 3.1, è in api/web/openapi-v1.yaml ed è servita all'indirizzo /api/web/openapi-v1.yaml: si apre con Swagger Editor, Postman o Insomnia.

La documentazione interattiva (Swagger UI) è all'indirizzo /api/web/docs/ in XAMPP e /docs/ del servizio api in Docker (vedi Deploy): con Authorize si inserisce il token personale, oppure il token master più l'utente in actAs (X-Act-As), e si provano le chiamate dalla pagina.

Architettura¶

L'API non ha logica propria. Ogni operazione passa dagli stessi servizi di common/services usati dai controller del frontend, che sono adattatori sottili come i controller dell'API:

Area	Servizio
Task: creazione, modifica, spostamento, completamento, sotto-task, ricorrenza, letta/non letta	`TaskWorkflow`, `TaskRecurrenceWriter`
Notifiche e stato "non letto" delle task	`TaskNotifier`
Permessi sulle task, task bloccate, eliminazione riservata	`TaskAccess`
Etichette, iscrizione, checklist, commenti, relazioni, promemoria, ore, allegati	`TaskParts`, `AttachmentDownload`
Azioni di massa	`TaskBulkOperation`
Bacheche: archivio, aspetto, sigla, preferiti, ordine degli stati, viste, filtri, webhook, link	`BoardSettings`, `BoardListService`
Modelli di bacheca: istantanea, creazione da modello, visibilità, predefinito	`BoardTemplateService`
Importazione ed esportazione CSV	`BoardCsv`
Team, membri, ruoli personalizzati, ricerca utenti	`TeamMembershipService`, `TeamPermissionResolver`
Riunioni e punti	`MeetingWorkflow`
Assenze	`LeaveService`
Ricerca	`TaskSearch`
Etichette: chi le gestisce	`TagPolicy`
Reazioni ai commenti	`TaskParts::react()`
Ordine personale delle bacheche	`BoardSettings::orderBoards()`
Le mie task: filtri, statistiche, ordine personale, giornata	`MyTasks`
Dashboard e report ore	`DashboardStats`, `TimesheetService`
Novità e guida	`ReleaseNotes`, `Guide`
Amministrazione	`AdminScope`, `AdminStats`, `UserAdministration`, `GlobalRoleManager`, `TeamMembershipService`, `TrashService`

Ogni azione dell'interfaccia e del pannello ha il suo endpoint, con poche eccezioni volute: le credenziali (password, verifica in due passaggi, token personali e master), le iscrizioni Web Push del browser, le pagine pubbliche dei link di condivisione e la coda dei log. Da questo elenco completo il connettore MCP ricava i tool di Claude.

Così una regola (una task bloccata non si modifica, un team non resta senza amministratore, una riunione completata è in sola lettura) vale identica da qualunque punto d'ingresso, e notifiche e webhook partono sempre nello stesso ordine.

Autenticazione¶

Ogni richiesta porta il token personale dell'utente nell'intestazione Authorization:

Authorization: Bearer IL_TUO_TOKEN

Il token si genera dalla pagina Profilo → Token API e viene mostrato una sola volta. Generarne uno nuovo invalida il precedente; la revoca chiude subito ogni integrazione. Nel database ne resta solo l'impronta sha256, e vale solo per gli account attivi.

Nome utente, email e password non si cambiano dall'API: un token rubato non deve bastare a prendersi l'account.

Al posto del token personale si può usare un token OAuth (prefisso gto_), quello che riceve il connettore MCP dopo il consenso dell'utente: vale allo stesso modo e si revoca da Profilo → App collegate.

Token master¶

Un token master non appartiene a nessun account: opera per conto dell'utente indicato nell'intestazione X-Act-As (uuid o email), solo sulle operazioni abilitate al momento della creazione.

Authorization: Bearer gtm_...
X-Act-As: mario.rossi@example.com

La richiesta vale come se la facesse l'utente indicato: servono sia l'operazione abilitata sul token sia i permessi di quell'utente. Storia della task, autore e limite di richieste sono i suoi; nel registro delle operazioni l'autore compare come utente via nome-token.
Le operazioni sono le rotte della v1 (controller/action, es. task/history, task/create), raggruppate per modulo nella pagina di gestione.
Errori: 400 senza X-Act-As o con un utente inesistente o non attivo, 403 per un'operazione non abilitata, 401 per un token revocato.
I token master si creano, modificano e revocano dal pannello di amministrazione, voce Token master, visibile solo agli account in params['masterTokenAdmins']. Il valore si vede una sola volta.

api/web/.htaccess inoltra l'intestazione Authorization a PHP: senza quella riga Apache la scarta e ogni richiesta risulterebbe non autenticata.

Convenzioni della v1¶

Solo uuid. Le risorse si indirizzano per uuid negli URL e nei corpi; utenti, stati, task padre e filtri escono come riferimenti con uuid. I modelli definiscono fields() come lista chiusa: una colonna nuova non viene esposta per errore, e segreti (firma dei webhook, token dei link, destinazioni di notifica) non escono mai.
Rotte dichiarate. Il parsing degli URL è rigoroso: ogni rotta ha il suo verbo, e un percorso o un verbo non previsto risponde 404.
PATCH parziali. Cambiano solo i campi inviati.
Sotto-risorse. Si creano ed elencano sotto la risorsa padre e si modificano o eliminano con il proprio uuid: POST /v1/tasks/{uuid}/checklist, PATCH /v1/checklist/{uuid}.
Stati personali con PUT e DELETE: PUT /v1/tasks/{uuid}/subscription iscrive, DELETE disiscrive; lo stesso per unread, favorite, le etichette di una task.
Codici. 201 alla creazione con la risorsa nel corpo, 204 senza corpo all'eliminazione.
Permessi nella risposta. Task, bacheche, team e riunioni riportano un oggetto permissions con cosa l'utente può fare: il client mostra i comandi giusti senza tentare e ricevere un 403.
Espansioni. GET /v1/tasks/{uuid}?expand=checklist,comments,history aggiunge le parti della scheda richieste (subtasks, checklist, attachments, relations, incoming_relations, reminders, worklogs, history, comments, recurrence).
Date. AAAA-MM-GG per le date, AAAA-MM-GG HH:MM per data e ora, in ora locale del server.

Aree¶

Area	Rotte principali
Utente	`GET/PATCH /v1/me`, `GET/PATCH /v1/me/preferences`, `GET /v1/me/notifications`, `GET /v1/me/tasks` (filtri della sezione «Le mie task»: `group` (anche `today`), `board`, `team`, `tag`, `priority`, `deadline`, `blocked`, `q`, `sort`; `subtasks` e `subscribed` aggiungono sottotask assegnate e task seguite, spente di default), `GET /v1/me/tasks/stats` (stesse due opzioni, e la risposta dice quali include), `PUT /v1/me/tasks/order`, `PUT/DELETE /v1/me/tasks/{uuid}/today`, `GET /v1/me/calendar`
Team	`GET/POST /v1/teams`, `GET/PATCH /v1/teams/{uuid}`, membri, ruoli, `PUT /v1/teams/{uuid}/permissions`, calendario, report, `GET /v1/users?q=`
Bacheche	`GET/POST /v1/boards`, `GET/PATCH /v1/boards/{uuid}`, task filtrate, azioni di massa, import ed export CSV
Stati	`GET/POST /v1/boards/{uuid}/lists`, `PUT /v1/boards/{uuid}/lists/order`, `PATCH/DELETE /v1/lists/{uuid}`
Configurazione	viste, filtri salvati, webhook (con prova e riconsegna), link pubblici
Etichette	`GET/POST /v1/tags`, `PATCH /v1/tags/{uuid}`
Task	`POST /v1/boards/{uuid}/tasks`, `GET/PATCH/DELETE /v1/tasks/{uuid}`, complete, move, transfer (in un'altra bacheca), duplicate, sotto-task, cronologia
Parti della task	checklist, commenti, relazioni, promemoria, ore lavorate, allegati
Riunioni	`GET/POST /v1/meetings`, avvio, completamento, riapertura, punti, importazione, task nate in riunione
Assenze	`GET/POST /v1/leaves`, `PATCH/DELETE /v1/leaves/{uuid}`
Ricerca	`GET /v1/search?q=`
Cestino	`GET /v1/trash`, ripristino, eliminazione definitiva, svuotamento
Profilo	`PUT/DELETE /v1/me/calendar-feed`, `POST/DELETE /v1/me/avatar`, `PUT /v1/teams/{uuid}/board-order`
Modelli di bacheca	`GET /v1/board-templates`, `GET/PATCH/DELETE /v1/board-templates/{uuid}`, `POST /v1/boards/{uuid}/template`, predefinito
Reazioni	`PUT/DELETE /v1/comments/{uuid}/reactions`
Dashboard e ore	`GET /v1/me/dashboard`, `GET /v1/users/{uuid}/dashboard`, `GET /v1/teams/{uuid}/dashboard`, `GET /v1/dashboard/global`, `GET /v1/timesheet`
Informazioni	`GET /v1/releases`, `POST /v1/releases/seen`, `GET /v1/guide`, `GET /v1/guide/{slug}`
Amministrazione	`/v1/admin/*`: quadro, utenti, ruoli globali, team, bacheche, modelli, etichette, registro, cache; per chi accede al pannello

L'elenco completo, con parametri, corpi e risposte, è nella specifica OpenAPI e in api/config/routes-v1.php.

Campi scelti¶

Le collezioni accettano ?fields=a,b: ogni elemento esce con i soli campi indicati (es. GET /v1/me/tasks?fields=uuid,key,title,status). Utile per gli elenchi di task, che con tutti i campi sono pesanti; il connettore MCP lo usa di default.

Paginazione¶

Le collezioni lunghe accettano ?page= e ?per_page= (predefinito 25, massimo 100) e restituiscono il totale nel corpo:

{
  "data": [ … ],
  "meta": { "page": 1, "per_page": 25, "total": 42, "pages": 2 }
}

Gli elenchi brevi per natura (stati, checklist, viste) escono interi, con meta.total.

Permessi¶

Ogni operazione risolve il team dalla risorsa (task → stato → bacheca → team) e delega a RBAC con gli stessi permessi dell'interfaccia: board.view per leggere, task.create, task.update, task.move per lavorare sulle task, board.manage per la configurazione della bacheca, team.manage per il team, tag.manage e tag.global per le etichette. Eliminare task resta riservato ai super amministratori e allo spazio personale (TrashPolicy). La matrice completa è in Team e ruoli.

Errori¶

Gli errori della v1 hanno sempre la stessa forma:

{
  "error": {
    "status": 422,
    "code": "validation_failed",
    "message": "I dati inviati non sono validi.",
    "fields": { "title": ["Campo obbligatorio."] }
  }
}

Stato	`code`	Quando
`401`	`unauthorized`	Token assente, non valido o utente non attivo.
`403`	`forbidden`	Permesso non concesso, task bloccata, riunione completata.
`404`	`not_found`	uuid inesistente o rotta non prevista.
`422`	`validation_failed`	Input malformato (`fields` elenca tutti i campi da correggere) o regola di dominio violata.
`429`	`too_many_requests`	Limite di richieste superato.
`500`	`internal_error`	Errore interno; in produzione senza dettagli.

Limiti di frequenza¶

120 richieste al minuto per utente. Ogni risposta riporta X-Rate-Limit-Limit, X-Rate-Limit-Remaining e X-Rate-Limit-Reset.

Migrazione dalle rotte senza versione¶

Le rotte senza versione (/me, /boards, /tasks…) non esistono più. Per un client scritto per loro:

Prima	Ora
`POST /tasks` con `list`	`POST /v1/boards/{uuid}/tasks`, `list` facoltativo
`PATCH`/`PUT /tasks/{uuid}`	`PATCH /v1/tasks/{uuid}`
`DELETE /tasks/{uuid}` → `{"deleted": true}`	`DELETE /v1/tasks/{uuid}` → `204`
`assignee` (uuid singolo)	`assignees` (elenco di uuid)
`due_at` in scrittura	`ends_at` (`due_at` resta solo in lettura)
errori `{"errors": {...}}`	`{"error": {status, code, message, fields}}`

Test¶

I test HTTP dell'API stanno in api/tests/Functional e attraversano rotte, autenticazione, permessi e serializzazione:

php vendor/bin/codecept run -c api Functional

Limiti attuali¶

Le notifiche push del browser (iscrizione web push) non sono esposte: servono solo al browser.
Le credenziali non si gestiscono dall'API: password, verifica in due passaggi, token personali e master, propri o altrui.
Il report di team e quello delle ore non hanno l'esportazione CSV: escono in JSON.
L'importazione CSV, come dall'interfaccia, non invia notifiche né webhook per le task create.