Guia de início rápido

Configuração básica

Para usar a API Waze Ads Management (WAM, na sigla em inglês), siga as etapas no Google Cloud Platform (GCP) e em https://biz.world.waze.com.

Etapas no Google Cloud Platform: ativar a API

Veja a seguir as etapas para criar um projeto do GCP, ativar a API WAM e gerar uma chave de API:

  1. Ative a API para o projeto do GCP.

    Há duas maneiras de ativar a API WAM:

    • Console do Cloud: clique em Ativar no Console do Cloud.
    • Console da biblioteca de APIs: acesse o console da biblioteca de APIs e busque "Waze" na caixa de pesquisa. Clique no card da API Waze Ads Management v1 e, depois, em Ativar.
  2. Crie uma chave de API. Para fazer isso, acesse a página Credenciais e clique em Criar credenciais > Chave de API.
  3. Consulte a verificação de integridade, conforme abaixo, para saber se a chave de API está configurada corretamente: 
    curl -X GET https://ads.wazeapis.com/v1/health?key=API_KEY

    A consulta retorna o resultado a seguir:

    {"status": "SERVING"}

Autenticação

Para autenticar suas credenciais de login, você precisa receber um token de atualização uma vez e armazená-lo com segurança para usar no futuro.

  1. Acesse https://biz.world.waze.com/app/auth/refresh-token.
  2. Clique em Fazer login com o Google e siga as instruções para conectar contas existentes do Waze, se aplicável. Use a Conta do Google que será utilizada com a API Waze Ads.
  3. Clique em Receber token de atualização.
  4. Registre o REFRESH_TOKEN exibido na caixa de diálogo para uso futuro.

Depois de receber um REFRESH_TOKEN, conclua as duas etapas abaixo para conseguir o WAZE_ACCESS_TOKEN que você precisa informar com chamadas de API autenticadas.

  1. Faça a autenticação usando as credenciais do Google e receba um GOOGLE_ACCESS_TOKEN e um GOOGLE_ID_TOKEN. 
    curl -X POST https://accounts.google.com/o/oauth2/token \
  -d clientId=753715161699-kr9ss4meme166uo941r93hc6d6662nat.apps.googleusercontent.com \
  -d clientSecret=5ico_JLwqEg2EmDsWfzcYIA0 \
  -d refreshToken=REFRESH_TOKEN \
  -d grantType=refresh_token
  2. Use generateWazeAccessToken para conseguir um WAZE_ACCESS_TOKEN: 
    curl -X POST https://ads.wazeapis.com/v1/generateWazeAccessToken?key=API_KEY \
  -d '{
    googleAccessToken: "GOOGLE_ACCESS_TOKEN",
    googleIdToken: "GOOGLE_ID_TOKEN"
  }'

Informe o WAZE_ACCESS_TOKEN em um cabeçalho em todas as chamadas autenticadas. Para ver como fazer isso, consulte o seguinte exemplo de consulta de contas da lista.

Primeiras chamadas: consultas da conta

Agora que você concluiu as etapas preliminares, é hora de fazer sua primeira chamada à API WAM.

Exemplo de consulta para listar contas

Para fazer a primeira chamada, realize a seguinte consulta:

curl -X GET https://ads.wazeapis.com/v1/accounts?key=API_KEY \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN'

Essa consulta lista todas as contas a que suas credenciais do Google têm acesso. Ela retornará uma lista vazia, a menos que você já tenha criado contas no Painel de publicidade do Waze.

Criar uma conta

Para saber mais sobre os cincos principais recursos do Waze Ads e a ordem de configuração deles, leia o guia de criação e relação de recursos. Para criar uma conta, envie a seguinte solicitação:

curl -X POST https://ads.wazeapis.com/v1/accounts?key=API_KEY \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN' \
  -d '{
    type: "LOCAL_STARTER",
    title: "Test Account",
    state: "ACTIVE",
    category: "RESTAURANT",
    payment: {
      currencyCode: "USD",
      method: "INVOICE"
    },
    advertisingRegionCode: "US"
  }'

A amostra de código anterior retorna uma resposta que contém um name. Veja um exemplo da Account criada:

{
  "name": "accounts/1012345",
  "type": "LOCAL_STARTER",
  "createTime": "2020-08-14T12:14:23.11Z",
  "title": "Test Account",
  "state": "ACTIVE",
  "category": "RESTAURANT",
  "payment": {
    "currencyCode": "USD",
    "method": "INVOICE"
  },
  "advertisingRegionCode": "US"
}

Parabéns! Você fez suas primeiras chamadas à API Waze Ads Management. Para ver todos os parâmetros e valores de Account compatíveis, consulte a página de referência de Account.

Opcional: atualizar conta

A API cria recursos e corrige valores para possibilitar a atualização de recursos.

Um updateMask é especificado como um parâmetro. O valor dele é uma lista separada por vírgulas de caminhos de campo. Um caminho desse tipo é delimitado por . para um campo, codificado em uma string. Consulte FieldMask para mais informações. O payload consiste em um recurso parcial com os campos que você quer corrigir.

O exemplo a seguir atualiza title e category para uma instância Account.

curl -X PATCH https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID?key=API_KEY&updateMask=title,category \
  -H 'Authorization: Bearer WAZE_ACCESS_TOKEN'
  -d '{
    title: "Louisville Diner",
    category: "COFFEE_SHOP"
  }'

Próximas etapas

Veja na lista a seguir as próximas etapas e recomendações de leituras adicionais: