API e webhook

Un'API REST con autenticazione a chiave, una specifica OpenAPI 3 e webhook firmati. Le chiavi di test (wp_test_…) sono gratuite e usano un corriere di prova, così sviluppi senza spedire niente.

Crea le tue chiavi Scarica la specifica OpenAPI

1. Registra una spedizione

Il corriere viene riconosciuto dal numero. Con Idempotency-Key una richiesta ripetuta non crea doppioni.

curl -X POST https://waypost.it/v1/trackings \
  -H "Authorization: Bearer wp_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-1001" \
  -d '{"trackings": [{"number": "VT123456789", "order_ref": "ORD-1001"}]}'

2. Ricevi i cambi di stato

Eventi: tracking.updated, tracking.delivered, tracking.exception, tracking.expired. Ogni invio ha un event_id univoco e, se il tuo server non risponde, viene ripetuto per quasi un giorno.

POST https://tuo-negozio.it/webhooks/waypost
X-Signature: t=1791135151,v1=5f2b…
X-Waypost-Event-Type: tracking.delivered

{
  "event_id": "0199…",
  "type": "tracking.delivered",
  "data": {
    "previous_status": "out_for_delivery",
    "tracking": {
      "number": "VT123456789",
      "carrier": "gls-it",
      "status": "delivered",
      "status_label": "Consegnata",
      "order_ref": "ORD-1001",
      "events": [ … ]
    }
  }
}

3. Verifica la firma

// Node.js: verifica della firma
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
  && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Endpoint

POST	/v1/trackings	Registra fino a 100 numeri, con corriere facoltativo e riferimento ordine
GET	/v1/trackings/{id}	Stato e cronologia degli eventi
GET	/v1/trackings	Elenco con filtri per stato, corriere e data, paginazione a cursore
DELETE	/v1/trackings/{id}	Smette di seguire la spedizione e libera il posto
POST	/v1/detect	Corrieri candidati per un numero, senza registrarlo
GET	/v1/carriers	Corrieri supportati
POST	/v1/webhooks	Aggiunge un endpoint di notifica
GET	/v1/usage	Consumo rispetto al piano

Stati normalizzati

pending, info_received, in_transit, out_for_delivery, available_for_pickup,exception, failed_attempt, delivered, returned, expired, sempre constatus_label in italiano e il testo originale del corriere.