Referência da API REST do Commerce (pré-visualização privada)

Note

O Web IQ Commerce está em pré-visualização privada e está incluído com AppIDs que oferecem acesso completo aos documentos. O acesso está ativado separadamente para Pesquisa, Ofertas e Detalhes do Produto. Durante a pré-visualização privada, a utilização é cobrada a $7,00 por cada 1.000 chamadas API. A superfície e o contrato da API podem mudar.

Os clientes elegíveis podem experimentar as APIs de Comércio no Playground, no Web IQ Developer Portal. Se nunca usaste o Playground antes, começa pelo Quickstart.

Se o seu AppID não tiver as APIs de Comércio, ou tiver dúvidas, abra um pedido de Suporte Web IQ, escolha Autenticação & Acesso como tipo de problema e Configuração de Chave API como subtipo, selecione Criar um pedido de suporte e inclua o seu AppID (copie-o da Gestão de Perfis no Portal de Programadores Web IQ) ou, se ainda não tiver um, o nome da sua empresa e o nome do seu recurso Web IQ.

As APIs do Web IQ Commerce são Pesquisa de Comércio, Ofertas e Detalhes de Produtos. A Commerce Search devolve produtos classificados e ofertas de vendedores para uma consulta de produto. Use o produto disponível, SKU e identificadores de ofertas com Ofertas. Detalhes do Produto aceita identificadores de produto e SKU.

Os três endpoints aceitam POST pedidos com um corpo JSON. Autenticar com uma chave API ativada para Commerce no x-apikey cabeçalho, ou com um token de acesso Microsoft Entra ID no Authorization cabeçalho. Consulte Autenticação para instruções de configuração.

Exemplos usam produtos fictícios da Contoso, vendedores, identificadores, URLs e preços. Substitua identificadores de exemplo por valores da sua resposta Commerce Search ao fazer pedidos de seguimento.

Cabeçalhos de solicitação

Cabeçalho Tipo Description
x-apikey ou Autorização cadeia (de caracteres) A sua chave API ou token de acesso do Entra ID para autenticação.
tipo de conteúdo cadeia (de caracteres) Tipo MIME do corpo do pedido. Utilize application/json.

Mercados suportados

Durante a pré-visualização privada, as APIs de Comércio suportam estas combinações de language e region. Outras combinações não são suportadas.

Mercado language region
Inglês (Estados Unidos) en US
Espanhol (Estados Unidos) es US
Inglês (Canadá) en CA
Francês (Canadá) fr CA
Inglês (Reino Unido) en GB
Alemão (Alemanha) de DE
Francês (França) fr FR
Inglês (Austrália) en AU
Japonês (Japão) ja JP

Para cada oferta que apresentar, utilize-a clickUrl exatamente como devolvida nessa resposta para cada link ou navegação para a oferta, seja por um utilizador ou por um agente a atuar em nome do utilizador. Por defeito, clickUrl é um redirecionamento hospedado pela Microsoft; A Microsoft também pode devolver um URL direto do comerciante. displayUrl Use apenas para identificar o comerciante ou vendedor no seu ecrã ou como contexto de modelo, nunca como link ou alvo de navegação. Se uma oferta não tiver um valor utilizável clickUrl, não apresente a oferta.

Trate clickUrl como opaco. O parâmetro de atribuição é necessário e pode estar dentro do redirecionamento, por isso pode não ser visível. Não removas, reescrevas, trunques, descodifiques ou substituas o ou o clickUrl seu parâmetro de atribuição, e não contornes os seus redirecionamentos nem adiciones um parâmetro tu próprio. Só podes envolver um clickUrl link de rastreamento ou redirecionamento se ele passar o original clickUrl sem alterações. Não reutilize a clickUrl para uma resposta, consulta, utilizador ou propósito diferente, incluindo através de um cache. A partilha ou encaminhamento do próprio utilizador final não é reutilização.

Constrói cada ligação no código da aplicação a partir da clickUrl resposta, em vez de um modelo o reproduzir. Para os termos que se aplicam, consulte o Anexo B dos Termos de Utilização Web IQ.

Endpoint:POST https://api.microsoft.ai/v3/search/commerce/products

Devoluções classificam produtos e ofertas do vendedor para uma consulta de produto. Use o produto disponível, SKU e identificadores de ofertas com Ofertas. Detalhes do Produto aceita identificadores de produto e SKU.

Pedido de exemplo de Pesquisa de Comércio

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"
  }'

Parâmetros de Pesquisa de Comércio

