Åben indkøbskurv (tidligere version)

Bemærk: Denne artikel er henvendt til en tidligere version af åben indkøbskurv, som benytter funktionen add. Hvis du ønsker at benytte åben indkøbskurv henviser vi til den nye version som du finder her.

Information om tidligere version

Funktionen består i korte træk af, at man kan lægge varer i kurven ved at benytte et link til shoppen. Linket tilføjes nogle parametre for at fortælle shoppen, hvilke produkter det drejer sig om. Læs mere om seneste version af åben indkøbskurv.

Der er forskellige måder at strukturere linket på, alt efter, hvilke parametre man ønsker at benytte. Parametre består af et parameter-navn og dets værdi (navn=værdi), som fortæller shoppen, hvilke data man ønsker at arbejde med. Benytter man flere parametre i sit link, adskilles disse med et &-tegn, hvilket vi gennemgår i eksemplet herunder.

Shoppen kan modtage følgende parametre via link:

• sku = Varenummer (kan være både produkt og/eller variant)
• product = Produktets ID
• variant = ID for den pågældende variant (ved variantprodukter)
• amount = Antal/stk. (uden amount sættes værdien 1)
• notification = Visning af statusbesked i kurv (sættes til "true" eller "false")

Bemærk: Linket skal enten indeholde "sku" (varenummer) eller "product" (produkt ID) for at funktionen slår igennem. Hvis du har flere produkter med samme varenummer bør du benytte "sku" (produkt ID), da shoppen ellers ikke ved, hvilket af produkterne du ønsker at tilføje.

Varenummer og produkt ID finder du under fanen Generelt på produktet. Du finder variant ID under fanen Varianter på det enkelte produkt (synlig på variantprodukter):

Du kan ligeledes lave et udtræk af dine produkter og varianter med shoppens eksportfunktion så du kan aflæse variant ID mv. på tværs af produkter.

Hvis man ønsker at linke direkte til et produkt uden varianter, kan linket se således ud:

Eksempel 1: https://minshop.dk/actions/cart/add/?sku=A001&amount=1
Eksempel 2: https://minshop.dk/actions/cart/add/?product=99&amount=2

Hvor "sku" er varenummeret (i dette tilfælde "A001"), "product" er produktets ID (i dette tilfælde "99"), og "amount" dikterer antallet der skal tilføjes kurven.

Hvis man ønsker at linke til et produkt med varianter via produktets ID, skal linket se således ud:

https://minshop.dk/actions/cart/add/?product=99&variant=10&amount=1

Hvor "99" er produktets ID, "10" er variantens globale ID, og "amount" dikterer antallet der skal tilføjes kurven.

Parameteret "notification" bestemmer visningen af statusbeskeder som "Varen er lagt i din indkøbskurv.", "Produktet findes ikke" osv. når linket benyttes:

Medtages parameteret i linket med værdien "false", så undlades notifikationen (standard er "true" og parameteret kan derfor undlades, hvis statusbeskederne skal vises):

https://minshop.dk/actions/cart/add/?product=99&variant=10&amount=1&notification=false

Værd at vide: Bortset fra parameteret expiryDays (se sektionen Udløb af indhold i kurven) er rækkefølgen af parametre i linket er uden betydning.

Tilføjelse af flere produkter

Det er muligt at tilføje flere produkter til kurven f.eks. ved at gentage kaldet som vist her:

Kald 1: https://minshop.dk/actions/cart/add/?product=4&amount=1
Kald 2: https://minshop.dk/actions/cart/add/?product=10&amount=1
Kald 3: https://minshop.dk/actions/cart/add/?product=6&amount=1

Udvidet åben indkøbskurv

Denne funktion kan f.eks. benyttes til at sende et eller flere produkt-links til en kunde med aftalt pris og antal. Da linket inkluderer en hash-kode (en streng til identifikation af linkets oprindelige opbygning) er det ikke muligt, at ændre værdierne efter linket er genereret og sendt til kunden.

