Ticaret REST API başvurusu (özel önizleme)

Note

Web IQ Commerce özel önizleme aşamasındadır ve tam belge erişimine sahip AppID'lere dahildir. Arama, Teklifler ve Ürün Ayrıntıları için erişim ayrı olarak etkinleştirilir. Özel önizleme sırasında kullanım, 1.000 API çağrısı başına 7,00 ABD doları olarak faturalandırılır. API yüzeyi ve sözleşmesi değişebilir.

Uygun müşteriler, Web IQ Geliştirici Portalı'ndaki Playground'da Ticaret API'lerini deneyebilir. Daha önce Playground'ı kullanmadıysanız Hızlı Başlangıç ile başlayın.

AppID'nizde Ticaret API'leri yoksa veya sorularınız varsa bir Web IQ Destek isteği açın, sorun türü olarak Kimlik Doğrulaması ve Erişim'i seçin ve alt tür olarak API Anahtarı Kurulumu'na tıklayın, Destek isteği oluştur'u seçin ve AppID'nizi ekleyin (Web IQ Geliştirici Portalı'nda Profil Yönetimi'nden kopyalayın) veya henüz yoksa, şirketinizin adı ve Web IQ kaynağınızın adı.

Web IQ Ticaret API'leri Ticaret Arama, Teklifler ve Ürün Ayrıntıları'dır. Commerce Search, bir ürün sorgusu için dereceli ürünleri ve satıcı tekliflerini döndürür. Teklifler ile kullanılabilir ürün, SKU ve teklif tanımlayıcılarını kullanın. Ürün Ayrıntıları ürün ve SKU tanımlayıcılarını kabul eder.

Üç uç nokta da JSON gövdesine sahip istekleri kabul POST eder. Üst bilgide Commerce için etkinleştirilmiş bir API anahtarıyla veya üst bilgide x-apikey Microsoft Entra ID erişim belirteci ile kimlik doğrulaması yapınAuthorization. Kurulum yönergeleri için bkz. Kimlik doğrulaması .

Örneklerde kurgusal Contoso ürünleri, satıcılar, tanımlayıcılar, URL'ler ve fiyatlar kullanılır. İzleme istekleri yaparken örnek tanımlayıcıları Commerce Search yanıtınızın değerleriyle değiştirin.

İstek başlıkları

Başlık Type Description
x-apikey veya Yetkilendirme string Kimlik doğrulaması için API anahtarınız veya Entra ID erişim belirteciniz.
içerik türü string İstek gövdesinin MIME türü. application/json adresini kullanın.

Desteklenen pazarlar

Özel önizleme sırasında, Ticaret API'leri ve birleşimlerini languageregiondestekler. Diğer birleşimler desteklenmez.

Pazar language region
İngilizce (ABD) en US
İspanyolca (ABD) es US
İngilizce (Kanada) en CA
Fransızca (Kanada) fr CA
İngilizce (Birleşik Krallık) en GB
Almanca (Almanya) de DE
Fransızca (Fransa) fr FR
İngilizce (Avustralya) en AU
Japonca (Japonya) ja JP

Sunduğunız her teklif için, bir kullanıcı veya kullanıcı için hareket eden bir aracı tarafından teklife yönelik her bağlantı veya gezinti için tam olarak bu yanıtta döndürülen şekilde kullanın clickUrl . Varsayılan olarak, clickUrl Microsoft barındırılan bir yeniden yönlendirmedir; Microsoft doğrudan satıcı URL'si de döndürebilir. Yalnızca ekranınızdaki satıcıyı veya satıcıyı tanımlamak veya model bağlamı olarak kullanın displayUrl ; hiçbir zaman bağlantı veya gezinti hedefi olarak kullanmayın. Bir teklifin kullanılabilir clickUrlbir teklifi yoksa teklifi sunmayın.

Opak gibi davran clickUrl . İlişkilendirme parametresi gereklidir ve yeniden yönlendirmenin içinde olabilir, bu nedenle görünür olmayabilir. veya ilişkilendirme parametresini ayırmayın, yeniden yazmayın, kesmeyin, kod çözmeyin veya değiştirmeyin clickUrl ve yönlendirmelerini atlamayın veya parametreyi kendiniz eklemeyin. Yalnızca özgün clickUrl bağlantıyı değiştirilmeden geçirirse, kendi izlemenize veya yeniden yönlendirme bağlantınıza sarmalayabilirsinizclickUrl. Önbellek aracılığıyla da dahil olmak üzere farklı bir yanıt, sorgu, kullanıcı veya amaç için yeniden kullanma clickUrl . Son kullanıcının kendi paylaşımı veya iletmesi yeniden kullanılmaz.