Parameter Required Tipo Default Description
query Yes cadeia (de caracteres) - Consulta de pesquisa de produto que não esteja em branco. O comprimento máximo é de 1.000 caracteres.
maxResults No número inteiro 10 Número máximo de produtos a devolver, de 1 a 50.
language No cadeia (de caracteres) en Linguagem de resultados ISO 639-1 de duas letras. Ver Mercados Suportados.
region No cadeia (de caracteres) US Código de país ou região de duas letras. Ver Mercados Suportados.
location No cadeia (de caracteres) - Localização no lat:<latitude>;long:<longitude> formato, por lat:37.7749;long:-122.4194exemplo. A latitude deve ser de -90 a 90, e a longitude de -180 a 180.

Resposta de Pesquisa de Comércio

Devolve um CommerceResponse com produtos classificados e as suas ofertas. Se nenhum produto coincidir, a resposta é 200 OK com um array vazio products .

Exemplo 200 OK de resposta (excerto):

{
  "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>"
}

Erros na Pesquisa de Comércio

Um ausente, em branco ou demasiado longo query, um fora de alcance maxResults, um language ou region que não sejam dois caracteres, ou um inválido location retorna 400 (HandlerInvalidInput). As falhas de serviço retornam 500 (InternalServerError). Para erros de autenticação, autorização, formatação e quota, veja Erros.

Limites de pesquisa de comércio

  • query: 1 a 1.000 caracteres, e não apenas espaços em branco.
  • maxResults: 1 a 50, padrão 10. O número de produtos devolvidos depende dos fósforos disponíveis. Não há paginação nem parâmetro para o número de ofertas por produto.
  • language e region: códigos de dois caracteres. location as coordenadas devem estar dentro dos intervalos na tabela de parâmetros.
  • Os limites de taxa e a quota diária do seu perfil de aplicação (AppID) também se aplicam.

Offers

Endpoint:POST https://api.microsoft.ai/v3/fetch/commerce/products/offers

Devolves ofertas elegíveis do vendedor para um produto, SKU ou oferta de representante da Commerce Search. Devolve as ofertas dos vendedores, não feedback ao nível do produto ou histórico de preços.

Ofertas de exemplo de pedido

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"
  }'

Parâmetros das ofertas

Envie todos os produtos disponíveis, SKU e identificadores de oferta para o produto selecionado a partir da resposta do Commerce Search. Se apenas um identificador for devolvido, envie esse identificador. É necessário pelo menos um identificador que não esteja em branco; um pedido sem um devolve 400 (HandlerInvalidInput).

Parameter Required Tipo Default Description
productId Conditional cadeia (de caracteres) - Produto id devolvido pela Commerce Search. Máximo de 1.000 caracteres.
skuId Conditional cadeia (de caracteres) - Produto skuId devolvido pela Commerce Search. Máximo de 1.000 caracteres.
offerId Conditional cadeia (de caracteres) - Oferta id representativa devolvida pela Commerce Search. Máximo de 1.000 caracteres.
language No cadeia (de caracteres) en Linguagem de resultados ISO 639-1 de duas letras. Ver Mercados Suportados.
region No cadeia (de caracteres) US Código de país ou região de duas letras. Ver Mercados Suportados.
location No cadeia (de caracteres) - Localização no lat:<latitude>;long:<longitude> formato. A latitude deve ser de -90 a 90, e a longitude de -180 a 180.

Resposta às ofertas

CommerceOffersResponse

Field Tipo Description
offers variedade de CommerceOffer Ofertas primárias ou representativas primeiro, seguidas de ofertas adicionais.
traceId cadeia (de caracteres) Pedir identificador de rastreio para depuração e correlação.

Para os campos de oferta, consulte CommerceOffer, CommerceOfferImage, CommerceInstallmentInfo e Supporting objects. Identificadores desconhecidos retornam 200 OK com um array vazio offers .

Exemplo 200 OK de resposta (excerto):

{
  "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>"
}

Erros nas ofertas

Um identificador em falta ou vazio, um identificador com mais de 1.000 caracteres, um language ou region que não seja de dois caracteres, ou um inválido location devolve 400 (HandlerInvalidInput). Identificadores desconhecidos retornam 200 OK com um array vazio offers . As falhas de serviço retornam 500 (InternalServerError). Ver Erros.

Limites de ofertas

  • Uma pesquisa produto, SKU ou representativa-oferta por pedido; as pesquisas em lote não são suportadas. Cada identificador está limitado a 1.000 caracteres.
  • Não existe maxResultsum parâmetro de deslocamento ou cursor. O número de ofertas depende da disponibilidade.
  • language e region: códigos de dois caracteres. location as coordenadas devem estar dentro dos intervalos na tabela de parâmetros.
  • Os limites de taxa e a quota diária do seu perfil de aplicação (AppID) também se aplicam.

