Kom igång med ShipNordics API

Med ShipNordics API kan du koppla ett eget system, till exempel en egenbyggd webbutik eller ett affärssystem, till ShipNordic. Ditt system skapar beställningar i ShipNordic, och när frakten har bokats skickar ShipNordic tillbaka spårningsnumret.

Den fullständiga tekniska dokumentationen finns på developer.shipnordic.se. Den här artikeln beskriver hur du skapar en API-nyckel och hur flödet fungerar.

Använder du WooCommerce behöver du inte bygga något själv. Följ i stället Koppla ihop din WooCommerce-butik med ShipNordic.

Så fungerar flödet

Hämta ombud (valfritt). Om kunden ska välja ombud eller paketbox i din kassa hämtar du dem för kundens postnummer med GET /ext/v1/service-points. Samma anrop kan också svara på om hemleverans finns på postnumret.
Skapa beställningen. Skicka beställningen med POST /ext/v1/orders. Den dyker upp under Sändningar i ShipNordic med status Ny.
Boka frakten i ShipNordic. Du bokar och skriver ut som vanligt från Sändningar. Om transportör, tjänst och ombud skickades med i beställningen är de redan ifyllda.
Ta emot spårningsnumret. När frakten är bokad skickar ShipNordic händelsen order.booked med spårningsnummer och spårningslänk till din Callback URL.

Skapa en API-nyckel

Gå till Inställningar → Kopplingar → API-nycklar.
Klicka på Ny API-nyckel.
Ange ett Namn, till exempel namnet på butiken eller systemet.
Ange en Callback URL om du vill få tillbaka spårningsnummer (valfritt, kan läggas till senare). Adressen måste börja med https://.
Klicka på Skapa nyckel.
Kopiera och spara API-nyckel och Callback-hemlighet på ett säkert ställe.

Viktigt: API-nyckeln och callback-hemligheten visas bara en gång. Tappar du bort dem behöver du skapa en ny nyckel.

Ställ in avsändare och transportörer

Klicka på pennan på nyckeln för att redigera den. Beställningar som skapas med nyckeln använder de här inställningarna när frakten bokas.

Allmänt: namn, Callback URL och status. En nyckel som är satt till Inaktiv slutar fungera direkt.
Avsändaradress: adressen som står som avsändare på fraktsedeln. Här anger du också VOEC-nummer (Norge), VAT-nummer och EORI-nummer (export utanför EU).
Transportörer: lägg till de transportörer du använder och ditt kundnummer hos var och en (DHL, PostNord, DB Schenker, UPS).

För Budbee, Instabox och Porterbuddy anger du inget kundnummer här. De använder API-nyckeln du lägger in under Inställningar → Kopplingar → Instabee. Läs mer i Kom igång med Budbee, Instabox och Porterbuddy.

Bra att veta för utvecklare

Inloggning: skicka API-nyckeln i headern Authorization: Bearer <din-api-nyckel>.
Adress: https://ser.shipnordic.se
Dubbletter: external_ref (ditt ordernummer) måste vara unikt per API-nyckel. Skickas samma värde igen får du svaret 409.
Begränsning av anrop: varje nyckel har en gräns per minut som visas i kolumnen Anrop/min. Överskrids den får du svaret 429 med headern Retry-After. Ombudssökningar har en egen, tio gånger högre gräns.
Callback: varje anrop är signerat. Headern X-ShipNordic-Signature innehåller en HMAC-SHA256 av innehållet, beräknad med din callback-hemlighet. Kontrollera alltid signaturen. Svara med 2xx. Vid fel görs nya försök efter 60 sekunder, 5 minuter och 30 minuter.
Priser: unit_price, total och shipping_cost ska skickas exklusive moms och efter alla rabatter, eftersom de används i tulldeklarationen. Priser inklusive moms för plocklistan skickas i egna fält.
Tull: för export utanför EU skickar du med HS-nummer (hsn) och ursprungsland (countryoforigin) på varje rad.
Vikt: anges i gram.

Exempel och alla fält finns på developer.shipnordic.se.

Ta bort en API-nyckel

Klicka på papperskorgen på nyckeln. Beställningar som har skapats med nyckeln finns kvar, men anrop med nyckeln och callbacks slutar fungera.