Contratto endpoint API (trailing slash)
Questa pagina documenta la convenzione canonica dei path dell’API XIQUIL e il comportamento del trailing slash (/ finale). È rilevante per chi integra l’API da automazioni o script esterni.
Regola canonica: niente trailing slash sui metodi mutanti
Sezione intitolata “Regola canonica: niente trailing slash sui metodi mutanti”I path REST di XIQUIL sono registrati senza slash finale. Per i metodi che modificano dati (POST, PUT, DELETE) usa sempre la forma senza slash:
✅ POST /api/uscite/42/fattura-elettronica❌ POST /api/uscite/42/fattura-elettronica/Perché: il redirect 307
Sezione intitolata “Perché: il redirect 307”Il backend (FastAPI) ha il redirect automatico dei trailing slash attivo. Se chiami un path con lo slash finale quando l’operazione è registrata senza (o viceversa), il server risponde con un 307 Temporary Redirect verso la forma canonica.
- Un browser o un client HTTP “ben educato” (es.
axios,curl -L) segue il 307 ri-inviando metodo, body e header (inclusi i cookie di autenticazione): la chiamata va a buon fine. - Un client di automazione che non segue i redirect, o che non re-invia le credenziali sul redirect, può ricevere un 401 o un risultato vuoto — un falso negativo: i dati erano corretti, ma la
/di troppo ha causato il problema.
I client first-party di XIQUIL (web app) usano già esclusivamente la forma canonica senza slash.
Tabella endpoint — Fattura Elettronica e Documento Generico
Sezione intitolata “Tabella endpoint — Fattura Elettronica e Documento Generico”I satellite documentali sono nested sotto l’owner Uscita/Entrata. Nota l’asimmetria di naming intenzionale: le Uscite usano path lunghi, le Entrate path abbreviati (fe/dg).
| Area | Documento | Metodi | Path canonico (senza slash) |
|---|---|---|---|
| Uscite | Fattura Elettronica | GET · POST · PUT · DELETE | /api/uscite/{uscita_id}/fattura-elettronica |
| Uscite | Documento Generico | GET · POST · PUT · DELETE | /api/uscite/{uscita_id}/documento-generico |
| Entrate | Fattura Elettronica | GET · POST · PUT · DELETE | /api/entrate/{entrata_id}/fe |
| Entrate | Documento Generico | GET · POST · PUT · DELETE | /api/entrate/{entrata_id}/dg |
Tutti gli endpoint sopra sono registrati senza slash finale.