Brug af udvidet åben indkøbskurv kan også være praktisk, hvis du afgiver et tilbud, og ønsker at sende et link til kunden så denne kan købe det specifikke tilbud via din webshop uden, at du på forhånd har oprettet specifikke produkter til formålet. Dette gøres ved, at oprette et anonymt (generisk/universelt) produkt som du efterfølgende via linket kan sætte titel, pris og varenummer på. Produktet er med andre ord bare en pladsholder for de informationer du angiver i linket. Dermed kan du generere forskellige links til det samme produkt i shoppen, som hver gang har forskellige priser og titler, og dermed agerer som et nyt produkt, hver gang. Denne metode vil f.eks. også kunne benyttes af evt. sælgere og partnere som shoppen måtte have tilknyttet.

Udvidet åben indkøbskurv tilføjer nye parametre til den eksisterende funktionalitet i åben indkøbskurv. Parametrene er som følger:

• title = Produkt titel (valgfri vilkårlig titel f.eks. "Tilbud ifølge aftale" mv.)
• price = Produkt pris (ønsket stk. pris)
• currency = Gennemtvingelse af valuta ("DKK", "EUR", "NOK" mv.)
• weight = Produktets vægt ("0.2", "1.5" mv.). Kun tilgængelig via addmulti

Med ovenstående forøges det mulige antal parametre til følgende når udvidet åben indkøbskurv er aktiveret:

• title = Produkt titel
• price = Produkt pris
• currency = Gennemtvingelse af valuta (kun med addmulti)
• weight = Produktets vægt (kun med addmulti)
• sku = Varenummer (kan være både produkt og/eller variant)
• product = Produktets ID
• variant = ID for variant (ved variantprodukt)
• amount = Antal: prisen multipliceres med antal (uden amount sættes værdien 1)
• notification = Statusbesked i kurv

For at benytte den udvidede åbne indkøbskurv skal du aktivere indstillingen i administrationen under Indstillinger > Webshopindstillinger > Produkter (nederst på siden):

1. Udvidet åben indkøbskurv: Aktiverer funktionaliteten for udvidet åben indkøbskurv
2. Tilladte IP-adresser (valgfri): Semikolonsepareret liste over tilladte IP-adresser. Dette er IP'en på klienten som linket til åben indkøbskurv kan benyttes af. Listen over IP-adresser hjælper med at forhindre misbrug af linket til åben indkøbskurv
3. Hemmelig nøgle: En nøgle, som indtastes, og derefter deles med den eksterne partner, som ønsker at generere links til åben indkøbskurv. Den hemmelige nøgle er en sikring af de links der genereres, som validerer linkets indhold og derved sikrer at variablerne såsom titel og pris ikke kan ændres af slutbrugeren

Generering af kode-variabel ud fra hemmelig nøgle

For at benytte åben udvidet indkøbskurv, genereres en SHA-1 (en krypteret streng der benyttes som nøgle) ud fra <SHARED_SECRET> samt værdierne af de argumenter der sendes, i rækkefølgen de optræder i linket, hvor <SHARED_SECRET> er den indtastede kode i administrationen:

(Den hemmelige nøgle er en kombination af bogstaver og tal som du selv finder på)

Eksempel link:

https://minshop.dk/actions/cart/add/?product=99&variant=5&amount=1&price=349&title=Produkt A

Kode: 07FnpNB9Qk8q9951349Produkt A = 3ccdb019bfed4d98cf5f8f230aaf1d6e5ba61841

Ovenstående kode genereres ud fra følgende parametre, så fremt de er angivet:
Hemmelig nøgle: 07FnpNB9Qk8q
Produkt-ID (product): 99
Variant-ID (variant): 5
Antal (amount): 1
Pris (price): 349
Titel (title): "Produkt A"

Endeligt link:

https://minshop.dk/actions/cart/add/?product=99&variant=5&amount=1&price=349&title=Produkt A&code=3ccdb019bfed4d98cf5f8f230aaf1d6e5ba61841

Værd at vide: Rækkefølgen af parametre i linket er uden betydning.

