Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 |
Links de ofertas e atribuição
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.
Pesquisa de Comércio
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ão10. 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. -
languageeregion: códigos de dois caracteres.locationas 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. -
languageeregion: códigos de dois caracteres.locationas 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.
-
languageeregion: 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.