Detalhes do Produto

Endpoint:POST https://api.microsoft.ai/v3/fetch/commerce/products/details

Devolve o título do produto (),name a descrição e a classificação agregada para um ID de produto, um ID de SKU, ou ambos, do Commerce Search. A descrição está incluída quando disponível.

Detalhes do produto Pedido de exemplo

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"
  }'

Parâmetros de Detalhes do Produto

É necessário pelo menos um productId que skuId não esteja em branco, e podes enviar ambos. offerId não é uma alternativa: um pedido apenas com um ID de oferta falha a validação.

Parameter Required Tipo Default Description
productId Conditional cadeia (de caracteres) - Produto id do Commerce Search. É obrigatório quando não skuId é enviado. Máximo de 1.000 caracteres.
skuId Conditional cadeia (de caracteres) - ID SKU do Commerce Search. É obrigatório quando não productId é enviado. Máximo de 1.000 caracteres.
language No cadeia (de caracteres) en Código linguístico de duas letras. Se omitido ou null, é usado o padrão. Ver Mercados Suportados.
region No cadeia (de caracteres) US Código de região de duas letras para a pesquisa do produto. Se omitido ou null, é usado o padrão. Ver Mercados Suportados.

Resposta aos Detalhes do Produto

ComércioDetalhesProdutoResposta

Field Tipo Description
products array de CommerceProductDetails Nenhum ou um produto correspondente. Pesquisas em lote não são suportadas.
traceId cadeia (de caracteres) Solicitar identificador de rastreio.

CommerceProdutosDetalhes

Field Tipo Description
id cadeia (de caracteres) Identificador de produto entre variantes, correspondendo ao Commerce Search.
name cadeia (de caracteres) Título do produto, quando disponível.
description cadeia (de caracteres) Descrição do produto, quando disponível.
rating Classificação CommerceRating A média do produto e a contagem de avaliações, numa escala de 1 a 5.

Classificação CommerceRating

O rating objeto é omitido quando não há classificação disponível.

Field Tipo Description
value number Classificação média do produto, arredondada para duas casas decimais.
scaleMin number No fundo da escala de avaliação (1).
scaleMax number Topo da escala de avaliação (5).
count número inteiro Número de avaliações para o produto. Uma contagem de zero é devolvida como 0.

Produtos desconhecidos regressam 200 OK com um array vazio products .

Exemplo de resposta 200 OK:

{
  "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>"
}

Erros nos detalhes do produto

Um identificador de produto ou SKU em falta ou vazio, um identificador com mais de 1.000 caracteres, ou um language ou region que não seja dois caracteres retorna 400 (HandlerInvalidInput). As falhas de serviço retornam 500 (InternalServerError). Ver Erros.

Limites de detalhes do produto

  • Pelo menos um identificador de produto ou SKU, com até 1.000 caracteres cada. Pesquisas em lote e pesquisas apenas por ID de oferta não são suportadas.
  • language e region: códigos de dois caracteres.
  • Os limites de taxa e a quota diária do seu perfil de aplicação (AppID) também se aplicam.

Objetos de resposta

Estes objetos são devolvidos pelo Commerce Search and Offers.

CommerceResponse

Field Tipo Description
products variedade de CommerceProduct Produtos por ordem de classificação.
traceId cadeia (de caracteres) Pedir identificador de rastreio para depuração e correlação.

CommerceProduct

Field Tipo Description
id cadeia (de caracteres) Identificador de produto entre variantes.
skuId cadeia (de caracteres) Identificador SKU do catálogo.
offers variedade de CommerceOffer Ofertas do vendedor principal.

CommerceOffer

Field Tipo Description
id cadeia (de caracteres) Identificador de oferta.
name cadeia (de caracteres) Título do vendedor.
description cadeia (de caracteres) Descrição do vendedor.
specifications array de CommerceSpecification Especificações ao nível da oferta e atributos selecionados. Os duplicados e a ordem das fontes são preservados. Ver Objetos de apoio.
seller CommerceSeller Detalhes de comerciantes. Ver Objetos de apoio.
price CommerceOfferPrice Oferta de preços em unidades menores ISO 4217. offeredPrice Volta para listPrice quando não há preço com desconto. Ver Objetos de apoio.
displayUrl cadeia (de caracteres) URL do comerciante ou vendedor, apenas para contexto de exibição ou modelo. Não o uses como link ou alvo de navegação.
clickUrl cadeia (de caracteres) Destino para cada ligação ou navegação para a oferta. Usa-o exatamente como devolvido. Ver Links e atribuição de ofertas.
images array do CommerceOfferImage Oferece imagens.
installmentInfo CommerceInstallmentInfo Detalhes do pagamento a prestações.
shippingInfo cadeia (de caracteres) Informação de envio, como texto legível.
condition cadeia (de caracteres) Condição fornecida pelo vendedor do artigo oferecido.