I kodeeksemplerne herunder viser vi, hvordan ovenstående gøres programmatisk. Du kan også benytte vores eksempel længere nede i artiklen, til direkte at konfigurere dine parametre, og efterfølgende generere et komplet link.

    // Parameters
    NameValueCollection args = HttpUtility.ParseQueryString(string.Empty);
    args.Add("product", "99");
    args.Add("sku", "A001");
    args.Add("variant", "5");
    args.Add("title", "Produkt A");
    args.Add("price", "349");
    args.Add("amount", "1");
    args.Add("notification", "false");
    args.Add("code", ""); // Leave blank for SHA-1
    // Secret (as entered in the shop administration)
    string secret = "SHARED_SECRET";
    // Join secret with parameters (out "SHARED_SECRET99A0015Produkt A3491")
    secret += string.Join("", args.AllKeys.Select(key => args[key]));
    // Generate SHA-1 (out "3bb989c215deaf74aa7ebac355aa766a2d2ff337")
    string hash = SHA1.Create().ComputeHash(Encoding.UTF8.GetBytes(secret)).Aggregate(string.Empty, (x, y) => x + y.ToString("x2"));
    // Get URL with parameters and key
    string url = "https://www.minshop.dk/actions/cart/add/?" + args.ToString() + hash;
    // (out "https://www.minshop.dk/actions/cart/add/?product=99&sku=A001&variant=5&title=Produkt+A&price=349&amount=1&code=3bb989c215deaf74aa7ebac355aa766a2d2ff337")

    

    $args = [
    'product' => 99,
    'sku' => 'A001',
    'variant' => 5,
    'title' => 'Produkt A',
    'price' => 349,
    'amount' => 1,
    'notification' => 'false'
    ];

    $args['code'] = sha1(SHARED_SECRET . implode($args));

    $url = 'https://www.minshop.dk/actions/cart/add/?' . http_build_query($args);

Flere produkter med "addmulti" action

• Læs mere her.

Tracking af ordrestatus via sporingskode

Det er muligt at medsende en sporingskode i kaldet til Åben indkøbskurv, som efterfølgende kan benyttes til at identificere ordren via SOAP- og GraphQL API. På denne måde kan man afklare om ordren er blevet oprettet og i så fald, hvilken ordrestatus den har mv.

Tracking funktionen fungerer ved at medsende parameteret referralCode i kaldet til shoppen: referralCode=LiveDec23-00001

Sporingskoden kan f.eks. bestå af en statisk del der fortæller, hvilken begivenhed ordren er oprettet til (live shopping event mv.) og en fortløbende eller tilfældig værdi der er unik for ordren, f.eks. LiveDec23-00001. På denne måde kan du identificere alle ordrer for det pågældende event og samtidigt skelne dem fra hinanden når du laver dit udtræk.

Her finder du sporingskoden i de to API'er:

• SOAP API: Order.ReferralCode (SOAP API dokumentation)
• GraphQL API: Order.referralCode (GraphQL dokumentation)

Værd at vide

• Sporingskoden må ikke overstige 50 tegn.
• Til sporingskoden benyttes UTF-8 indkodning internt i systemet. Dog skal du være opmærksom på at UTF-8 ikke understøttes i URL, og du bør derfor lave en sporingskode der indeholder gyldige tegn.
• Sporingskoden er en del af Udvidet åben indkøbskurv og kan tilføjes eksemplet med hemmelig nøgle og kodegeneratoren i denne artikel.

Udløb af indhold i kurven

Med parametret expiryDays er det muligt, at angive, hvor mange dage kurven skal bevares for gæste-brugere uden login. Denne funktion vil typisk være rettet mod kunder med mobiltelefon, der ikke er logget ind i shoppen og handler som gæst men stadigvæk har behov for, at kunne genkalde produkter efter udløbet session ud fra en forudbestemt periode som shopejeren finder passende i den pågældende kontekst. Ved registrerede kunder gælder de eksisterende regler for indkøbskurven.

Værd at vide

• Hvis expiryDays undlades, benyttes standarduløb på 30 dage for gæster i shoppen.
• Værdien i expiryDays angives som heltalsværdi: 0 = deaktiveret (udløb med session), 30 = max-antal dage.
• Værdier større end 30 og mindre end 0 vil resultere i undtagelsen Ugyldig åben indkøbskurv kode.
• Hvis du benytter expiryDays med Udvidet åben indkøbskurv skal expiryDays placeres efter input sektionen og før referralCode (se eksempler herunder). Placering i en anden rækkefølge vil resultere i undtagelsen Ugyldig åben indkøbskurv kode.

Eksempler

Åben indkøbskurv:

...actions/cart/add/?product=99&variant=10&amount=1¬ification=false&expiryDays=1&referralCode=live2024

Udvidet åben indkøbskurv:

.../actions/cart/addmulti/?input=[{"product":7,"amount":2, "price":89}, {"product":9,"amount":4, "price":49}]&expiryDays=1&referralCode=live2024&code=4d916578e950c253a99a7a16217acdf05c08cffb

Læs mere om addmulti her

Stacking af produkter i kurven

Med parametret stack er det muligt, at bestemme om gentagne tilføjelser af det samme produkt skal lægges til eksisterende produkter af samme slags i kurven, altså tilføjes som en enkelt linje med opskrivning af produktantal eller om de skal have hver deres linje, og fremstå som separate klynger af produkter i kurven.

• Parameteret stack tilføjes en boolsk værdi: true/false eller 1/0.
• Stacking er slået fra som standard (svarende til stack=0)
• stack fungerer både med normal, addmulti og udvidet åben indkøbskurv.
• stack inkluderes ikke i oprettelsen af hash koden til udvidet åben indkøbskurv og står på den måde som en selvstændig del af strengen.
• Produkter stackes kun, hvis de er identiske og ikke er blevet tilpasset med nye værdier via åben indkøbskurv (pris, titel, vægt eller valuta). Tilpassede produkter stackes altså ikke (se Eksempel 2)

Eksempel 1

1. Normal tilføjelse via Åben indkøbskurv, hvor de 2 produkter tilføjes kurven som forventet:
   

   https://minshop.dk/actions/cart/add/?product=17&amount=2

2. Gentages samme kald vil der tilføjes yderligere 2 produkter på en separat linje fordi stacking er slået fra som standard:
   

   https://minshop.dk/actions/cart/add/?product=17&amount=2

3. Slår vi stacking til (stack=1) vil produkterne i stedet lægges oven i de eksisterende produkter i kurven:
   

   https://minshop.dk/actions/cart/add/?product=17&amount=2&stack=1

Eksempel 2

Her benytter vi addmulti til, at tilføje flere forskellige produkter i samme kald.

1. Her tilføjes 2 stk. af produkt ID 5, og 5 stk. af produkt ID 14, som har tilpasset pris og titel, hvilket tilføjer 2 produktlinjer i kurven:
   

   .../actions/cart/addmulti/?input=[{"product":5,"amount":2},{"product":14,"amount":5,"price":12,"title":"customtitle"}]

2. Gentages kaldet med stacking slået til (stack=1) vil produkt ID 5 stackes til 4 stk. men produkt ID 14 vil ikke stackes men få, hver deres linje med hhv. 5 stk. fordi de er tilpassede produkter:
   

   .../actions/cart/addmulti/?input=[{"product":5,"amount":2},{"product":14,"amount":5,"price":12,"title":"customtitle"}]&stack=1

Læs mere om addmulti her

Fejlsøgning

Hvis kald med åben indkøbskurv fejler, kan det give en af følgende beskeder:

• Ugyldig åben indkøbskurv kode: Den genererede SHA-1 matcher ikke de data shoppen forventer. Det kan f.eks. være, hvis man har ændret et parameter/værdi eller den hemmelig kode, og har glemt at generere en ny SHA-1 nøgle.
• Produktet findes ikke: Produkt ID (product) eller Varenummer (sku) findes ikke. Hvis du benytter både "product" og "sku" i samme link, skal begge stemme med produktet, før produktet kan fremfindes. Hvis der er angivet et variant ID (variant), men produktet ikke har nogen varianter, ignoreres dette og hovedproduktet lægges i kurv.
• Husk at vælge antal: Hvis linket indeholder parameteret "variant", og dette ikke matcher variant ID'et på det valgte produkt.
• Dette produkt er ikke på lager og kan derfor ikke bestilles: Hvis produktet er sat til ikke at kunne sælges med 0 i lagerantal, lægges varen i kurven med denne besked.
• Ugyldig URL-parameter: Vises ved syntaks fejl i JSON-koden (ved brug af addmulti). Det kunne f.eks. være, hvis vægten i weight-parameteret ikke er angivet med en numerisk værdi.
• Error - Invalid JSON input: Vises, hvis JSON koden ikke kan afvikles (ved brug af addmulti). Det kunne f.eks. være, hvis der ikke er angivet matchende parenteser, manglende eller forkert tegnsætning i koden.
• Hvis dit link bringer dig til forsiden af shoppen, i stedet for at lægge varen i kurven, skal du gennemgå linket for fejl.

Relevante links

• Åben indkøbskurv (ny version)