Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 |
Oferta de links e atribuição
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.
Pesquisa de Comércio
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ão10. 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. -
languageeregion: códigos de dois caracteres.locationas 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. -
languageeregion: códigos de dois caracteres.locationas 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.
-
languageeregion: 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.