Ulkoisen tuotevalinnan siirtäminen AI Commerce -ostoskoriin

Ulkoisen laskurin, konfiguraattorin tai muun valintatyökalun tuotteet lisätään asiakkaan AI Commerce -ostoskoriin lähettämällä asiakkaan selaimesta lomake kaupan osoitteeseen POST /api/service/cart/import. Tämä ohje on tarkoitettu integraation toteuttavalle kehittäjälle. Integraatio siirtää tuotevalinnan, ei ulkoisen järjestelmän hintatarjousta. Asiakas jatkaa käsittelyn jälkeen kaupan kassalle tai muuhun integraatiossa määriteltyyn sisäiseen osoitteeseen.

Päätepiste on julkinen: kumppaniavainta, allekirjoitusta tai erillistä tunnistautumista ei tarvita. AI Commerce vastaa hinnoittelusta ja kaupan istunnosta. Lähettävä järjestelmä ei saa antaa hintoja, alennuksia, asiakas- tai istuntotunnisteita eikä ostoskorin sisäisiä metatietoja. Tuotteiden pitää olla kohdekaupan tuotteita, ja integraation on käytettävä kyseisen kaupan tunnisteita, valintoja ja myyntiyksiköitä.

Käytä selaimen lomakenavigaatiota, älä korvaa sitä taustalla tehtävällä cross-origin fetch-kutsulla tai palvelinten välisellä pyynnöllä. Palvelin käyttää pyynnöstä tunnistettua kaupan istuntoa tai aloittaa uuden. Aiemman ostoskorin jatkuminen edellyttää, että selain välittää kaupan istunnon tunnistetiedot tässä siirtymässä. Testaa siksi myös olemassa oleva istunto oikeiden verkkotunnusten välillä; pelkkä tyhjän ostoskorin testi ei riitä. Kaupan CORS- tai CSP-rajoituksia ei tarvitse muuttaa tämän ohjeen toteuttamiseksi.

POST-pyynnön rakenne ja HTML-lomake

POST-pyynnön osoite on kohdekaupan oma HTTPS-osoite ja polku /api/service/cart/import. Lähetä lomake muodossa application/x-www-form-urlencoded. Lomakkeessa sallitaan vain pakollinen items ja valinnainen return. Tuotelista on items-kentän sisältämä JSON-merkkijono, ei koko HTTP-pyynnön JSON-runko. Älä käytä application/json- tai multipart/form-data-muotoa, GET-linkkiä tai URL-osoitteeseen lisättyä tuotelistaa.

Vaihda esimerkin https://kauppa.example, tuotenumero ja tuotetunniste oman integraatiosi arvoiksi. Esimerkin tuotteet ja verkkotunnus ovat paikkamerkkejä. Tavallinen HTML-lomake toimii ilman JavaScriptiä ja tekee tarvittavan lomakekoodauksen. Jos muodostat kentän arvon palvelimella, koodaa JSON lisäksi turvallisesti HTML-attribuuttiin; älä yhdistä asiakkaan tekstiä suoraan HTML-merkkijonoon.

<form method="post"
      action="https://kauppa.example/api/service/cart/import"
      enctype="application/x-www-form-urlencoded"
      accept-charset="UTF-8"
      target="_top">
  <input type="hidden" name="items"
         value='[{"sku":"TUOTE-123","quantity":2},{"id":456,"quantity":1}]'>
  <input type="hidden" name="return" value="/checkout">
  <button type="submit">Siirrä ostoskoriin</button>
</form>

return ei ole ulkoisen kumppanisivun osoite. Täydet URL-osoitteet, //example.com, kenoviivat sekä välilyöntejä tai ohjausmerkkejä sisältävät arvot hylätään. Käytä kohdekaupassa oikeasti toimivaa sisäistä polkua; polun hyväksyminen ei takaa, että sitä vastaava sivu on olemassa. Lomakkeen target="_top" siirtää koko selainikkunan. Iframe-upotuksessa myös upotuksen omien rajoitusten on sallittava lomakkeen lähetys ja ylimmän ikkunan navigaatio.

Tuoterivin kentät, tunnisteet ja valinnat

Jokainen items-taulukon rivi kuvaa yhden lisättävän tuotevalinnan. Rivillä annetaan täsmälleen yksi tunniste: id tai sku. Eri riveillä voi käyttää eri tunnistetyyppiä. Lisäksi tarvitaan positiivinen kokonaisluku quantity. JSON-luvut ja merkkijonot erotetaan toisistaan: määrä 2 hyväksytään, mutta määrä "2" ei. Älä lähetä valinnaisia kenttiä tarpeettomasti; pois jätetty variantti ja kommentti käsitellään tyhjinä ja lisävalinnat tyhjänä kokoelmana.

