SkickaPacket
Laddar…
Kom igång

Så integrerar du SkickaPacket

Integrationen ska göras i din backend. App-id, security-key och access-token får aldrig exponeras i webbläsaren.

01

Välj miljö med rätt miljöfil

API-adressen får inte hårdkodas. Backend ska läsa samtliga värden från den aktiva miljöfilen.

.env.localLokal intern utveckling
SKICKAPACKET_API_URL=http://127.0.0.1:8080
SKICKAPACKET_APP_ID=sp_test_app_...
SKICKAPACKET_SECURITY_KEY=sp_test_key_...
.env.devUtveckling och test mot Stage
SKICKAPACKET_API_URL=https://api.stage.skickapacket.com
SKICKAPACKET_APP_ID=sp_test_app_...
SKICKAPACKET_SECURITY_KEY=sp_test_key_...
.env.productionProduktion
SKICKAPACKET_API_URL=https://api.skickapacket.com
SKICKAPACKET_APP_ID=sp_live_app_...
SKICKAPACKET_SECURITY_KEY=sp_live_key_...

Startkonfigurationen måste uttryckligen ladda rätt fil. Om SKICKAPACKET_API_URL saknas ska backend stoppa med ett konfigurationsfel – använd ingen automatisk fallback.

02

Skapa en API-app

Logga in med företagets konto ovan, registrera företagsprofilen och skapa en TEST-app. Security-key visas endast en gång och ska sparas i din backend eller secrets manager.

03

Hämta en 24-timmarstoken

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

Cachelagra access_token och återanvänd den. Hämta inte en ny token för varje offert.

04

Hämta transportalternativ

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

Använd inte den äldre adressen POST /api/quotes i nya integrationer.

05

Förnya token automatiskt

Vid 401 med error="invalid_token": radera den gamla token, autentisera med app-id/security-key, spara den nya token och försök originalanropet igen högst en gång.

06

Boka med quote-ID och idempotens

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

Skicka quoteId från offerten, extern orderreferens samt avsändare och mottagare. Svaret är 202 BOOKING_PENDING; en worker utför bokningen. Återanvänd samma idempotensnyckel och exakt samma payload efter timeout. Skapa aldrig en ny nyckel för ett oklart svar.

07

Hämta status och fraktsedel

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

Etiketten returneras som PDF. 202 Retry-After: 5 betyder att klienten ska vänta. BOOKING_UNKNOWN kräver statuskontroll eller manuell avstämning – ingen automatisk ny bokning.

08

Registrera signerad webhook

PUT /api/integration/v1/webhooks
Authorization: Bearer ${ACCESS_TOKEN}

{"endpointUrl":"https://din-app.se/webhooks/skickapacket"}

Spara signingSecret och verifiera HMAC-SHA256 över timestamp + "." + rawBody. Deduplicera med SkickaPacket-Event-Id.

09

Hantera fel säkert

  • 400 – rätta requesten.
  • 401 – credentials eller token är ogiltig.
  • 403 – credentials eller bokning är inte aktiverad i miljön.
  • 409 – idempotensnyckeln återanvändes med annan payload.
  • 410 – offerten har gått ut; hämta en ny.
  • 429 – vänta enligt Retry-After.
  • 5xx – kontrollera först shipmentstatus och använd begränsade omförsök.

Webhook behövs inte för token eller offerter, men rekommenderas för boknings- och etiketthändelser.