Åben indkøbskurv

Introduktion

Med funktionen Åben indkøbskurv, kan du tilføje produkter til indkøbskurven via et link til shoppen. Det kan f.eks. være et link i et nyhedsbrev, på sociale medier eller i en specifik forhandler- eller tilbudsmail mv. Åben indkøbskurv kan ikke benyttes på pakkeprodukter.

Der findes to versioner af Åben indkøbskurv

• Åben indkøbskurv (basis funktioner)
• Udvidet åben indkøbskurv (avancerede funktioner)

Bemærk: Tilgængeligheden af Åben indkøbskurv afhænger af din abonnementspakke. Udvidet åben indkøbskurv aktiveres via et flueben under Indstillinger > Webshopindstillinger > Produkter i sektionen Udvidet åben indkøbskurv.

I praksis

Som vi nævnte i introduktionen består funktionen 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.

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: 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

Så længe gentagne kald foretages i samme session vil produkterne blive tilføjet samme kurv.

I ovenstående eksempel benytter vi "add" action i vores URL til at tilføje et produkt af gangen, men det er også muligt at benytte "addmulti", som er en action der tillader flere produkter i et enkelt kald ved at supplere de produkt data vi allerede har til rådighed og indkapsle dem i et JSON array og passere dem til et input parameter i vores URL:

.../actions/cart/addmulti/?input=[{}, {}, ...]

Eksempler

I dette eksempel tilføjer vi 2 stk. af produkt ID 7 og 4 stk. af produkt ID 9:

https://minshop.dk/actions/cart/addmulti/?input=[{"product":7,"amount":2}, {"product":9,"amount":4}]

I dette eksempel inkluderer vi varianter og tilføjer 1 stk. af variant 34 fra produkt ID 16, og 4 stk. af produkt ID 20, samt 1 stk. af variant 14 fra produkt ID 3:

https://minshop.dk/actions/cart/addmulti/?input=[{"product":16,"variant":34,"amount":1},{"product":20,"amount":4},{"product":3,"variant":14,"amount":1}]

Vi kan bryde URL'en op således for at få et overblik:

• Input start: https://minshop.dk/actions/cart/addmulti/?input=[
• Produkt 1: {"product":16,"variant":34,"amount":1},
• Produkt 2: {"product":20,"amount":4},
• Produkt 3: {"product":3,"variant":14,"amount":1}
• Input slut: ]

Husk at variant ID ikke kan aflæses under variantdata i administrationen, da det er et relativt ID tilknyttet varianttypen og ikke et unikt ID (et produkt kan have flere varianttyper tilknyttet). Lav i stedet et udtræk af dine produkter og varianter med shoppens eksportfunktion.

Funktionen addmulti er ikke afhængig af om udvidet åben indkøbskurv er aktiveret og kan benyttes med shoppens standardindstillinger for åben indkøbskurv.

Tilvalgstyper

Hvis du benytter funktionen addmulti og ønsker at inkludere Tilvalgstyper på produktet, så kan det gøres via parametret "additionalData". I eksemplet herunder har produktet 4 tilvalg med flere valgmuligheder i enkeltvalgsbokse (radioknapper), afkrydsningsbokse (checkbox) og et tekstfelt:

1. Der findes 4 slags tilvalgstyper som fastsættes ved oprettelse af tilvalgstyperne i shoppen:
   • Enkeltvalgsbokse (radioknapper)
   • Afkrydsningsboks (checkbox)
   • Tekstfelt
   • Dropdownliste

   Den overordnede tilvalgstype adresseres via tilvalgstypens ID, som svarer til variablen typeId i vores kald til shoppen. typeId er med andre ord tilvalgstypen og ikke en bestemmelse af om den er en afkrydsningsboks mv., dette er fastsat ved oprettelsen af vores tilvalgstyper.

2. Valget for den pågældende tilvalgstype angiver vi via parameteret choice:
   • Ved dropdownliste/enkeltvalgsboks: ID (2 mv.)
   • Ved afkrydsningsboks et array af ID'er ([5,6])
   • Ved tekstfelt en tekststreng ("Min yndlingsstol!")

   Værdien til choice (også kaldet tilvalgstypedata) kan aflæses på de enkelte tilvalgstyper i shoppens administration, og står listet i tilvalgsdataenes titler som "(data 1), (data 4)" etc.

Hvis vi ønsker at benytte billedeksemplet ovenfor til vores kald kan det gøre således:

https://minshop.dk/actions/cart/addmulti/?input=[{"product":16,"variant":36,"amount":1,"additionalData":[{"typeId": 1, "choice": 2}, {"typeId": 2, "choice": [5,6]}, {"typeId": 3, "choice": "Min yndlingsstol!"}, {"typeId": 4, "choice": 7}]}]

Vi kan bryde URL'en op således for at få et overblik:

• Input start: https://minshop.dk/actions/cart/addmulti/?input=[
• Produkt start: {
• Produkt ID, variant og antal: "product":16,"variant":36,"amount":1,
• Tilvalg start: "additionalData":[
• Tilvalgstype 1: {"typeId": 1, "choice": 2},
• Tilvalgstype 2: {"typeId": 2, "choice": [5,6]},
• Tilvalgstype 3: {"typeId": 3, "choice": "Min yndlingsstol!"},
• Tilvalgstype 4: {"typeId": 4, "choice": 7}
• Tilvalg slut: ]
• Produkt slut: }
• Input slut: ]