Uygulama kodundaki her bağlantıyı bir modelin clickUrl yeniden oluşturması yerine yanıttaki dosyasından oluşturun. Geçerli koşullar için bkz. Web IQ Kullanım Koşullarının B'sini Sergile.

Uç nokta:POST https://api.microsoft.ai/v3/search/commerce/products

Bir ürün sorgusu için dereceli ürünleri ve satıcı tekliflerini döndürür. Teklifler ile kullanılabilir ürün, SKU ve teklif tanımlayıcılarını kullanın. Ürün Ayrıntıları ürün ve SKU tanımlayıcılarını kabul eder.

Ticaret Arama örnek isteği

curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Contoso wireless headphones",
    "maxResults": 1,
    "language": "en",
    "region": "US",
    "location": "lat:37.7749;long:-122.4194"
  }'

Commerce Search parametreleri

Parametre Required Type Default Description
query Yes string - Boş olmayan ürün arama sorgusu. Uzunluk üst sınırı 1.000 karakterdir.
maxResults Hayır integer 10 Döndürülecek en fazla ürün sayısı 1 ila 50.
language Hayır string en İki harfli ISO 639-1 sonuç dili. Bkz. Desteklenen pazarlar.
region Hayır string US İki harfli ülke veya bölge kodu. Bkz. Desteklenen pazarlar.
location Hayır string - Biçimdeki lat:<latitude>;long:<longitude> konum, örneğin lat:37.7749;long:-122.4194. Enlem -90 ile 90 arasında, boylam ise -180 ile 180 arasında olmalıdır.

Commerce Search yanıtı

Dereceli ürünleri ve tekliflerini içeren bir CommerceResponse döndürür. Hiçbir ürün eşleşmiyorsa, yanıt boş products bir diziyle olur200 OK.

Örnek 200 OK yanıt (alıntı):

{
  "products": [
    {
      "offers": [
        {
          "id": "100000000001",
          "name": "Contoso Wireless Headphones",
          "seller": {
            "name": "Contoso Electronics",
            "logoUrl": "https://contoso.example/logo.png"
          },
          "price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
        }
      ],
      "id": "PG_00000000000000000000000000000001",
      "skuId": "00000000000000000000000000000001"
    }
  ],
  "traceId": "<trace-id>"
}

Ticaret Arama hataları

Eksik, boş veya uzun query, aralık maxResultsdışı , iki karakter olmayan bir language veya region geçersiz location bir döndürür 400 (HandlerInvalidInput ). Hizmet hataları () döndürür500InternalServerError. Kimlik doğrulaması, yetkilendirme, biçim ve kota hataları için bkz. Hatalar.

Ticaret Arama sınırları

  • query: 1 ile 1.000 karakter arasında ve yalnızca boşluk değil.
  • maxResults: 1 - 50, varsayılan 10. Döndürülen ürünlerin sayısı kullanılabilir eşleşmelere bağlıdır. Ürün başına teklif sayısı için sayfalandırma ve parametre yoktur.
  • language ve region: iki karakterli kodlar. location koordinatları parametreler tablosundaki aralıklar içinde olmalıdır.
  • Uygulama profilinizin (AppID) hız sınırları ve günlük kotası da geçerlidir.

Offers

Uç nokta:POST https://api.microsoft.ai/v3/fetch/commerce/products/offers

Ticari Arama'dan bir ürün, SKU veya temsili teklif için uygun satıcı tekliflerini döndürür. Ürün düzeyinde geri bildirim veya fiyat geçmişi yerine satıcı tekliflerini döndürür.

Örnek istek sunar

curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "productId": "PG_00000000000000000000000000000001",
    "skuId": "00000000000000000000000000000001",
    "offerId": "100000000001",
    "language": "en",
    "region": "US"
  }'

Parametreler sunar

Seçili ürün için tüm kullanılabilir ürün, SKU ve teklif tanımlayıcılarını Ticari Arama yanıtından gönderin. Yalnızca bir tanımlayıcı döndürülürse, bu tanımlayıcıyı gönderin. Boş olmayan en az bir tanımlayıcı gereklidir; tek bir istek döndürmeden (HandlerInvalidInput döndürür 400 .

Parametre Required Type Default Description
productId Conditional string - Commerce Search tarafından döndürülen ürün id . En fazla 1.000 karakter.
skuId Conditional string - Commerce Search tarafından döndürülen ürün skuId . En fazla 1.000 karakter.
offerId Conditional string - Ticari Arama tarafından döndürülen temsili teklif id . En fazla 1.000 karakter.
language Hayır string en İki harfli ISO 639-1 sonuç dili. Bkz. Desteklenen pazarlar.
region Hayır string US İki harfli ülke veya bölge kodu. Bkz. Desteklenen pazarlar.
location Hayır string - Biçimli lat:<latitude>;long:<longitude> konum. Enlem -90 ile 90 arasında, boylam ise -180 ile 180 arasında olmalıdır.

Yanıt sunar

CommerceOffersResponse

Alan Type Description
offers CommerceOffer dizisi Birincil veya temsilci önce teklifler, ardından ek teklifler sunar.
traceId string Hata ayıklama ve bağıntı için istek izleme tanımlayıcısı.

Teklif alanları için bkz. CommerceOffer, CommerceOfferImage, CommerceInstallmentInfo ve Destekleyici nesneler. Bilinmeyen tanımlayıcılar boş offers bir diziyle döner200 OK.

Örnek 200 OK yanıt (alıntı):

{
  "offers": [
    {
      "id": "100000000001",
      "name": "Contoso Wireless Headphones",
      "seller": {
        "name": "Contoso Electronics",
        "logoUrl": "https://contoso.example/logo.png"
      },
      "price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
    }
  ],
  "traceId": "<trace-id>"
}

Hatalar sunar

Eksik veya boş bir tanımlayıcı, 1.000 karakterden uzun bir tanımlayıcı, iki karakter olmayan bir language veya region veya geçersiz location bir dönüş 400 (HandlerInvalidInput ). Bilinmeyen tanımlayıcılar boş offers bir diziyle döner200 OK. Hizmet hataları () döndürür500InternalServerError. Bkz. Hatalar.

Sınırlar sunar

  • İstek başına bir ürün, SKU veya temsili teklif araması; toplu aramalar desteklenmez. Her tanımlayıcı 1.000 karakterle sınırlıdır.
  • , ofset veya imleç parametresi yoktur maxResults. Tekliflerin sayısı kullanılabilirliğe bağlıdır.
  • language ve region: iki karakterli kodlar. location koordinatları parametreler tablosundaki aralıklar içinde olmalıdır.
  • Uygulama profilinizin (AppID) hız sınırları ve günlük kotası da geçerlidir.

Ürün Ayrıntıları

Uç nokta:POST https://api.microsoft.ai/v3/fetch/commerce/products/details

Ticari Arama'dan ürün kimliği, SKU kimliği veya her ikisi için ürün başlığını (name), açıklamasını ve toplam derecelendirmesini döndürür. Açıklama kullanılabilir olduğunda eklenir.

Ürün Ayrıntıları örnek isteği

curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "productId": "PG_00000000000000000000000000000002",
    "skuId": "00000000000000000000000000000002",
    "language": "en",
    "region": "US"
  }'

Ürün Ayrıntıları parametreleri

En az bir productId veya skuId boş olmayan bir değer gereklidir ve her ikisini de gönderebilirsiniz. offerId alternatif değildir: Yalnızca teklif kimliğine sahip bir istek doğrulanamadı.

Parametre Required Type Default Description
productId Conditional string - id Ticari Arama ürünü. Hayır skuId gönderildiğinde gereklidir. En fazla 1.000 karakter.
skuId Conditional string - Ticari Arama'dan SKU Kimliği. Hayır productId gönderildiğinde gereklidir. En fazla 1.000 karakter.
language Hayır string en İki harfli dil kodu. veya nullbelirtilmezse, varsayılan kullanılır. Bkz. Desteklenen pazarlar.
region Hayır string US Ürün araması için iki harfli bölge kodu. veya nullbelirtilmezse, varsayılan kullanılır. Bkz. Desteklenen pazarlar.

