Vertaa omaa valikoimaa markkinaan

Tuota tarkistettava vertailu: mitkä omat SKU:t yhdistyvät markkinatuotteisiin, mille löytyy saatavilla olevia kilpailijatarjouksia ja mitkä havaitut markkinatuotteet puuttuvat täydellisestä katalogistasi. Lopputulos on päätöslista, ei automaattinen hinnanmuutos tai ostotilaus.

Aloita sandbox-avaimella eristetyssä työtilassa. Oman tuotantokatalogin käyttöön tarvitset live-avaimen, merchant:write-, intelligence:read- ja catalog:read-oikeudet sekä comparisons:access-käyttöoikeuden. Valmistele valitun markkinan täydellinen katalogi: yksilöllinen SKU, kanoninen tunniste tai kelvollinen GTIN, todelliset havainto- ja vanhenemisajat, valuutta ja veropohja. Tarvitset curl-ohjelman ja yksityisen CATALOG_REQUEST_KEY-arvon. Markkinalähteen omistajan pitää toimittaa tuore aineisto; oman katalogin tuonti ei tuo markkinadataa.

Katalogituonti korvaa nykyisen projektion; se ei lisää rivejä vanhan jatkoksi. Älä tuo otosta tai yhtä suuremman katalogin sivua ja tulkitse muita markkinatuotteita todellisiksi valikoima-aukoiksi. Jos koko katalogi ylittää tuonnin rajan, pysähdy selvittämään tuotteen rajoitus. Tuotannon erähaut ovat laskutettavia; testidata on esimerkkiaineistoa, ei nykyistä markkinanäyttöä.

PUT /v1/merchant/catalog hyväksyy enintään 1 000 tuotetta, joilla on yksilöllinen merchant_sku ja täsmällinen kanoninen tunniste tai kelvollinen GTIN. Tarvitset merchant:write-oikeuden, tilauksen comparisons:access-käyttöoikeuden ja Idempotency-Key-otsakkeen. Markkinalähteen ei tarvitse vielä olla olemassa. Ilmoita todelliset lähteen havainto- ja vanhenemisajat, markkina, valuutta ja tax_basis; älä käytä esimerkkiaikoja tuotantohavaintoina. Katalogin korvaaminen edellyttää uudempaa havaintoaikaa. Kauppajärjestelmäsi säilyy tietojen omistajana.

{
  "evidence": {
    "source_id": "merchant-export",
    "source_ref": "merchant:export:example",
    "observed_at": "2026-09-29T08:00:00Z",
    "expires_at": "2026-09-30T08:00:00Z",
    "market": "FI",
    "currency": "EUR",
    "tax_basis": "inclusive"
  },
  "items": [
    {
      "merchant_sku": "headphones-black",
      "canonical_product_id": "sony_wh1000xm5_black",
      "current_price": 249,
      "unit_cost": 160,
      "fulfillment_cost": 5,
      "delivery_charge": 5,
      "minimum_margin_percent": 20
    }
  ]
}

# Use a private sandbox key and an isolated workspace first.
# catalog.json must contain YOUR complete catalog and current source evidence.
curl --fail-with-body --silent --show-error -X PUT https://hintadata.fi/v1/merchant/catalog \
  -H "Authorization: Bearer $HINTADATA_API_KEY" \
  -H "Idempotency-Key: $CATALOG_REQUEST_KEY" \
  -H 'Content-Type: application/json' --data-binary @catalog.json

Kirjoita runko catalog.json-tiedostoon ja aseta uusi pyyntöavain tälle korvaukselle. Tarkista, että imported vastaa lähetettyä rivimäärää ja palautettu lähdetieto omaa vientiäsi. Saman sisällön uudelleenyritys käyttää samaa avainta. Älä siirrä aikaleimoja vain saadaksesi vanhan datan näyttämään tuoreelta.

GET /v1/merchant/coverage vaatii intelligence:read-oikeuden eikä kuluta vertailukrediittejä. Se näyttää molempien lähteiden tilan missing, stale tai fresh sekä matched-, ambiguous- ja unmatched-rivimäärät. Suodata resolution-arvolla ja sivuta limit/offset-arvoilla. Puuttuva markkina-aineisto ei osoita, etteivät kilpailijat myy tuotetta. Moniselitteinen GTIN jää moniselitteiseksi: korjaa lähdetunniste tai anna täsmällinen kanoninen tunniste.

