Från order till
tracking och fraktsedel.

Konfigurera endast backend

Läs API-adress och credentials från aktiv miljöfil. Om ett obligatoriskt värde saknas ska Nordbix stoppa vid start utan fallback. Security-key får aldrig skickas till webbläsaren eller loggas.

# .env.local
SKICKAPACKET_API_URL=http://127.0.0.1:8080

# .env.dev
SKICKAPACKET_API_URL=https://api.stage.skickapacket.com

# .env.production
SKICKAPACKET_API_URL=https://api.skickapacket.com

SKICKAPACKET_APP_ID=sp_test_app_...
SKICKAPACKET_SECURITY_KEY=sp_test_key_...

Lägg till databasfält

Spara quoteId, offertens utgångstid, en unik stabil Idempotency-Key, shipmentId, bokningsstatus, trackingnummer, tracking-URL, etikettstatus, intern PDF-sökväg och senaste felkod. Lägg en unik constraint på mottagna webhook-eventId.

Hämta och cachelagra token

POST ${SKICKAPACKET_API_URL}/api/integration/v1/oauth/token
X-App-Id: ${SKICKAPACKET_APP_ID}
X-Security-Key: ${SKICKAPACKET_SECURITY_KEY}

Återanvänd token i upp till 24 timmar. Vid 401 invalid_token hämtas en ny token och originalanropet upprepas högst en gång.

Hämta och spara offert

POST /api/integration/v1/shipping/quotes
Authorization: Bearer ${ACCESS_TOKEN}
Content-Type: application/json

{
  "orderType": "PARCEL",
  "originCountry": "SE", "originPostalCode": "11122", "originCity": "Stockholm",
  "destinationCountry": "SE", "destinationPostalCode": "21120", "destinationCity": "Malmö",
  "weightKg": 2, "lengthCm": 40, "widthCm": 25, "heightCm": 20
}

Visa alternativen för kunden och spara valt quoteId och expiresAt. Priset får inte återskapas eller ändras i Nordbix. För PostNord 19 ska Nordbix skicka sitt fasta inlämningsställe som originServicePointId och kundens valda utlämnings-/upphämtningsställe som servicePointId. Båda lagras av SkickaPacket och bokningen nekas om någon saknas.

Verifiera betalning före bokning

Nordbix ska inte anropa bokningen förrän kundens betalning är verifierad. Skapa och spara idempotensnyckeln innan det första bokningsförsöket.

Boka asynkront

POST /api/integration/v1/shipments
Authorization: Bearer ${ACCESS_TOKEN}
Idempotency-Key: ${STABLE_ORDER_KEY}
Content-Type: application/json

{
  "quoteId": "qt_...", "externalOrderId": "nordbix-order-123",
  "sender": {
    "name": "Nordbix AB", "companyName": "Nordbix AB", "addressLine1": "Gatan 1",
    "postalCode": "11122", "city": "Stockholm", "countryCode": "SE",
    "contact": { "email": "info@nordbix.com", "phoneNumber": "+46700000000" }
  },
  "recipient": {
    "name": "Kund Namn", "addressLine1": "Vägen 2", "postalCode": "21120",
    "city": "Malmö", "countryCode": "SE",
    "contact": { "email": "kund@example.com", "phoneNumber": "+46700000001" }
  },
  "originServicePointId": "<Nordbix fasta inlämningsställe>",
  "servicePointId": "<kundens valda utlämningsställe>"
}

Spara returnerat shipmentId direkt. 202 BOOKING_PENDING betyder att SkickaPackets worker har tagit emot bokningen – inte att transportören redan har godkänt den.

Följ bokningsstatus

GET /api/integration/v1/shipments/{shipmentId}
Authorization: Bearer ${ACCESS_TOKEN}

Invänta webhook eller polla tills status blir BOOKED. Vid BOOKING_UNKNOWN får Nordbix aldrig skapa en ny automatisk bokning; ordern ska flaggas för manuell avstämning.

Hämta fraktsedeln

GET /api/integration/v1/shipments/{shipmentId}/label
Authorization: Bearer ${ACCESS_TOKEN}
Accept: application/pdf

Vid 200 sparas PDF:en internt. Vid 202 väntar Nordbix enligt Retry-After. SkickaPacket levererar tracking och PDF via API eller webhook; Nordbix ansvarar för att visa tracking och skicka kundbekräftelse samt eventuellt mejl till info@nordbix.com.

Räkna inte 15 minuter som en garanti

Bokningsworkern kör normalt var 15:e minut. En order kan därför ligga i BOOKING_PENDING i upp till ungefär ett intervall innan transportörsanropet börjar. Tracking och PDF kan komma senare beroende på transportören. Behåll samma shipmentId, polla med backoff eller invänta webhook och skapa inte en ny bokning bara för att resultatet dröjer.

Ta emot signerade webhooks

PUT /api/integration/v1/webhooks
{"endpointUrl":"https://nordbix.com/webhooks/skickapacket"}

Verifiera HMAC-SHA256 över timestamp + "." + rawBody, neka gamla timestamps, deduplicera event-ID och svara snabbt med 2xx. Hantera booked, booking-failed, booking-unknown, label-ready, in-transit, delivered, returned och cancelled. Ett definitivt fel innehåller data.failure. Vid okänt utfall ska Nordbix stoppa automatisk ombokning och stämma av samma shipment. Endpointen måste vara publik HTTPS; Local kräver en HTTPS-tunnel eller polling eftersom localhost och privata adresser nekas.

Hantera återförsök utan dubbelköp

• Före mottaget shipment-ID: samma payload och samma idempotensnyckel.
• Efter mottaget shipment-ID: endast statusanrop.
• 409: stoppa – nyckeln användes med annan payload.
• 410: hämta en ny offert och starta en ny bokningsoperation.
• 5xx: kontrollera status före varje eventuellt omförsök.