Ürün Ayrıntıları yanıtı

CommerceProductDetailsResponse

Alan Type Description
products CommerceProductDetails dizisi Sıfır veya eşleşen bir ürün. Toplu aramalar desteklenmez.
traceId string İstek izleme tanımlayıcısı.

CommerceProductDetails

Alan Type Description
id string Çeşitlemeler arasında ürün tanımlayıcısı, eşleşen Ticari Arama.
name string Ürün başlığı, kullanılabilir olduğunda.
description string Kullanılabilir olduğunda ürün açıklaması.
rating CommerceRating 1 ile 5 arasında bir ölçekte ürün ortalama derecelendirmesi ve derecelendirme sayısı.

CommerceRating

Kullanılabilir rating derecelendirme olmadığında nesne atlanır.

Alan Type Description
value number Ürün ortalaması derecelendirmesi, iki ondalık basameğe yuvarlanır.
scaleMin number Derecelendirme ölçeğinin (1) alt kısmı.
scaleMax number Derecelendirme ölçeğinin (5) üst kısmı.
count integer Ürünün derecelendirme sayısı. Sıfır sayısı olarak 0döndürülür.

Bilinmeyen ürünler boş products bir diziyle geri döner200 OK.

Örnek 200 OK yanıt:

{
  "products": [
    {
      "id": "PG_00000000000000000000000000000002",
      "name": "Contoso Wireless Earbuds",
      "description": "Illustrative wireless in-ear headphones",
      "rating": { "value": 4.2, "scaleMin": 1, "scaleMax": 5, "count": 42 }
    }
  ],
  "traceId": "<trace-id>"
}

Ürün Ayrıntıları hataları

Eksik veya boş bir ürün veya SKU tanımlayıcısı, 1.000 karakterden uzun bir tanımlayıcı veya iki karakter döndürmemiş bir language veya region (HandlerInvalidInput) döndürür 400 . Hizmet hataları () döndürür500InternalServerError. Bkz. Hatalar.

Ürün Ayrıntıları sınırları

  • Her biri 1.000 karaktere kadar en az bir ürün veya SKU tanımlayıcısı. Yalnızca teklif kimliğine göre toplu aramalar ve aramalar desteklenmez.
  • language ve region: iki karakterli kodlar.
  • Uygulama profilinizin (AppID) hız sınırları ve günlük kotası da geçerlidir.

Yanıt nesneleri

Bu nesneler Ticaret Arama ve Teklifler tarafından döndürülür.

CommerceResponse

Alan Type Description
products CommerceProduct dizisi Derece sırasına göre ürünler.
traceId string Hata ayıklama ve bağıntı için istek izleme tanımlayıcısı.

CommerceProduct

Alan Type Description
id string Çeşitlemeler arasında ürün tanımlayıcısı.
skuId string Katalog SKU tanımlayıcısı.
offers CommerceOffer dizisi Birincil satıcı teklifleri.

CommerceOffer

Alan Type Description
id string Teklif tanımlayıcısı.
name string Satıcı başlığı.
description string Satıcı açıklaması.
specifications dizisi CommerceSpecification Teklif düzeyi belirtimleri ve seçili öznitelikler. Yinelenenler ve kaynak sırası korunur. Bkz . Destekleyici nesneler.
seller CommerceSeller Satıcı ayrıntıları. Bkz . Destekleyici nesneler.
price CommerceOfferPrice ISO 4217 küçük birimlerde teklif fiyatlandırması. offeredPrice indirim fiyatı olmadığında geri döner listPrice . Bkz . Destekleyici nesneler.
displayUrl string Yalnızca görüntüleme veya model bağlamı için satıcı veya satıcı URL'si. Bunu bağlantı veya gezinti hedefi olarak kullanmayın.
clickUrl string Teklife yönelik her bağlantı veya gezinti için hedef. Tam olarak döndürülen şekilde kullanın. Bkz . Teklif bağlantıları ve ilişkilendirme.
images CommerceOfferImage dizisi Resim teklif edin.
installmentInfo CommerceInstallmentInfo Taksit ödeme ayrıntıları.
shippingInfo string Okunabilir metin olarak sevkiyat bilgileri.
condition string Teklif edilen ürünün satıcı tarafından sağlanan koşulu.

CommerceOfferImage

