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.
As APIs do Microsoft Web IQ Commerce retornam produtos estruturados, ofertas de vendedor e detalhes do produto que seu aplicativo pode usar para criar uma experiência de compra. Seu aplicativo pode usar um modelo de IA para interpretar a solicitação de um comprador e explicar as opções de produto, enquanto renderiza os preços, os vendedores e os links dos resultados da API em vez de gerá-los.
Note
As APIs de Comércio estão em versão prévia privada e estão incluídas com AppIDs que têm acesso completo a documentos. O acesso é habilitado separadamente para Pesquisa, Ofertas e Detalhes do Produto: o acesso à pesquisa sozinho não dá acesso aos pontos de extremidade de acompanhamento. Se o AppID não os tiver, abra uma solicitação de suporte do Web IQ (tipo de problema Authentication & Access) com seu AppID. Para fazer suas primeiras chamadas, consulte a etapa 8 do Início Rápido.
Escolher um ponto de extremidade
| Pergunta do comprador | Endpoint | Entrada | Result |
|---|---|---|---|
| Quais produtos correspondem? | POST /v3/search/commerce/products |
Consulta de produto | Classificado products com vendedor principal offers |
| Onde posso comprar isso? | POST /v3/fetch/commerce/products/offers |
Produto, SKU ou ID da oferta representativa | Vendedor offersqualificado, com ofertas representativas primeiro |
| Quais são os detalhes do produto? | POST /v3/fetch/commerce/products/details |
ID de SKU ou produto | Zero ou um produto com nome, descrição e avaliação agregada quando disponível |
Os caminhos são relativos a https://api.microsoft.ai. Cada ponto de extremidade usa um corpo JSON e uma chave de API ou token de Microsoft Entra ID habilitado para o Comércio; consulte Autenticação. Você pode usar a Pesquisa sozinho e chamar Ofertas ou Detalhes do Produto quando a experiência precisar delas.
Conectar as chamadas
- Envie uma consulta concisa do comprador para Search e selecione um dos produtos retornados.
- Para Ofertas, envie todos os identificadores que o resultado tem: o produto
idcomoproductId, seuskuIdcomoskuId, e aidde sua oferta representativa comoofferId. Use os IDs do mesmo resultado. Pelo menos um é obrigatório. - Para detalhes do produto, envie o produto
idcomoproductId, seuskuIdou ambos. - Manipule
200 OKcom um arrayoffersouproductsvazio como nenhuma correspondência, não como uma solicitação com falha. As solicitações de acompanhamento funcionam em um produto, SKU ou oferta representativa por vez; esses pontos de extremidade não dão suporte a IDs de lote ou paginação.
Tratar identificadores como cadeias de caracteres opacas. Um resultado da pesquisa pode não conter todas as IDs: alguns produtos retornam apenas uma oferta. Se apenas um ID de oferta estiver disponível, você poderá solicitar Offers, mas não Product Details. Não suponha que uma ID permaneça válida ao longo do tempo ou que uma ID tenha precedência quando você enviar várias.
Escolha o mercado
Todos os três pontos de extremidade aceitam dois caracteres language e region valores, com en e US como padrões; consulte mercados com suporte para as combinações disponíveis na versão prévia privada. A pesquisa e as ofertas também aceitam um opcional location no formulário lat:<latitude>;long:<longitude>, com latitude de -90 a 90 e longitude de -180 a 180. Os Detalhes do Produto não aceitam um location.
Use o mercado escolhido pelo comprador de forma consistente entre as chamadas. Enviar localização ou outro contexto pessoal somente quando o aplicativo estiver autorizado a fazer isso. A cobertura do catálogo varia de acordo com o mercado.
Controlar o número de resultados
maxResults pesquisa solicita de 1 a 50 produtos, com padrão de 10; não define o número de ofertas. Um conjunto de resultados menor pode ser útil quando você envia resultados diretamente para um modelo. Um conjunto de candidatos maior pode ser útil quando o aplicativo filtra ou classifica os resultados primeiro. A pesquisa pode retornar menos produtos do que o solicitado.
As ofertas não têm maxResults, deslocamento nem cursor; o número de ofertas depende da disponibilidade. Detalhes do produto retornam no máximo um produto.
Criar uma ferramenta de agente
Uma abordagem é expor a Pesquisa como uma ferramenta e manter as configurações de mercado no código do aplicativo confiável. Veja a seguir um esquema de ferramenta ilustrativo, não um ponto de extremidade do Web IQ:
{
"name": "search_products",
"description": "Find ranked products and seller offers for a shopping request.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "A nonblank product query of at most 1000 characters."
},
"maxResults": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"description": "Maximum number of products to request; default 10."
}
},
"required": ["query"]
}
}
O manipulador de ferramentas deve validar os argumentos do modelo, adicionar as opções selecionadas pelo usuário language e region, e chamar a Pesquisa com credenciais do lado do servidor. A pesquisa aceita uma consulta não vazia de até 1.000 caracteres. Para uma solicitação que envolve vários tipos de produto distintos, considere uma chamada de Pesquisa separada por tipo e limite a simultaneidade e o volume de solicitação: cada chamada conta com relação ao limite de taxa e cota do AppID.
Dê ao modelo uma seleção compacta dos campos retornados e mantenha as IDs necessárias para chamadas de acompanhamento. Trate títulos de vendedores, descrições e outros textos retornados como dados não confiáveis, não instruções. Não deixe um modelo gerar URLs de compra ou alegar que um produto, preço ou classificação existe quando a API não o retornou.
Filtrar, classificar e renderizar resultados
- Verifique as restrições rígidas no código do aplicativo. Se o comprador especificar um preço máximo, condição, tamanho ou outros atributos, verifique os dados de oferta disponíveis antes de mostrar uma correspondência. Se um campo necessário estiver ausente ou não puder ser interpretado, não afirme que a restrição foi atendida. A oferta
specificationspode incluir atributos como marca ou tamanho, mas a disponibilidade e os valores variam. - Classifique os candidatos. Comece com o ranking do produto Search e aplique os critérios do seu aplicativo. Se você usar um modelo para classificar novamente, envie-o apenas aos candidatos que você deseja que ele considere e mantenha os dados estruturados originais para renderização.
- Compare itens equivalentes. Para comparações do vendedor, verifique o produto e a variante, a moeda e a condição. Remova as IDs de oferta repetidas antes de exibir uma lista e verifique as ofertas antes de alegar o menor preço.
- Renderizar a partir dos campos. Use a oferta
name,seller.name,price,shippingInfo,conditioneimages[].urlquando presentes. Para cada oferta que você apresentar, inclua um link para seuclickUrlnessa resposta. UsedisplayUrlapenas para identificar o comerciante ou vendedor na exibição, não como destino. Consulte Link para ofertas. - Falhar de forma controlada. Se uma etapa de modelo falhar, mostre os resultados estruturados disponíveis sem comentários gerados quando apropriado. Se uma solicitação de Comércio falhar, diga que os resultados estão indisponíveis e ofereça uma nova tentativa, em vez de inventar produtos ou preços.
Os Detalhes do Produto podem retornar um produto name, description e um agregado rating. A classificação é omitida quando não disponível. Seus value, scaleMin, scaleMax e count descrevem o produto, não uma oferta individual ou uma variante específica. Não infera o texto da avaliação ou um resumo da avaliação a partir da avaliação agregada.
Link para as ofertas
Para cada oferta que você apresentar, use exatamente o seu clickUrl como foi retornado nessa resposta para enviar um usuário, ou um agente atuando para o usuário, para a oferta. Use displayUrl apenas para identificar o comerciante ou vendedor em sua exibição ou como contexto para um modelo, nunca para navegação. Se uma oferta não tiver um clickUrl utilizável, não apresente a oferta; não recorra a displayUrl nem crie um link.
Trate o clickUrl como opaco: não remova, reescreva, trunque, decodifique ou substitua-o, não ignore seus redirecionamentos e não reutilize-o para uma resposta, consulta, usuário ou finalidade diferentes, inclusive por meio de um cache. Para obter as regras completas, incluindo quando você pode encapsular um clickUrl em seu próprio link de acompanhamento, consulte links de oferta e atribuição na referência de Comércio e exibição B dos Termos de Uso do IQ da Web.
Criar navegação no código, não no modelo
Mantenha cada original clickUrl no código do aplicativo confiável, associado à sua oferta, resposta e usuário. Envie ao modelo um identificador de oferta que seu aplicativo gera para essa resposta, juntamente com as informações relevantes do produto. O modelo pode selecionar um identificador, mas não deve reproduzir ou modificar o link. Resolva o identificador em relação à resposta original ao renderizar ou navegar e rejeite identificadores desconhecidos ou obsoletos em vez de voltar para uma URL gerada pelo modelo. Se um agente precisar receber um clickUrl, verifique se ele recebe e usa o valor original exato.
O exemplo de navegador a seguir cria um link de um objeto de oferta na resposta atual. Como uma política de aplicativo conservadora, ela aceita apenas links HTTPS e rejeita valores que o analisador de URL do navegador ou a serialização de link alteraria. Ele atribui a cadeia de caracteres original, não uma URL reconstruída. Quando ele retornar null, não apresente essa oferta. Você pode executá-lo em um console do navegador; a verificação final confirma se a URL está preservada e que destinos ausentes ou não seguros são rejeitados.
function createOfferLink(offer) {
if (typeof offer.clickUrl !== "string" || offer.clickUrl.length === 0) {
return null;
}
try {
const parsed = new URL(offer.clickUrl);
if (parsed.protocol !== "https:" || parsed.href !== offer.clickUrl) return null;
} catch {
return null;
}
const link = document.createElement("a");
link.setAttribute("href", offer.clickUrl);
if (link.href !== offer.clickUrl) return null;
link.textContent = offer.name || "View offer";
return link;
}
const exampleClickUrl = "https://merchant.example/offer?attribution=opaque%2Fvalue";
const exampleLink = createOfferLink({ clickUrl: exampleClickUrl, name: "Example offer" });
if (
exampleLink?.getAttribute("href") !== exampleClickUrl ||
createOfferLink({ clickUrl: "javascript:alert(1)" }) !== null ||
createOfferLink({ displayUrl: "https://merchant.example/products/headphones" }) !== null
) {
throw new Error("Offer links must preserve clickUrl without a fallback.");
}
Essa verificação não verifica redirecionamentos ou wrappers mais abaixo do caminho; teste o caminho de navegação completo em seu aplicativo. Não use uma citação gerada por modelo, um link do Markdown ou displayUrl como destino.
Formatar preços
listPrice, offeredPricee os valores de parcelamento são inteiros em unidades secundárias ISO 4217. USD usa dois dígitos decimais, portanto 39999 é USD 399,99; JPY usa zero. Use a própria escala de unidade secundária da moeda, não uma divisão fixa por 100.
offeredPrice recorre a listPrice quando não há preço de desconto. Mostre um preço de lista como um preço anterior somente se for maior que o preço oferecido e os termos aplicáveis permitirem.
Por exemplo, este formatador JavaScript manipula três moedas explicitamente:
function formatPrice(amount, currency, locale = "en-US") {
const minorUnitDigits = { USD: 2, JPY: 0, KWD: 3 };
const digits = minorUnitDigits[currency];
if (!Number.isSafeInteger(amount) || digits === undefined) {
throw new Error("Unsupported currency or unsafe integer amount");
}
const formatter = new Intl.NumberFormat(locale, {
style: "currency",
currency,
minimumFractionDigits: digits,
maximumFractionDigits: digits,
});
return formatter.format(amount / 10 ** digits);
}
console.log(formatPrice(39999, "USD")); // $399.99 in en-US
Em produção, use uma tabela mantida de unidades secundárias da ISO 4217 para cada moeda que seu aplicativo suporta, em vez de inferir a escala a partir dos padrões de exibição de Intl. Não compare valores entre moedas sem uma política de conversão. Os preços e a disponibilidade mudam, portanto, exiba-os da resposta atual.
Lidar com erros e limites de taxa
Todos os três pontos de extremidade usam os limites de taxa e a cota diária de seu AppID (15 consultas por segundo por padrão), compartilhados com as outras APIs de IQ da Web que o AppID chama. Erros de taxa e cota retornam 429; verifique o errorCode e retryAfter na resposta.
| Resposta | Ação recomendada |
|---|---|
400, 401, 403 ou 415 |
Corrija a solicitação, as credenciais ou o acesso. Repetir uma solicitação inalterada não ajuda. |
429 AuthUserThrottled |
Aguarde pelo menos o tempo de retryAfter se estiver presente e tente novamente com backoff exponencial limitado e jitter. Reduza a frequência da solicitação. |
429 AuthUserDailyUsageExceeded |
Não tente novamente; a cota diária é redefinida às 00:00 UTC. |
500 InternalServerError |
Siga qualquer retryAfter orientação e tente novamente com backoff limitado e jitter. Se as falhas persistirem, entre em contato com o Suporte do Web IQ. |
Para erros do Commerce, retryAfter é uma duração, por exemplo "60s", quando presente. Defina um tempo limite e um orçamento total de novas tentativas. Registre o ponto de extremidade, o status, o código de erro e traceId, e evite registrar em log as credenciais ou os dados do comprador de que você não precisa. Veja Tratamento de erros.
Testar antes do lançamento
- Crie um conjunto representativo de consultas de compradores para as categorias e mercados que você dá suporte.
- Inspecione os resultados brutos da Pesquisa antes de aplicar sua própria filtragem e classificação e compare a experiência final.
- Verifique uma amostra de produtos retornados, links do vendedor, preços e condições comparando com as páginas do vendedor antes de fazer declarações sobre eles.
- Verifique se a navegação de usuário e agente usa exatamente
clickUrla partir da resposta correspondente, inclusive por meio de qualquer wrapper próprio, que os redirecionamentos são preservados e que os links não são reutilizados para outra resposta, consulta, usuário ou finalidade. - Teste valores ausentes ou não utilizáveis de
clickUrle identificadores de ofertas gerados pelo modelo ou obsoletos, e verifique se nenhum deles recorra adisplayUrlou a um link gerado. - Teste resultados vazios, campos ausentes, produtos sem uma ID de SKU ou produto, tempos limite, limitação, esgotamento de cota e falhas de modelo.
- Controlar volume de solicitação, erros e IDs de rastreamento. Inclua uma ID de rastreamento relevante quando você entrar em contato com o Suporte do Web IQ.
Próximas Etapas
- Faça suas primeiras chamadas de Commerce na etapa 8 do Quickstart.
- Consulte a referência da API de Comércio para o contrato de solicitação e resposta completo.
- Consulte o tratamento de erros para códigos de erro e as diretrizes de repetição.