SKU voi vastata kauppaan tallennettua tuotenumeroa tai tuotteen API-tuotenumeroa. Osittaista hakua tai kirjainkoon normalisointia ei tehdä: käytä tarkalleen kaupan arvoa. Jos sama lähetetty SKU vastaa useaa eri tuotetta tai yhtään tuotetta ei löydy, koko pyyntö hylätään. Pelkästään numeroista koostuva SKU lähetetään silti merkkijonona, jotta myös mahdolliset alkunollat säilyvät.

variant käyttää muotoa optionId-valueId; useat parit erotetaan pilkulla. Käytä kohdekaupan oikeita valintatunnisteita ja samaa esitysjärjestystä kuin kaupan omassa valinnassa. customOptions käyttää lisävalinnan näkyvää nimeä ja valittua arvoa. Lähetä ne tavallisena tekstinä. Alla oleva valintojen esimerkki näyttää rakenteen, ei tietyn kaupan oikeita arvoja.

[
  {"sku": "TUOTE-123", "quantity": 2},
  {
    "id": 456,
    "quantity": 1,
    "variant": "10-22,11-35",
    "comment": "Asennus keittiöön",
    "customOptions": {"Väri": "Valkoinen"}
  }
]

Tuonti tarkistaa pyynnön rakenteen ja tuotetunnisteiden löytymisen kaupan tuoteluettelosta ennen ostoskorin kirjoittamista. Se ei tee erillistä varianttien tai lisävalintojen katalogivalidointia eikä varmista kaikkia tuotteen vähimmäismääriä, määräportaita, kommenttivaatimuksia tai asiakasrajoituksia. Kumppanin on muodostettava oikea tuotevalinta; normaali ostoskorin ja kassan käsittely jää voimaan. Onnistunut tuonti ei tarkoita, että tilaus olisi kaikilta osin valmis maksettavaksi tai että varastosaatavuus olisi vahvistettu.

Rivillä ei sallita muita kenttiä. Esimerkiksi price, specialPrice, discount, customerId, sessionId ja bundleId aiheuttavat pyynnön hylkäyksen; niitä ei vain ohiteta. Myöskään tiedostot, ulkoisen järjestelmän omat suunnittelumetatiedot tai hintatarjoukset eivät kuulu tähän lomakesopimukseen.

Ostoskorin yhdistäminen, hinnoittelu ja vastaukset

Hyväksytty tuotevalinta lisätään asiakkaan tunnistettuun ostoskoriin, eikä koriin jo kuuluvia muita rivejä korvata. Samaa ostoskoririviä vastaavat tuotteet yhdistyvät määrää kasvattamalla: esimerkiksi kaksi kappaletta korissa ja kolme lisättävää kappaletta tuottavat viisi kappaletta, ellei kaupan enimmäismäärä rajoita lopputulosta. Jos kauppaan on asetettu ostoskorimäärän yläraja, normaali määränkäsittely leikkaa määrän siihen; rajan ylittäminen ei itsessään aiheuta tuonnin 422-virhettä.

Rivin tunnistamiseen käytetään tuotetunnistetta, varianttimerkkijonoa ja kommenttia. customOptions ei yksin erottele rivejä. Jos muuten sama rivi on jo korissa, sen nykyiset lisävalinnat ja muut metatiedot säilyvät ja vain määrä muuttuu. Älä siis lähetä kahta toisistaan poikkeavaa lisävalintaa muuten samana rivinä ja oleta saavasi kaksi erillistä riviä. Samassa paketissa toistuvat rivit yhdistyvät samalla periaatteella.

AI Commerce hinnoittelee uudet rivit omien tuotetietojensa ja normaalin asiakaskohtaisen hintalogiikkansa perusteella. Ulkoista erikoishintaa ei aseteta. Tuonti ei ole idempotentti: saman POST-pyynnön lähettäminen uudelleen lisää määrät uudelleen. HTTP 303 ohjaa selaimen erilliseen GET-pyyntöön, mutta ei estä kumppanisivulla tehtyä uutta lomakelähetystä.

Tuonnin omat validointivirheet näytetään yksinkertaisella AI Commerce -HTML-virhesivulla, eivät JSON-vastauksena. Esimerkiksi kelvollinen ensimmäinen rivi ja puuttuva viimeinen tuote hylkäävät koko paketin ennen tuonnin ostoskorikirjoitusta. Tämä ei ole lupaus yleisestä tietokantavirheiden palautuksesta: odottamattomassa palvelinvirheessä tarkista ostoskori ennen uusintalähetystä. Päätepiste ei palauta koneellisesti käsiteltävää rivikohtaista onnistumisraporttia.