Alan Type Description
url string Resim URL'si.

CommerceInstallmentInfo

Alan Type Description
description string Taksit planının okunabilir metin olarak açıklaması.
downPayment CommercePrice Tutarın önde olması gerekir. Bkz . Destekleyici nesneler.
monthlyPayment CommercePrice Aylık taksit ödemesi. Bkz . Destekleyici nesneler.
months integer Ay sayısı.

Destekleyici nesneler

Fiyatlar, para biriminin ISO 4217 küçük birimlerindeki tamsayılardır. Örneğin, 10000 ile currencyUSD değeri 100,00 TL'dir.

Object Alan Type Description
CommerceOfferPrice listPrice integer ISO 4217 küçük birimler orijinal fiyat.
CommerceOfferPrice offeredPrice integer ISO 4217 küçük birimler güncel fiyat. İndirim fiyatı olmadığında geri listPrice döner.
CommerceOfferPrice currency string ISO 4217 para birimi kodu.
CommercePrice amount integer ISO 4217 küçük birim cinsinden ödeme tutarı.
CommercePrice currency string ISO 4217 para birimi kodu.
CommerceSeller name string Satıcı görünen adı.
CommerceSeller logoUrl string Satıcı logosu URL'si.
CommerceSpecification name string Teklif öznitelik adı.
CommerceSpecification values dize dizisi Yinelenenleri ve kaynak sırasını koruyarak öznitelik görüntüleme değerleri.

Errors

Bu hatalar üç uç nokta için de geçerlidir. Her uç noktanın doğrulama ve boş sonuç davranışı kendi bölümünde açıklanmıştır.

HTTP durumu Hata kodu Anlam ve eylem
400 RequestInvalidFormat, HandlerInvalidInput Hatalı biçimlendirilmiş JSON veya eksik veya geçersiz istek parametreleri. Uç noktanın parametre tablosunu ve sınırlarını kullanarak isteği düzeltin.
401 veya gibi AuthNoToken kimlik doğrulama hataları AuthInvalidApiKey Kimlik bilgileri eksik, geçersiz veya süresi dolmuş. Geçerli kimlik bilgileriyle yeniden kimlik doğrulaması.
403 AuthUnauthorizedService Arayan, istenen kaynağa erişme yetkisine sahip değil. Uygulama profiliniz Commerce için etkinleştirilmemişse, bu sayfanın üst kısmında açıklandığı gibi erişim isteyin.
405 MethodNotAllowed POST'yi, GET'ye tercih edin.
415 RequestUnsupportedMediaType Gönderin content-type: application/json.
429 AuthUserThrottled, AuthUserDailyUsageExceeded Uygulama profilinizin (AppID) hız sınırı veya günlük kotası aşıldı. Yeniden denemeden önce içindeki retryAfter süreyi bekleyin.
500 InternalServerError Servis, talebi tamamlayamadı. Belirtilen gecikmeden sonra yeniden deneyin ve desteğe başvurduğunda öğesini traceId ekleyin.

Hata yanıtı

Hatalar paylaşılan hata yanıt yapısını kullanır.

Alan Type Description
errorCode string Makine tarafından okunabilir hata kodu.
errorCategory string UserError veya SystemError.
userMessage string Hatanın okunabilir açıklaması.
technicalDetails string İsteğe bağlı tanılama ayrıntıları.
retryAfter string saniye olarak isteğe bağlı yeniden deneme gecikmesi ve ardından bir s sonek (örneğin, "60s").
requestId string İsteğe bağlı istek tanımlayıcısı.
traceId string Destek için isteğe bağlı dağıtılmış izleme tanımlayıcısı.

Hata örneği

olmadan querybir Ticaret Arama isteği:

curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{}'

400 Bad Request yanıt:

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "query is required",
  "traceId": "<trace-id>"
}

Hız sınırları

Üç uç nokta da AppID'nin çağırdığı diğer Web IQ API'leriyle paylaşılan Web IQ AppID'nizin (varsayılan olarak saniyede 15 sorgu) hız sınırlarını ve günlük kotasını kullanır. Yanıt 429 , içindeki retryAfteryeniden deneme gecikmesini içerir. Günlük kotalar UTC saat 00:00'da sıfırlanır. Yeniden deneme kılavuzu için bkz. Hata işleme.