Autenticazione

L'API di accesso fornisce i token di accesso JWT necessari per tutti gli endpoint protetti.

Percorso base: /api/v1

---

POST /api/v1/login

Accesso standard — restituisce token di accesso e di aggiornamento.

Autenticazione: Nessuna (endpoint pubblico)

Richiesta:

{
  "username": "mario.rossi",
  "password": "PasswordSicura@1"
}

Campo	Tipo	Obbligatorio	Descrizione
username	String	Obbligatorio	Nome di accesso utente
password	String	Obbligatorio	Password utente

Risposta 200 OK:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Codici di stato:

Codice	Descrizione
200 OK	Accesso riuscito
400 Bad Request	Errore di validazione (campi mancanti)
401 Unauthorized	Credenziali non valide

---

POST /api/v1/login-extended

Restituisce il token di accesso con informazioni aggiuntive sull'utente (codice deposito, timestamp di scadenza). Utilizzarlo quando la propria integrazione necessita di conoscere il codice deposito o l'esatta scadenza del token.

Autenticazione: Nessuna (endpoint pubblico)

Richiesta: identica a /login

Risposta 200 OK:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userName": "mario.rossi",
  "depotCode": "0699",
  "expireAt": "2025-10-30T18:30:00Z"
}

Campo	Tipo	Descrizione
token	String	Token di accesso JWT
refreshToken	String	Token di aggiornamento JWT
userName	String	Nome utente autenticato
depotCode	String	Primo codice deposito non vuoto tra gli indirizzi di ritiro dell'utente
expireAt	ISO 8601	Timestamp di scadenza del token

Codici di stato:

Codice	Descrizione
200 OK	Accesso riuscito
400 Bad Request	Errore di validazione
401 Unauthorized	Credenziali non valide
403 Forbidden	Contesto di accesso automatico mancante

---

Utilizzo dei token

Includere il JWT in ogni richiesta successiva:

curl -X GET "https://label-print-shipments.dpd.ch/api/v1/tracking/05305000123456" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const response = await fetch('https://label-print-shipments.dpd.ch/api/v1/shipments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(shipmentData)
});

Scadenza del token

• Il TTL predefinito è configurato per ogni ambiente (tipicamente 24 ore)
• Una risposta 401 Unauthorized indica che il token è scaduto
• Autenticarsi nuovamente con /login per ottenere un nuovo token

Lista di controllo sicurezza

• Utilizzare sempre HTTPS in produzione
• Conservare i token in cookie HTTP-only sicuri o in un archivio sicuro — mai in localStorage
• Non esporre mai i token negli URL o nei file di log
• Eliminare i token al momento della disconnessione