Tilvalgene står i kurven sammen med produktet og er en tydelig indikator for om tilvalgsdataene er kommunikeret korrekt til shoppen via din URL:

For at benytte denne funktion skal du kende ID'erne på tilvalgstyperne (typeId) og deres tilhørende data ID (choice). Gå til Produkter > Tilvalgstyper og aflæs tilvalgstype ID'et (vises i kolonnen "Id"):

Klik på blyantikonet for at få vist detaljer for tilvalgstypedata. Her kan du aflæse tilvalgsdataenes ID som vist herunder. Data ID'erne benyttes når du skal sætte markering i enkeltvalgsbokse, dropdownliste eller afkrydsningsbokse (som vist i eksemplet længere oppe i artiklen):

Læs mere om oprettelse af Tilvalgstyper her.

Opsummering

• product/sku/ean: Én af disse er er påkrævet
• variant: Påkrævet for variant produkter hvis feltet product benyttes
• amount: Påkrævet
• additionalData: Valgfri inkludering af én eller flere tilvalgstyper (variablen skrives med camelCase)
• notification: Valgfri visning af statusbesked

Husk at variant ID'et ikke kan aflæses under variantdata i administrationen da det er et relativt ID tilknyttet varianttypen og ikke et unikt ID. Lav i stedet et udtræk af dine produkter og varianter med shoppens eksportfunktion.

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 krypteret nøgle, 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)

Hvis der angives en titel skal dette gøres med UTF-8 indkodning:

• "Tilbud ifølge aftale" => "Tilbud+if%C3%B8lge+aftale"

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

• title = Produkt titel
• price = Produkt pris
• 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 samt værdierne af de argumenter der sendes, i rækkefølgen de optræder i linket, hvor 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

Vi kan ligeledes benytte "addmulti" med udvidet åben indkøbskurv, som i eksemplet længere oppe (se sektionen Tilføjelse af flere produkter) og generere tilsvarende link med vores JSON indkodede streng af produkter:

Kode: 07FnpNB9Qk8q[{"product":7,"amount":2, "price":89}, {"product":9,"amount":4, "price":49}] = 4d916578e950c253a99a7a16217acdf05c08cffb

Princippet er det samme som ovenfor, hvor produktværdierne (i dette tilfælde vores JSON array) og den hemmelige nøgle fra shoppen kombineres til at danne den krypterede streng:

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

Her benytter vi vores action "addmulti" fra tidligere og tilføjer vores JSON argument til input parameteret sammen med den genererede kode.

Kodeeksemplerne overfor kan i så fald simplificeres til kun at indeholde et enkelt parameter "input" som indeholder vores JSON argument:

C#

    args.Add("input", "[{\"product\":7,\"amount\":2, \"price\":89}, {\"product\":9,\"amount\":4, \"price\":49}]");

PHP

    'input' => '[{"product":7,"amount":2, "price\:89}, {"product":9,"amount":4, "price":49}]"'

Lav dit eget link (link generator)

Hvis du ønsker at konfigurere dine parametre, og efterfølgende generere et komplet link inkl. SHA-1 til udvidet åben indkøbskurv, kan du gøre dette helt uden programmeringserfaring, ved at benytte følgende metode.

Dette gør du ved at kopiere kodestumpen herunder og indsætte den i LINQPad, der er et gratis værktøj til afvikling af kode. Kodestumpen samler dine parametre samt den hemmelige nøgle, og genererer en krypteret SHA-1 nøgle til brug i linket. Herefter bygger koden det færdige link til dig. Koden tager højde for specialtegn i din titel og undlader parametre som ikke har angivet nogen værdi. Du kan downloade softwaren her.

Når du har indsat kodestumpen i LINQPad, kan du ændre værdierne som beskrevet i kommentarerne i koden:

Download

• Download kodeeksemplet: her (cSharp_aaben_kurv.zip)
• Download en version af kodeeksemplet tilpasset addmulti action med JSON argumentet: her (cSharp_Addmulti.zip)

Start LINQPad og indsæt kodestumpen:

(Klik på billedet for at zoome)

1. Indsæt og tilpas dine værdier (produkt ID, titel, pris osv.)
2. Klik på start knappen eller tast F5 på dit tastatur, for at køre koden
3. Det genererede link fremkommer i nederste vindue og kan kopieres herfra

Du kan efterfølgende gemme dit dokument i LINQPad, og oprette kopier mv. til senere brug.

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.

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).
• Error - Invalid JSON input: Vises hvis JSON koden ikke kan afvikles (ved brug af addmulti).
• Hvis dit link bringer dig til forsiden af shoppen, i stedet for at lægge varen i kurven, skal du gennemgå linket for fejl.

Nyttige links

• Hvordan opretter jeg tilvalgstyper?
• Kom i gang med GraphQL API
• Kom i gang med SOAP API