Enviar Mensagens de Transação para o Microsoft Advertising

  • Artigo

Antes de enviar uma mensagem de transação:

  • Valide a mensagem para garantir que está em conformidade com o XSD de Transação. Isto irá poupar-lhe percursos de ida e volta e tempo a ter de corrigir erros.

  • Certifique-se de que a mensagem contém menos de 100 MB de dados não comprimidos ou 10 MB de dados comprimidos (com compressão GZip). Para reduzir o tráfego de rede, deve sempre enviar dados comprimidos.

  • Certifique-se de que tem menos de cinco pedidos em fila ou que está a ser processado. A sua aplicação deve incluir a lógica necessária para se manter dentro do limite. Se exceder o limite, o pedido falhará com o código de estado HTTP 429.

Depois de validar a mensagem, envie-a para a Microsoft no corpo de um pedido HTTPS POST. O URL para o qual envia o pedido é:

https://hotels.api.bingads.microsoft.com/api/customers/<customerId>/transactions

Defina <customerId> para o ID de cliente do anunciante.

O pedido tem de incluir os seguintes cabeçalhos:

  • Content-Type: application/xml; charset=utf-8
  • Autorização: Accesstokengoeshere do Portador <>

Para obter detalhes sobre como obter um token de acesso OAuth, veja Introdução na API do Hotel.

Também pode especificar os seguintes cabeçalhos opcionais:

  • Codificação de Conteúdo: gzip
    Especifique este cabeçalho se comprimir a mensagem de transação (recomendado).

  • X-Transaction-ID: <ID definido pelo utilizador>
    Um ID opaco definido pelo utilizador que os anunciantes utilizam para identificar exclusivamente a mensagem. Se incluir este cabeçalho, o ID tem de corresponder ao ID no atributo do id elemento Transaction.

Segue-se um pedido POST de exemplo.

POST https://hotels.api.bingads.microsoft.com/api/customers/abc123/transactions HTTP/1.1
Content-Type: application/xml; charset=utf-8
Host: hotels.api.bingads.microsoft.com

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-05-25T20:44:56-04:00" id="de0be689-d094-406e-
8027-724309deb373">
  <Result>
    <Property>13579</Property>
    <Checkin>2017-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">159.99</Baserate>
    <Tax currency="USD">20.00</Tax>
    <OtherFees currency="USD">4.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="mobile"/>
      <PointOfSale id="desktop"/>
    </AllowablePointsOfSale>
  </Result>
</Transaction>

O pedido POST coloca a mensagem numa fila a processar e, em seguida, devolve. Pode ter um máximo de cinco pedidos em fila ou a ser processados ao mesmo tempo. Se exceder o limite, o pedido falha com 429.

Para determinar se a Microsoft processou a mensagem com êxito, consulte Hotel Price Ads Feed Status (Estado do Feed de Anúncios de Preços do Hotel) na aplicação Web Microsoft Hotel Center of Microsoft Advertising (Centro Hoteleiro da Microsoft Advertising).

Se o pedido for bem-sucedido (a mensagem for colocada com êxito na fila), o corpo da resposta inclui um documento XML que especifica o número de bytes lidos (BytesReceived) do corpo do pedido (a mensagem de transação).

<TxnResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Microsoft.BingAds.BHAC.HotelAdsAPIs.Models">
  <BytesReceived>184381</BytesReceived>
  <FeedId>6165579</FeedId>
</TxnResponse>

O FeedId elemento contém um ID gerado pela Microsoft que identifica exclusivamente o feed. O relatório de estado da transação inclui este ID.

Se o pedido falhar, o corpo da resposta incluirá um documento XML que contém uma lista de códigos de erro e mensagens que identificam o motivo da falha do pedido. Para obter uma lista de códigos de erro e mensagens, consulte Códigos de Erro e Mensagens.

A resposta inclui o cabeçalho de resposta WebRequestActivityId. O cabeçalho contém o ID associado ao pedido nos ficheiros de registo. Sempre que um pedido falhar, capture o ID. Se não conseguir resolver o problema, indique este ID quando contactar o Suporte.

Com que frequência preciso de enviar mensagens

Enviar mensagens de transação sempre que os preços e a disponibilidade forem alterados.