CommerceOfferImage

Field Tipo Description
url cadeia (de caracteres) URL da imagem.

CommerceInstallmentInfo

Field Tipo Description
description cadeia (de caracteres) Descrição do plano de prestações, como texto legível.
downPayment CommercePrice Quantidade exigida antecipadamente. Ver Objetos de apoio.
monthlyPayment CommercePrice Pagamento mensal em prestações. Ver Objetos de apoio.
months número inteiro Número de meses.

Objetos de apoio

Os preços são inteiros em unidades menores da moeda ISO 4217. Por exemplo, 10000 com currencyUSD são $100,00.

Object Field Tipo Description
CommerceOfferPrice listPrice número inteiro Preço original em unidades menores ISO 4217.
CommerceOfferPrice offeredPrice número inteiro Preço atual em unidades menores ISO 4217. Volta para listPrice quando não há preço com desconto disponível.
CommerceOfferPrice currency cadeia (de caracteres) Código de moeda ISO 4217.
CommercePrice amount número inteiro Valor do pagamento em unidades menores da ISO 4217.
CommercePrice currency cadeia (de caracteres) Código de moeda ISO 4217.
CommerceSeller name cadeia (de caracteres) Nome de exibição do comerciante.
CommerceSeller logoUrl cadeia (de caracteres) URL do logótipo do comerciante.
CommerceSpecification name cadeia (de caracteres) Oferecer nome do atributo.
CommerceSpecification values Matriz de cadeia de caracteres Valores de exibição de atributos, preservação de duplicados e ordem de origem.

Errors

Estes erros aplicam-se a todos os três endpoints. O comportamento de validação e resultado vazio de cada endpoint é descrito numa secção própria.

Estado HTTP Código de erro Significado e ação
400 RequestInvalidFormat, HandlerInvalidInput JSON malformado, ou parâmetros de pedido que estão em falta ou são inválidos. Corrige o pedido usando a tabela de parâmetros e os limites do endpoint.
401 Erros de autenticação, como AuthNoToken ou AuthInvalidApiKey As credenciais estão em falta, inválidas ou expiradas. Autentique novamente com credenciais válidas.
403 AuthUnauthorizedService O chamador não está autorizado a aceder ao recurso solicitado. Se o seu perfil de aplicação não estiver ativado para o Commerce, solicite acesso conforme descrito no topo desta página.
405 MethodNotAllowed Use POST, não GET.
415 RequestUnsupportedMediaType Enviar content-type: application/json.
429 AuthUserThrottled, AuthUserDailyUsageExceeded O limite de taxa ou quota diária do seu perfil de aplicação (AppID) foi ultrapassado. Espera pelo tempo de entrada retryAfter antes de tentares novamente.
500 InternalServerError O serviço não conseguiu concluir o pedido. Tente novamente após o atraso indicado e inclua o traceId momento em que contactar o suporte.

Resposta de erro

Os erros utilizam a estrutura de resposta partilhada ao erro.

Field Tipo Description
errorCode cadeia (de caracteres) Código de erro legível por máquina.
errorCategory cadeia (de caracteres) UserError ou SystemError.
userMessage cadeia (de caracteres) Explicação legível do erro.
technicalDetails cadeia (de caracteres) Detalhes opcionais de diagnóstico.
retryAfter cadeia (de caracteres) Atraso opcional de retentativa em segundos, seguido de um s sufixo (por exemplo, "60s").
requestId cadeia (de caracteres) Identificador de pedido opcional.
traceId cadeia (de caracteres) Identificador de traço distribuído opcional para suporte.

Exemplo de erro

Um pedido de Pesquisa de Comércio sem query:

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

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

Limites tarifários

Os três endpoints usam os limites de taxa e a quota diária do seu AppID Web IQ (15 consultas por segundo por defeito), partilhados com as outras APIs Web IQ que o AppID chama. Uma 429 resposta inclui o atraso de retentativa em retryAfter. Quotas diárias reiniciadas às 00:00 UTC. Para orientações sobre retentativas, veja Gestão de erros.