Autenticazione

Autentica le richieste con la tua API key

Tutte le richieste alle API MoovExpress vanno autenticate con una API key, passata nell'header Authorization come Bearer token.

Authorization: Bearer mvx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ottenere la API key

1. Accedi al portale MoovExpress.
2. Vai in Impostazioni → API Key.
3. Scegli il contratto e premi Genera API key.
4. Copia la chiave: viene mostrata una sola volta.

Ogni chiave è legata a un contratto. Se usi più contratti, genera una chiave per ciascuno.

Verifica connessione

Per testare che la chiave sia valida (utile in fase di collegamento con un'altra piattaforma) usa GET /api/v1/account: con API key valida risponde 200 con i dati del contratto, altrimenti 401.

curl https://moovexpress.com/api/v1/account \
  -H "Authorization: Bearer mvx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{ "ok": true, "account": "Cliente Demo Srl", "contratto": "Standard Nazionale",
  "contratto_attivo": true, "listino_attivo": true, "credito": 150.00, "valuta": "EUR" }

Esempio di richiesta autenticata

curl -X POST https://moovexpress.com/api/v1/rates \
  -H "Authorization: Bearer mvx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "packages": [{ "weight": 2.5, "length": 30, "width": 20, "height": 15 }],
    "shipTo": { "postalCode": "00100", "state": "RM", "country": "IT" }
  }'

const res = await fetch("https://moovexpress.com/api/v1/rates", {
  method: "POST",
  headers: {
    "Authorization": "Bearer mvx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    packages: [{ weight: 2.5, length: 30, width: 20, height: 15 }],
    shipTo: { postalCode: "00100", state: "RM", country: "IT" },
  }),
});
const data = await res.json();

$ch = curl_init("https://moovexpress.com/api/v1/rates");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer mvx_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "packages" => [["weight" => 2.5, "length" => 30, "width" => 20, "height" => 15]],
    "shipTo" => ["postalCode" => "00100", "state" => "RM", "country" => "IT"],
  ]),
]);
$data = json_decode(curl_exec($ch), true);

Revocare una chiave

Puoi eliminare una API key in qualsiasi momento dalla stessa pagina API Key del portale. Una volta revocata, i sistemi che la usano smettono immediatamente di funzionare: genera prima la nuova chiave, poi revoca quella vecchia.

Risposte di errore di autenticazione

{ "error": "API key non valida o mancante" }

Limiti di frequenza

Le richieste sono soggette a un limite di frequenza per API key. Superata la soglia, la risposta è 429 Too Many Requests con l'header Retry-After (secondi da attendere prima di riprovare). Lo stesso 429 viene restituito quando la quota del pacchetto è esaurita o non pagata: il campo codice distingue i casi.

{ "error": "Troppe richieste in poco tempo: rallenta e riprova tra qualche secondo.", "codice": "rate_limit" }