Errori di autenticazione

Spiegazioni dettagliate e soluzioni per gli errori relativi all'autenticazione.

---

HTTP 401 Unauthorized

{
  "status": 401,
  "error": "Unauthorized",
  "message": "JWT token is missing or invalid"
}

Lista di controllo:

Verifica	Atteso
Nome intestazione	Authorization (con A maiuscola)
Prefisso del valore	Bearer (con uno spazio dopo Bearer)
Origine del token	Campo token dalla risposta di /api/v1/login
Token non scaduto	Verificare expireAt via /api/v1/login-extended
Nessun carattere extra	Rimuovere gli spazi prima/dopo la stringa del token

---

HTTP 401 — Token scaduto

I token hanno un TTL finito configurato sul server. Una volta scaduti, ogni richiesta restituisce 401.

Soluzione: Effettuare nuovamente l'accesso:

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "your_user", "password": "your_pass"}'

Prevenzione — rinnovare proattivamente prima della scadenza:

// Store expiry time from /login-extended
const tokenExpiry = new Date(loginResponse.expireAt);

async function getValidToken() {
  const fiveMinuteBuffer = 5 * 60 * 1000;
  if (Date.now() > tokenExpiry.getTime() - fiveMinuteBuffer) {
    await reAuthenticate();
  }
  return currentToken;
}

---

HTTP 400 — Username o password mancante

{
  "status": 400,
  "errors": [{ "field": "username", "message": "must not be blank" }]
}

Soluzione: Assicurarsi che sia username sia password siano presenti e non vuoti nel corpo della richiesta.

---

HTTP 403 — Forbidden (login-extended)

{
  "status": 403,
  "message": "Auto-login context is missing"
}

Causa: /api/v1/login-extended richiede un contesto di accesso automatico che non è configurato per il vostro account.

Soluzione: Usare /api/v1/login al suo posto, oppure contattare il vostro referente DPD per abilitare l'accesso esteso per il vostro account.

---

Credenziali corrette ma ancora 401?

1. Verificare di chiamare l'URL dell'ambiente corretto (dev, staging o produzione)
2. Verificare che il proprio account sia attivo — contattare il supporto DPD
3. Verificare se il proprio indirizzo IP deve essere autorizzato (whitelist) per l'accesso API