Åben indkøbskurv

I denne artikel:

Åben indkøbskurv

Med modulet å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å Facebook eller i en specifik forhandlermail mv. Åben indkøbskurv kan ikke benyttes på pakkeprodukter.

Der er flere forskellige måder at strukturere linket på, alt efter hvilke parametre du ønsker at benytte. Parametre består af et parameter-navn og dets værdi (navn=værdi), som fortæller shoppen hvilke data du ønsker at arbejde med. Benytter du flere parametre i dit 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 = ID for produkt
variant = ID for variant (ved variant produkt)
amount = Antal (uden amount sættes værdien 1)
notification = Visning af statusbesked i kurv ("true", "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).

Hvis man ønsker at linke direkte til et hovedprodukt, 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 direkte 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 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 værdien er "true" og parameteret kan derfor helt 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=[{}, {}, ...]

Eksempel

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}]

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 et tilvalg med 3 muligheder i enkeltvalgsbokse (radioknapper):

(billedet viser tilvalg på et fiktivt produkt)

typeId kan være følgende tilvalgstyper:
- 1 = Afkrydsningsboks (checkbox)
- 2 = Tekstfelt
- 3 = Dropdownliste/Enkeltvalgsbokse (radioknapper) (deler samme ID da funktionaliteten datamæssigt er identisk)
choice angiver valget for den pågældende tilvalgstype:
- Ved afkrydsningsboks et array af ID'er ([6, 3, 2])
- Ved tekstfelt en tekststreng ("Min tekststreng")
- Ved dropdownliste/enkeltvalgsboks: ID (1 mv.)

Hvis vi ønsker at tilføje eksemplet ovenfor til vores kald kan det gøre således:

https://minshop.dk/actions/cart/addmulti/?input=[{"product":7,"amount":1, "additionalData": {["typeId": 3, "choice": 0]},}]

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

Klik på blyantikonet for at få vist detaljer for tilvalgstypedata. Her kan du aflæse tilvalgsdataenes ID som vist herunder:

Hvis du ønsker at sætte flere tilvalgstyper på samme produkt kan flere data tilføjes arrayet:

"additionalData": [{"typeId": 1, "choice": [1] }, {"typeId": 2, "choice": "tekst..."}, {"typeId": 3, "choice": 1}]

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
notification: Valgfri visning af statusbesked

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 = ID for produkt
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):

Udvidet åben indkøbskurv: Aktiverer funktionaliteten for udvidet åben indkøbskurv
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
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:


    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:


    // Deklaration af variabler
    string ProduktId, VariantId, Antal, Pris, VareNr, Titel, Notifikation, HemmeligNoegle, Domaene, Protokol;

    /*** START ***/
    // 1. Indsæt dine parameterværdier mellem anførselstegnene:
    ProduktId = "110";
    VareNr = "A001";
    VariantId = "5";
    Titel = "Tilbud ifølge aftale";
    Pris = "99";
    Antal = "3";
    Notifikation = "Nej";
    // Bemærk: Undlad værdier til parametre du ikke ønsker medtaget i linket ("")

    // 2. Indsæt din hemmelige nøgle fra shoppen mellem anførselstegnene:
    HemmeligNoegle = "hemmelig";

    // 3. Indsæt dit domæne mellem anførselstegnene:
    Domaene = "minshop.dk";

    // 4. Hvis du benytter SSL kan du lade følgende værdi være.
    // Og hvis ikke skal den ændres til "http://", altså uden "s":
    Protokol = "https://";

    // 5. Tast F5 på dit tastatur eller klik på "play knappen" i topmenuen af LINQPad
    // -herefter køres koden og det genererede link vises i "Results" vinduet herunder.
    /*** SLUT ***/

    // Koden herunder håndterer validering og konvertering af værdier til SHA-1, samt opbygning af komplet URL
    // (reference til System.Web.dll (HttpUtility) udeladt for umiddelbar afvikling i LINQPad)
    System.Collections.Specialized.NameValueCollection args = new System.Collections.Specialized.NameValueCollection();
    if (!string.IsNullOrEmpty(ProduktId)) args.Add("product", ProduktId);
    if (!string.IsNullOrEmpty(VareNr)) args.Add("sku", VareNr);
    if (!string.IsNullOrEmpty(VariantId)) args.Add("variant", VariantId);
    if (!string.IsNullOrEmpty(Titel)) args.Add("title", Titel);
    if (!string.IsNullOrEmpty(Pris)) args.Add("price", Pris);
    if (!string.IsNullOrEmpty(Antal)) args.Add("amount", Antal);
    if (!string.IsNullOrEmpty(Notifikation)) {args.Add("notification", (Notifikation == "Nej") ? "false":"true");}
    args.Add("code", ""); // Benyttes til SHA-1
    HemmeligNoegle += string.Join("", args.AllKeys.Select(key => args[key]));
    string hash = System.Security.Cryptography.SHA1.Create().ComputeHash(
        Encoding.UTF8.GetBytes(HemmeligNoegle)).Aggregate(string.Empty, (x, y) => x + y.ToString("x2"));
    IEnumerable
        segments = from key in args.AllKeys
        from value in args.GetValues(key)
        select string.Format("{0}={1}",
        System.Net.WebUtility.UrlEncode(key),
        System.Net.WebUtility.UrlEncode(value));
    string url = Protokol + (Domaene = Domaene.Replace("/", "")) + "/actions/cart/add/?" + string.Join("&", segments) + hash;
    url.Dump();

TIP: Du kan downloade en version af ovenstående kode tilpasset "addmulti" action med JSON argumentet her (cSharp_Addmulti.zip).

Start LINQPad og indsæt kodestumpen:

(Klik på billedet for at zoome)

Indsæt og tilpas dine værdier (produkt ID, titel, pris osv.)
Klik på start knappen eller tast F5 på dit tastatur, for at køre koden
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.

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.
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?

Åben indkøbskurv

I denne artikel: