Construa uma experiência de compra com as APIs do Commerce (pré-visualização privada)

As APIs do Microsoft Web IQ Commerce devolvem produtos estruturados, ofertas de vendedores e detalhes de produto que a sua aplicação pode utilizar para fundamentar uma experiência de compra. A sua aplicação pode usar um modelo de IA para interpretar o pedido de um comprador e explicar as escolhas de produto, enquanto apresenta preços, vendedores e links a partir dos resultados da API em vez de os gerar.

Note

As APIs de Comércio estão em pré-visualização privada e estão incluídas com AppIDs que têm acesso completo aos documentos. O acesso está ativado separadamente para Pesquisa, Ofertas e Detalhes do Produto: O acesso à pesquisa por si só não dá acesso aos endpoints de seguimento. Se o seu AppID não os tiver, abra um pedido de Suporte Web IQ (tipo de problema Autenticação e Acesso) com o seu AppID. Para fazer as suas primeiras chamadas, consulte o passo 8 do Quickstart.

Escolha um ponto final

Pergunta do comprador Endpoint Input Result
Que produtos correspondem? POST /v3/search/commerce/products Consulta de produto Classificado products com o vendedor principal offers
Onde posso comprar isto? POST /v3/fetch/commerce/products/offers ID de produto, SKU ou ID da oferta representativa Vendedor offerselegível, com ofertas representativas em primeiro lugar
Quais são os detalhes do produto? POST /v3/fetch/commerce/products/details ID de produto ou SKU Zero ou um produto com nome, descrição e classificação agregada quando disponível

Os caminhos são relativos a https://api.microsoft.ai. Cada endpoint aceita um corpo JSON e uma chave API ou token Microsoft Entra ID ativado para Commerce; consulte Autenticação. Pode usar apenas a Pesquisa e chamar Ofertas ou Detalhes do Produto quando a experiência o precisar.

Ligar as chamadas

  1. Envie uma consulta de comprador concisa à Search e selecione um dos produtos devolvidos.
  2. Para Ofertas, envie todos os identificadores que o resultado tenham: o produto id como productId, is skuId como skuId, e o id da sua oferta representativa como offerId. Use os IDs do mesmo resultado. Pelo menos um é necessário.
  3. Para Detalhes do Produto, envie o produto id como productId, o seu skuId, ou ambos.
  4. Trate 200 OK com uma matriz products ou offers vazia como sem correspondência, não como um pedido falhado. Os pedidos de acompanhamento funcionam num produto, SKU ou oferta representativa de cada vez; estes endpoints não suportam IDs de lote nem paginação.

Trate os identificadores como cadeias opacas. Um resultado de pesquisa pode não conter todos os IDs: alguns produtos devolvem apenas um offer. Se apenas um ID de oferta estiver disponível, pode solicitar Ofertas mas não Detalhes do Produto. Não presuma que um ID se mantém válido ao longo do tempo, ou que um ID tem precedência quando envia vários IDs.

Escolha o mercado

Os três endpoints aceitam valores de dois caracteres language e region valores, com en e US como valores predefinidos; consulte Mercados suportados para as combinações disponíveis na pré-visualização privada. Pesquisa e Ofertas também aceitam um opcional location no formato lat:<latitude>;long:<longitude>, com latitude de -90 a 90 e longitude de -180 a 180. Detalhes do Produto não aceitam um location.

Use consistentemente o mercado escolhido pelo cliente em todas as chamadas. Envie a localização ou outro contexto pessoal apenas quando a sua aplicação estiver autorizada para isso. A cobertura do catálogo varia consoante o mercado.

Controlar o número de resultados

A pesquisa maxResults pesquisa 1 a 50 produtos, com um padrão de 10; não define o número de ofertas. Um conjunto de resultados mais pequeno pode ser útil quando envia resultados diretamente para um modelo. Um conjunto maior de candidatos pode ser útil quando a sua aplicação filtra ou classifica os resultados primeiro. A pesquisa pode devolver menos produtos do que os solicitados.

As ofertas não têm maxResults, offset nem cursor; o número de ofertas depende da disponibilidade. Detalhes do Produto devolve no máximo um produto.

Construir uma ferramenta para o agente

Uma abordagem é expor a Search como uma ferramenta e manter as definições de mercado em código de aplicação confiável. O seguinte é um esquema ilustrativo de ferramenta, não um endpoint 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 seu manipulador de ferramentas deve validar os argumentos do modelo, adicionar os language e region selecionados pelo utilizador e chamar Search com credenciais do lado do servidor. A pesquisa aceita uma consulta não em branco de até 1.000 caracteres. Para um pedido que envolva vários tipos distintos de produtos, considere uma chamada de Pesquisa separada por tipo e limite a concorrência e o volume de pedidos: cada chamada conta contra o limite de taxa e a quota do seu AppID.

Dê ao modelo uma seleção compacta dos campos devolvidos e mantenha os IDs de que necessita para chamadas de seguimento. Trate os títulos, descrições e outro texto devolvido do vendedor como dados não confiáveis, e não como instruções. Não deixe que um modelo gere URLs de compra ou afirme que existe um produto, preço ou classificação quando a API não o devolveu.

Filtrar, classificar e renderizar resultados

  1. Verifique as restrições rígidas no código da aplicação. Se o comprador especificar um preço máximo, condição, tamanho ou outros atributos, verifique os dados disponíveis da oferta antes de mostrar uma correspondência. Se um campo necessário estiver em falta ou não puder ser interpretado, não afirme que a restrição foi cumprida. A oferta specifications pode incluir atributos como marca ou tamanho, mas a disponibilidade e os valores variam.
  2. Classifique os candidatos. Comece pelo posicionamento do produto Search e depois aplique os critérios da sua aplicação. Se usar um modelo para reclassificar, envie-o apenas aos candidatos que pretende que considere e mantenha os dados estruturados originais para renderização.
  3. Compare o que é comparável. Para comparações com vendedores, verifique o produto e a variante, a moeda e o estado. Remova os IDs de ofertas repetidas antes de apresentar uma lista e verifique as ofertas antes de afirmar o preço mais baixo.
  4. Apresentar com base nos campos. Utilize a oferta name, seller.name, price, condition, shippingInfo e images[].url quando estiverem presentes. Para cada oferta que apresentar, inclua uma ligação para o seu clickUrl nessa resposta. Utilize displayUrl apenas para identificar o comerciante ou vendedor no ecrã, não como destino. Veja o link para as ofertas.
  5. Falha de forma controlada. Se um passo do modelo falhar, mostre os resultados estruturados disponíveis sem comentários gerados quando apropriado. Se um pedido de Comércio falhar, diga que os resultados não estão disponíveis e ofereça uma nova tentativa, em vez de inventar produtos ou preços.

Os Detalhes do Produto podem devolver um produto name, description e o rating agregado. A classificação é omitida quando não está disponível. Os seus value, scaleMin, scaleMax e count descrevem o produto, não uma oferta individual ou uma variante específica. Não infira o texto da avaliação ou um resumo da avaliação a partir da classificação agregada.

Para cada oferta que apresentar, utilize o seu clickUrl exatamente tal como foi devolvido nessa resposta para enviar um utilizador, ou um agente a atuar em nome do utilizador, para a oferta. Use displayUrl apenas para identificar o comerciante ou vendedor na sua exposiçã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 construa uma ligação.

Trate-os clickUrl como opacos: não os removam, reescrevam, truncem, descodifiquem ou substituam, não contornem os seus redirecionamentos e não os reutilizem para uma resposta, consulta, utilizador ou propósito diferente, incluindo através de uma cache. Para as regras completas, incluindo quando pode incluir A clickUrl no seu próprio link de rastreamento, consulte Links de Oferta e atribuição na referência de Comércio e no Anexo B dos Termos de Utilização do Web IQ.

Construir navegação em código, não no modelo

Mantenha cada original clickUrl em código de aplicação confiável, associado à sua oferta, resposta e utilizador. Envie ao modelo um identificador de oferta que a sua aplicação gere para essa resposta, juntamente com a informação relevante do produto. O modelo pode selecionar um identificador, mas não deve reproduzir nem modificar a ligação. Resolva o identificador com base na resposta original ao renderizar ou navegar, e rejeite identificadores desconhecidos ou obsoletos em vez de voltar a um URL gerado pelo modelo. Se um agente tiver de receber um clickUrl, certifique-se de que recebe e utiliza exatamente o valor original.

O seguinte exemplo do navegador cria uma ligação a partir de um objeto de oferta na resposta atual. Como política de aplicação conservadora, aceita apenas ligações HTTPS e rejeita valores que o parser de URL do navegador ou a serialização de links alteraria. Atribui a string original, não uma URL reconstruída. Quando devolver null, não apresente essa oferta. Pode executá-lo numa consola do navegador; a verificação final confirma que o URL está preservado e que os destinos em falta ou inseguros 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.");
}

Esta verificação não verifica redirecionamentos ou wrappers mais abaixo no caminho; teste o caminho de navegação completo na sua aplicação. Não utilize uma citação gerada pelo modelo, um link Markdown ou displayUrl como destino.

Formatar preços

listPrice, offeredPrice, e os montantes das prestações são números inteiros em unidades monetárias fracionárias da ISO 4217. USD usa dois dígitos decimais, por isso 39999 é USD 399,99; JPY usa zero. Utilize a própria escala de unidades menores da moeda, não uma divisão fixa por 100. offeredPrice recorre a listPrice quando não existe preço com desconto. Mostre um preço de lista como preço anterior apenas se for superior ao preço oferecido e se os termos aplicáveis o permitirem.

Por exemplo, este formatador JavaScript lida explicitamente com três moedas:

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, utilize uma tabela de unidades menores ISO 4217 mantida para cada moeda que a sua aplicação suporta, em vez de inferir a escala a partir dos Intl valores predefinidos de visualização. Não compare valores entre moedas sem uma política de conversão. Os preços e a disponibilidade mudam, por isso mostre-os com base na resposta atual.

Lidar com erros e limites de taxa

Os três endpoints utilizam os limites de taxa e a quota diária do seu AppID (15 consultas por segundo por predefinição), partilhados com as outras APIs Web IQ que o AppID chama. Os erros de taxa e quota retornam 429; verifique o errorCode e o retryAfter na resposta.

Resposta Ação recomendada
400, 401, 403, ou 415 Corrija a solicitação, as credenciais ou o acesso. Tentar novamente uma solicitação inalterada não ajuda.
429 AuthUserThrottled Espera pelo menos o tempo indicado em retryAfter, quando presente, depois tenta novamente com recuo exponencial limitado e jitter. Reduza a frequência dos pedidos.
429 AuthUserDailyUsageExceeded Não tente novamente; a quota diária reinicia-se às 00:00 UTC.
500 InternalServerError Siga qualquer retryAfter orientação e tente novamente com backoff limitado e jitter. Se persistirem falhas, contacte o Suporte Web IQ.

Para erros de Comércio, retryAfter é uma duração, como "60s", quando presente. Use um timeout e um orçamento global de retentativas. Registe o endpoint, estado, código de erro e traceId, e evite registar credenciais ou dados de compradores de que não precisa. Ver Gestão de erros.

Teste antes do lançamento

  • Construa um conjunto representativo de consultas de pesquisa dos compradores para as categorias e mercados que apoia.
  • Inspecione os resultados brutos da pesquisa antes de aplicar a sua própria filtragem e classificação e, em seguida, compare a experiência final.
  • Verifique uma amostra de produtos apresentados, links do vendedor, preços e condições em relação às páginas do vendedor antes de fazer reclamações sobre eles.
  • Verifique se a navegação do utilizador e agente utiliza exatamente clickUrl da resposta correspondente, incluindo através de qualquer wrapper seu, que os redirecionamentos são preservados e que os links não são reutilizados para outra resposta, consulta, utilizador ou finalidade.
  • Teste valores em falta ou inutilizáveis clickUrl e identificadores de ofertas gerados por modelo ou obsoletos, e certifique-se de que nenhum deles reverte para displayUrl ou para um link gerado.
  • Teste resultados vazios, campos em falta, produtos sem ID de produto nem SKU, timeouts, limitação, esgotamento de quotas e falhas no modelo.
  • Acompanhe o volume de solicitações, erros e IDs de rastreio. Inclua um ID de rastreamento relevante quando contactar o Suporte Web IQ.

Passos seguintes