curl --fail-with-body --silent --show-error 'https://hintadata.fi/v1/merchant/coverage?limit=100&offset=0' \
  -H "Authorization: Bearer $HINTADATA_API_KEY"

Edellytä market_status- ja merchant_status-kentiltä fresh-tilaa ennen vertailun tulkintaa. Lue kaikki kattavuussivut next_offset-arvolla, kunnes se on null. Pidä unmatched- ja ambiguous-rivit erillisellä korjauslistalla; älä poista niitä parantaaksesi näennäistä kattavuutta.

POST /v1/products/resolve ja POST /v1/offers/batch vaativat catalog:read-oikeuden. Molemmat hyväksyvät 1–100 riviä, joissa on täsmälleen yksi canonical_product_id, gtin tai merchant_sku. Tulokset säilyttävät järjestyksen ja palauttavat rivikohtaisen tilan ja ehdokkaat. Kelvolliset GTIN-8/12/13/14-merkkijonot normalisoidaan etunollilla; virheellinen tarkistusnumero hylkää pyynnön. Nämä vain lukevat POST-kutsut eivät tarvitse Idempotency-Key-otsaketta. Tuotannossa kustannus on yksi vertailukrediitti syötettä kohden, myös ilman osumaa; epäonnistunut pyyntö vapauttaa varauksensa. Testitila on maksuton ja käyttää esimerkkiaineistoa.

{"items":[{"merchant_sku":"headphones-black"},{"canonical_product_id":"sony_wh1000xm5_black"}]}

Yhdistä omat merchant_sku-eräsi, tarkista jokaisen rivin tila ja hae yhdistettyjen rivien tarjoukset. Säilytä yhteys SKU:n, kanonisen tunnisteen ja lähdenäytön välillä. Alla oleva harjoitus näyttää matched/unmatched-käsittelyn esimerkkitunnisteilla; se ei tuo omaa katalogiasi eikä todista tuotantovalikoiman kattavuutta.

Kun täydellinen katalogi on tuore ja jokainen tunniste yhdistyy, hae valikoimamahdollisuudet ja käy next_offset-arvolla kaikki sivut läpi. 409 catalog_unresolved tarkoittaa, että tunnisteita pitää vielä korjata. Tallenna jokaisen ehdokkaan canonical_product_id, observed_stores, available_supplier_count, interpretation ja evidence. Onnistunut tyhjä lista tarkoittaa, ettei annetussa markkina-aineistossa ole aukkoja, ei koko markkinan täydellistä kattavuutta.

curl --fail-with-body --silent --show-error 'https://hintadata.fi/v1/assortment/opportunities?limit=100&offset=0' \
  -H "Authorization: Bearer $HINTADATA_API_KEY"

Muodosta omaan järjestelmääsi kolme tarkistusryhmää: vertailukelpoiset tarjoukset, ratkaisematon näyttö ja havaitut valikoima-aukon ehdokkaat. Liitä mukaan lähdeaikaleimat ja hintojen perusteet. Hyväksy kaupallinen toimenpide erikseen. Jos haet myös hinnoittelusuosituksia, anna kaikki kustannuskentät ja tarkista status ja evidence_gaps ennen suosituksen käyttöä.

Sinulla on tuontikuitti tarkoitetusta täydellisestä katalogista, sen riveihin täsmäytetyt kattavuusluvut, jokaisen pyydetyn SKU:n tila ja sivutetut valikoimaehdokkaat lähdenäyttöineen. Kaikilla ratkaisemattomilla tunnisteilla on vastuuhenkilö ja seuraava toimenpide. Jos tuoreus- tai tunnistetarkistus epäonnistuu, oikea lopputulos on estetty päätös ja korjauslista, ei keksitty vertailu.