Dynaamisen tuotevalinnan lähettäminen JavaScriptillä

Dynaaminen laskuri voi muodostaa saman selainlomakkeen JavaScriptillä asiakkaan painaessa siirtopainiketta. JavaScriptin tehtävä on vain koota tuotevalinta items-kenttään ja lähettää lomake. Älä tee samasta painalluksesta lisäksi taustapyyntöä. Esimerkki ei tarvitse erillistä kirjastoa, ja kenttien arvot asetetaan DOM-ominaisuuksina, jolloin asiakkaan kommenttia ei tarvitse yhdistää HTML-attribuutin lähdetekstiin.

function siirraOstoskoriin(items) {
  const form = document.createElement("form");
  form.method = "post";
  form.action = "https://kauppa.example/api/service/cart/import";
  form.enctype = "application/x-www-form-urlencoded";
  form.acceptCharset = "UTF-8";
  form.target = "_top";

  const fields = {
    items: JSON.stringify(items),
    return: "/checkout"
  };

  for (const [name, value] of Object.entries(fields)) {
    const input = document.createElement("input");
    input.type = "hidden";
    input.name = name;
    input.value = value;
    form.appendChild(input);
  }

  document.body.appendChild(form);
  form.submit();
}

// Kutsu kerran asiakkaan painaessa siirtopainiketta.
siirraOstoskoriin([
  { sku: "TUOTE-123", quantity: 2 },
  { id: 456, quantity: 1 }
]);

Vaihda osoite ja tuotteet oikeiksi sekä liitä kutsu oman käyttöliittymäsi painiketapahtumaan. Pidä quantity ja id JSON-lukuina. Älä käytä encodeURIComponent-käsittelyä kentän arvolle ennen lomakelähetystä: JSON.stringify muodostaa JSONin ja selain tekee lomakekoodauksen. Estä käyttöliittymässä tahaton kaksoislähetys, mutta älä rakenna automaattista uusintaa epäselvään vastaukseen. Lähetyksen jälkeen navigaatio jatkuu AI Commercen vastauksen perusteella.

Kumppanin tarkistuslista ja virheen selvittäminen

Kumppanin hyväksymistesti tehdään todellisesta lähettävästä verkkotunnuksesta kohdekauppaan. Testaa sekä ensimmäinen käynti ilman kaupan istuntoa että selain, jossa ostoskorissa on jo tuotteita. Varmista tuonnin jälkeen oikea kauppa, oikea sisäinen paluusivu, lisätyt määrät ja aiempien rivien säilyminen. Testaa käytössä olevilla selaimilla; istunnon jatkumista ei osoita palvelinpuolen HTTP-kutsu, joka ei käytä asiakkaan selaimen istuntoa.

Testaa lisäksi tunnistaminen sekä id- että sku-kentällä, kaksi samaa riviä, variantti, kommentti ja lisävalinnat. Tarkista erityisesti tilanne, jossa aiemmalla rivillä ja tuodulla rivillä on eri customOptions-arvot. Kokeile virheellinen viimeinen tuotetunniste ja erikseen väärä määrätyyppi: koko tuontipaketin tulee jäädä lisäämättä. Tarkista myös ulkoisen return-osoitteen hylkäys sekä määrien käyttäytyminen kaupan mahdollisella ylärajalla.

Pidä laskurin myyntiyksiköt yhteensopivina kaupan kanssa. Rajapinta ei muunna esimerkiksi metrejä, pakkauskokoja tai ulkoisia tuotekoodistoja automaattisesti. Varianttien, pakollisten lisävalintojen ja tuotekohtaisten tilausedellytysten oikeellisuus on tarkistettava varsinaisessa ostopolussa; onnistunut lomakesiirto yksin ei todista näitä. Iframe-toteutuksessa varmista myös koko ikkunan navigaatio.

Virhettä selvitettäessä tallenna kohdekaupan osoite, ajankohta, HTTP-status ja lähetetyn tuotevalinnan rakenne. Tarkista ensin sisältötyyppi, JSON-lukujen tyypit, ylimääräiset kentät sekä tuotteiden tunnisteet ja saatavuus kaupan tuoteluettelossa. Älä liitä tukipyyntöön evästeitä, istuntotunnisteita tai asiakkaan tarpeettomia henkilötietoja. Päätepiste siirtää asiakkaan ostoskoriin; se ei anna kumppanille vastauksena ostoskorin sisältöä eikä oikeutta päättää asiakkaan hinnoista.