Referência da API REST do Comércio (versão prévia privada)

Note

O IQ Commerce da Web está em versão prévia privada e está incluído com AppIDs que têm acesso completo a documentos. O acesso é habilitado separadamente para Pesquisa, Ofertas e Detalhes do Produto. Durante a visualização privada, o uso é cobrado em US$ 7,00 por 1.000 chamadas à API. A superfície da API e o contrato podem ser alterados.

Os clientes qualificados podem experimentar as APIs de Comércio no Playground no Portal do Desenvolvedor de Qi da Web. Se você não usou o Playground antes, comece com o Início Rápido.

Se o AppID não tiver as APIs de Comércio ou você tiver dúvidas, abra uma solicitação de Suporte ao IQ da Web, escolha Autenticação & Acesso como o tipo de problema e a Configuração de Chave de API como o subtipo, selecione Criar uma solicitação de suporte e inclua sua AppID (copie-a do Gerenciamento de Perfil no Portal do Desenvolvedor do IQ da Web) ou, se você ainda não tiver uma, o nome da sua empresa e o nome do recurso de qi da Web.

As APIs de Comércio de IQ da Web são Pesquisa de Comércio, Ofertas e Detalhes do Produto. A Pesquisa de Comércio retorna produtos classificados e ofertas de vendedor para uma consulta de produto. Use os identificadores de oferta, SKU e produto disponíveis com Ofertas. Os Detalhes do Produto aceitam identificadores de SKU e produtos.

Todos os três pontos de extremidade aceitam POST solicitações com um corpo JSON. Autentique com uma chave de API habilitada para o Comércio no x-apikey cabeçalho ou com um token de acesso Microsoft Entra ID no Authorization cabeçalho. Consulte Autenticação para obter instruções de instalação.

Exemplos usam produtos fictícios da Contoso, vendedores, identificadores, URLs e preços. Substitua identificadores de exemplo por valores da resposta da Pesquisa de Comércio ao fazer solicitações de acompanhamento.

Cabeçalhos de solicitação

Cabeçalho Tipo Description
x-apikey ou Autorização cadeia Sua chave de API ou Entra ID token de acesso para autenticação.
tipo de conteúdo cadeia Tipo MIME do corpo da solicitação. Use application/json.

Mercados com suporte

Durante a visualização privada, as APIs de Comércio dão suporte a essas combinações de language e region. Não há suporte para outras combinações.

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 você apresentar, use exatamente clickUrl como retornado nessa resposta para cada link ou navegação para a oferta, seja por um usuário ou por um agente que atua para o usuário. Por padrão, clickUrl é um redirecionamento hospedado Microsoft; Microsoft também pode retornar uma URL de comerciante direto. Use displayUrl apenas para identificar o comerciante ou vendedor em seu contexto de exibição ou de modelo, nunca como um link ou destino de navegação. Se uma oferta não tiver uma usá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, portanto, pode não estar visível. Não remova, reescreva, trunque, decodize ou substitua o clickUrl parâmetro de atribuição e não ignore seus redirecionamentos ou adicione um parâmetro por conta própria. Você pode encapsular um clickUrl link de rastreamento ou redirecionamento somente se ele passar o original clickUrl por meio de unaltered. Não reutilize um clickUrl para uma resposta, consulta, usuário ou finalidade diferentes, inclusive por meio de um cache. O próprio compartilhamento ou encaminhamento de um usuário final não é reutilizado.

Crie cada link no código do aplicativo a clickUrl partir da resposta, em vez de ter um modelo reproduzi-lo. Para obter os termos que se aplicam, consulte a Exibição B dos Termos de Uso do IQ da Web.

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

Retorna produtos classificados e ofertas de vendedor para uma consulta de produto. Use os identificadores de oferta, SKU e produto disponíveis com Ofertas. Os Detalhes do Produto aceitam identificadores de SKU e produtos.

Solicitação 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

Parâmetro Required Tipo Default Description
query Yes cadeia - Consulta de pesquisa de produto que não está em branco. O comprimento máximo é de 1.000 caracteres.
maxResults No inteiro 10 Número máximo de produtos a serem retornados, de 1 a 50.
language No cadeia en Idioma de resultado ISO 639-1 de duas letras. Consulte os mercados com suporte.
region No cadeia US Código de país ou região de duas letras. Consulte os mercados com suporte.
location No cadeia - Local no lat:<latitude>;long:<longitude> formato, por exemplo lat:37.7749;long:-122.4194. A latitude deve ser de -90 a 90 e longitude de -180 a 180.

Resposta da Pesquisa de Comércio

Retorna um CommerceResponse com produtos classificados e suas ofertas. Se nenhum produto corresponder, a resposta será 200 OK com uma matriz vazia products .

Exemplo 200 OK de resposta (trecho):

{
  "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 de Pesquisa de Comércio

Um ausente, em branco ou longoquery, um fora do intervalomaxResults, um language ou region que não é dois caracteres ou um retorno 400 inválido location (HandlerInvalidInput). Retorno de falhas de serviço 500 (InternalServerError). Para obter erros de autenticação, autorização, formato e cota, consulte Erros.

Limites da Pesquisa de Comércio

  • query: 1 a 1.000 caracteres e não apenas espaço em branco.
  • maxResults: 1 a 50, padrão 10. O número de produtos retornados depende das correspondências disponíveis. Não há paginação e nenhum 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 cota diária do seu perfil de aplicativo (AppID) também se aplicam.

Offers

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

Retorna ofertas de vendedor qualificadas para um produto, SKU ou oferta representativa da Pesquisa de Comércio. Ele retorna ofertas do vendedor, não comentários no nível do produto ou histórico de preços.

Solicitação de exemplo de ofertas

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 de ofertas

Envie todos os identificadores de produto, SKU e oferta disponíveis para o produto selecionado na resposta da Pesquisa de Comércio. Se apenas um identificador for retornado, envie esse identificador. Pelo menos um identificador que não está em branco é necessário; uma solicitação sem um retorna 400 (HandlerInvalidInput).

Parâmetro Required Tipo Default Description
productId Condicional cadeia - Produto id retornado pela Pesquisa de Comércio. Máximo de 1.000 caracteres.
skuId Condicional cadeia - Produto skuId retornado pela Pesquisa de Comércio. Máximo de 1.000 caracteres.
offerId Condicional cadeia - Oferta representativa id retornada pela Pesquisa de Comércio. Máximo de 1.000 caracteres.
language No cadeia en Idioma de resultado ISO 639-1 de duas letras. Consulte os mercados com suporte.
region No cadeia US Código de país ou região de duas letras. Consulte os mercados com suporte.
location No cadeia - Local em lat:<latitude>;long:<longitude> formato. A latitude deve ser de -90 a 90 e longitude de -180 a 180.

Resposta de ofertas

CommerceOffersResponse

Field Tipo Description
offers matriz de CommerceOffer Ofertas primárias ou representativas primeiro, seguidas por ofertas adicionais.
traceId cadeia Solicitar identificador de rastreamento para depuração e correlação.

Para os campos de oferta, consulte CommerceOffer, CommerceOfferImage, CommerceInstallmentInfo e objetos de suporte. Identificadores desconhecidos retornam 200 OK com uma matriz vazia offers .

Exemplo 200 OK de resposta (trecho):

{
  "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 de ofertas

Um identificador ausente ou em branco, um identificador com mais de 1.000 caracteres, um language ou region que não seja dois caracteres ou um retorno 400 inválido location (HandlerInvalidInput). Identificadores desconhecidos retornam 200 OK com uma matriz vazia offers . Retorno de falhas de serviço 500 (InternalServerError). Consulte Erros.

Limites de ofertas

  • Um produto, SKU ou pesquisa de oferta representativa por solicitação; Não há suporte para pesquisas em lotes. Cada identificador é limitado a 1.000 caracteres.
  • Não há parâmetro maxResults, 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 cota diária do seu perfil de aplicativo (AppID) também se aplicam.

Detalhes do produto

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

Retorna o título do produto (name), a descrição e a classificação de agregação para uma ID do produto, uma ID de SKU ou ambos, da Pesquisa de Comércio. A descrição é incluída quando disponível.

Solicitação de exemplo de Detalhes do Produto

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

Pelo menos um productId ou skuId que não está em branco é necessário e você pode enviar ambos. offerId não é uma alternativa: uma solicitação com apenas uma ID de oferta falha na validação.

Parâmetro Required Tipo Default Description
productId Condicional cadeia - Produto id da Pesquisa de Comércio. Necessário quando não skuId for enviado. Máximo de 1.000 caracteres.
skuId Condicional cadeia - ID de SKU da Pesquisa de Comércio. Necessário quando não productId for enviado. Máximo de 1.000 caracteres.
language No cadeia en Código de idioma de duas letras. Se omitido ou null, o padrão é usado. Consulte os mercados com suporte.
region No cadeia US Código de região de duas letras para a pesquisa do produto. Se omitido ou null, o padrão é usado. Consulte os mercados com suporte.

Resposta dos Detalhes do Produto

CommerceProductDetailsResponse

Field Tipo Description
products matriz de CommerceProductDetails Zero ou um produto correspondente. Não há suporte para pesquisas em lote.
traceId cadeia Identificador de rastreamento de solicitação.

CommerceProductDetails

Field Tipo Description
id cadeia Identificador de produto entre variantes, correspondente à Pesquisa de Comércio.
name cadeia Título do produto, quando disponível.
description cadeia Descrição do produto, quando disponível.
rating CommerceRating Classificação média do produto e contagem de classificação, em uma escala de 1 a 5.

CommerceRating

O rating objeto é omitido quando nenhuma classificação está disponível.

Field Tipo Description
value número Classificação média do produto, arredondada para duas casas decimais.
scaleMin número Parte inferior da escala de classificação (1).
scaleMax número Parte superior da escala de classificação (5).
count inteiro Número de classificações para o produto. Uma contagem de zero é retornada como 0.

Os produtos desconhecidos retornam 200 OK com uma matriz vazia products .

Exemplo 200 OK de resposta:

{
  "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 de Detalhes do Produto

Um produto ou identificador de SKU ausente ou em branco, um identificador com mais de 1.000 caracteres ou um language ou region que não seja dois caracteres retorna 400 (HandlerInvalidInput). Retorno de falhas de serviço 500 (InternalServerError). Consulte Erros.

Limites de Detalhes do Produto

  • Pelo menos um identificador de SKU ou produto, até 1.000 caracteres cada. Não há suporte apenas para pesquisas e pesquisas em lote por ID da oferta.
  • language e region: códigos de dois caracteres.
  • Os limites de taxa e a cota diária do seu perfil de aplicativo (AppID) também se aplicam.

Objetos de resposta

Esses objetos são retornados pela Pesquisa e Ofertas do Comércio.

CommerceResponse

Field Tipo Description
products matriz de CommerceProduct Produtos em ordem de classificação.
traceId cadeia Solicitar identificador de rastreamento para depuração e correlação.

CommerceProduct

Field Tipo Description
id cadeia Identificador de produto entre variantes.
skuId cadeia Identificador de SKU do catálogo.
offers matriz de CommerceOffer Ofertas do vendedor primário.

CommerceOffer

Field Tipo Description
id cadeia Identificador de oferta.
name cadeia Título do vendedor.
description cadeia Descrição do vendedor.
specifications matriz de CommerceSpecification Especificações de nível de oferta e atributos selecionados. Duplicatas e ordem de origem são preservadas. Consulte objetos de suporte.
seller CommerceSeller Detalhes do comerciante. Consulte objetos de suporte.
price CommerceOfferPrice Preços da oferta em unidades secundárias ISO 4217. offeredPrice volta para listPrice quando nenhum preço de desconto está presente. Consulte objetos de suporte.
displayUrl cadeia URL do comerciante ou vendedor, somente para exibição ou contexto de modelo. Não o use como um link ou destino de navegação.
clickUrl cadeia Destino para cada link ou navegação para a oferta. Use-o exatamente como retornado. Consulte links e atribuição da Oferta.
images matriz de CommerceOfferImage Oferecer imagens.
installmentInfo CommerceInstallmentInfo Detalhes do pagamento de parcelamento.
shippingInfo cadeia Informações de envio, como texto legível.
condition cadeia Condição fornecida pelo vendedor do item oferecido.

CommerceOfferImage

Field Tipo Description
url cadeia URL da imagem.

CommerceInstallmentInfo

Field Tipo Description
description cadeia Descrição do plano de parcelamento, como texto legível.
downPayment CommercePrice Valor necessário antecipadamente. Consulte objetos de suporte.
monthlyPayment CommercePrice Pagamento de parcela mensal. Consulte objetos de suporte.
months inteiro Número de meses.

Suporte a objetos

Os preços são inteiros nas unidades secundárias iso 4217 da moeda. Por exemplo, 10000 com currencyUSD é $100.00.

Object Field Tipo Description
CommerceOfferPrice listPrice inteiro Preço original em unidades secundárias ISO 4217.
CommerceOfferPrice offeredPrice inteiro Preço atual em unidades secundárias ISO 4217. Volta para listPrice quando nenhum preço de desconto está disponível.
CommerceOfferPrice currency cadeia Código de moeda ISO 4217.
CommercePrice amount inteiro Valor do pagamento em unidades secundárias ISO 4217.
CommercePrice currency cadeia Código de moeda ISO 4217.
CommerceSeller name cadeia Nome de exibição do comerciante.
CommerceSeller logoUrl cadeia URL do logotipo do comerciante.
CommerceSpecification name cadeia Nome do atributo de oferta.
CommerceSpecification values matriz de strings Valores de exibição de atributo, preservando duplicatas e ordem de origem.

Erros

Esses erros se aplicam a todos os três pontos de extremidade. A validação e o comportamento de resultado vazio de cada ponto de extremidade são descritos em sua própria seção.

Status de HTTP Código de erro Significado e ação
400 RequestInvalidFormat, HandlerInvalidInput JSON malformado ou parâmetros de solicitação ausentes ou inválidos. Corrija a solicitação usando a tabela e os limites de parâmetros do ponto de extremidade.
401 Erros de autenticação, como AuthNoToken ou AuthInvalidApiKey As credenciais estão ausentes, inválidas ou expiradas. Autentique novamente com credenciais válidas.
403 AuthUnauthorizedService O chamador não está autorizado a acessar o recurso solicitado. Se o perfil do aplicativo não estiver habilitado para o Comércio, solicite acesso conforme descrito na parte superior 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 cota diária do seu perfil de aplicativo (AppID) foi excedido. Aguarde o tempo retryAfter antes de tentar novamente.
500 InternalServerError O serviço não conseguiu concluir o pedido. Tente novamente após o atraso indicado e inclua quando entrar em contato com o traceId suporte.

Resposta de erro

Os erros usam a estrutura de resposta de erro compartilhada.

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

Exemplo de erro

Uma solicitação 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 de taxa

Todos os três pontos de extremidade usam os limites de taxa e a cota diária do AppID do IQ Da Web (15 consultas por segundo por padrão), compartilhados com as outras APIs de IQ da Web que o AppID chama. Uma 429 resposta inclui o atraso de repetição em retryAfter. As cotas diárias são redefinidas às 00:00 UTC. Para obter diretrizes de repetição, consulte Tratamento de erros.