Haun min_price ja vertailun best_offer perustuvat saatavilla olevien tarjousten toimitettuun hintaan, eivät listahintaan. Null tarkoittaa, ettei saatavilla olevaa tarjousta tunneta, ei nollahintaa. Vertailu ei enää hyväksy goal- tai range-parametria; aikajakso kuuluu historiaan. Hinnoittelu palauttaa nykyisen tuotehinnan, ehdotuksen, erotuksen, vähimmäishinnan ja ehdotetun katteen. Kulut sisältävät toimituskulut ja myyntituotto asiakkaan delivery_charge-maksun. Syötteiden markkinan, valuutan ja tunnetun veropohjan pitää sopia yhteen. Puuttuvat kentät tai vanhentunut katalogi palauttavat insufficient_evidence-tilan ja evidence_gaps-listan. Tämä API-kutsu palauttaa suosituksen. Hintadatan automaattinen hinnoittelu muuttaa kaupan hintoja asetettujen hinnoittelusääntöjen ja katerajojen mukaisesti. Valikoima-analyysi edellyttää tuoretta, kokonaan yhdistettyä katalogia ja näyttää havaittuja aukkoja, ei kysyntäennusteita.

Havaittu aukko on vain tuote, joka esiintyy annetussa markkinadatassa mutta puuttuu tuodusta katalogistasi. Se ei osoita asiakaskysyntää, kannattavaa hankintaa eikä anna lupaa ostaa varastoa. Puuttuva tai tuntematon saatavuus ei tarkoita loppuunmyytyä. Tarjouslista voi sisältää tarjouksia, joita ei ole saatavilla; käytä saatavilla olevien tarjousten toimitettua hintaa ja säilytä sen lähdenäyttö.

POST /v1/watchlists edellyttää condition-kenttää. target_price laukeaa tavoitehinnassa tai sen alapuolella; below_own_price vertaa yhdistettyyn omaan SKU-hintaan toimitusmaksuineen. Molemmat ilmoittavat ehdon muuttuessa todeksi. price_change_percent mittaa muutoksen itseisarvon edellisestä hyväksytystä aineistosta; availability_change ilmoittaa vain tunnetut saatavilla/ei saatavilla -siirtymät. Puuttuva havainto ei tarkoita loppuunmyytyä. Uusi vahti ei lähetä heti ilmoitusta. GET tukee status- ja canonical_product_id-suodattimia sekä sivutusta. POST /v1/watchlists/batch keskeyttää, jatkaa tai poistaa atomisesti enintään 100 eri vahtia expected_revision-arvojen ja Idempotency-Key-otsakkeen avulla. Yksikin ristiriita hylkää koko erän. Katalogin korvaaminen mitätöi odottavat omaan hintaan perustuvat päätökset.

{"canonical_product_id":"sony_wh1000xm5_black","condition":"price_change_percent","change_percent":5,"channel":"webhook"}

400 invalid_request: tarkista yksilölliset SKU:t, täsmälleen yksi tunniste erärivillä, GTIN-tarkistusnumerot ja lähdeajat. 401/403: korjaa avain, oikeus tai tilaus; älä liitä avainta tukipyyntöön. 409 source_conflict: täsmäytä lähdetunniste ja vientien järjestys; älä nimeä vanhaa dataa uudeksi. 409 idempotency_conflict: käytä avainta uudelleen vain alkuperäisellä rungolla.

Unmatched tai ambiguous: korjaa lähdetunnisteet, tarkista ehdokkaat ja tuo koko katalogi uudelleen aidosti uudemmalla näytöllä. 409 catalog_unresolved: tee korjaus ennen valikoima-analyysiä. Puuttuva/vanhentunut kattavuus tai 503 source_unavailable/source_stale: pyydä kyseisen lähteen omistajaa päivittämään data ja tarkista kattavuus uudelleen. Älä korvaa virheitä onnistuneella tyhjällä tuloksella.

429 tai tilapäinen 5xx: noudata Retry-After-ohjetta ja rajaa uudelleenyritykset; säilytä tuonnin pyyntöavain ja runko. Jos ajo katkesi tuonnin jälkeen, tarkista kattavuus ennen uusintaa. Katalogin korvaamiselle ei ole perumiskomentoa: palauta tiedot omistavasta kauppajärjestelmästä kelvollisella uudemmalla lähdenäytöllä. Seuraava tehtävä löytyy hintavahdin elinkaarioppaasta; vahtien luonti on erillinen kirjoitus.