Pular para o conteúdo
owiew developers

Início rápido

Objetivo: obter um token a partir da sua chave de API e ler as campanhas do último mês com curl.

O que você precisa

Seção intitulada “O que você precisa”
  • Uma chave de API do seu cliente na owiew. Ela hoje começa com adv_ (veja Autenticação) e aparece uma única vez, no momento da criação. Hoje a chave é emitida a pedido: peça ao suporte da owiew, informando o nome da integração, o papel de leitura e, se quiser limitar, as contas de anúncio que ela deve enxergar. Guarde o valor num gerenciador de segredos.
  • curl e jq instalados.

Nos comandos abaixo a chave fica numa variável de ambiente. Nunca a escreva no código nem na URL.

Passos

Seção intitulada “Passos”

  1. Defina as variáveis de ambiente.

    Janela do terminal
    export OWIEW_API_URL="https://dash.owiew.com"
    export OWIEW_API_KEY="cole-aqui-a-sua-chave"

  2. Troque a chave por um token. A chave vai no cabeçalho Authorization, nunca no corpo nem na URL.

    Janela do terminal
    curl -sS -X POST "$OWIEW_API_URL/v1/token" \
      -H "Authorization: Bearer $OWIEW_API_KEY" > token.json

  3. Guarde o token e o identificador do cliente.

    Janela do terminal
    export OWIEW_TOKEN=$(jq -r .access_token token.json)
    export OWIEW_TENANT_ID=$(jq -r .tenant_id token.json)

    O token vale dois minutos. Se passar disso antes da próxima chamada, repita os passos 2 e 3.

  4. Peça as campanhas de um período.

    Janela do terminal
    curl -sS "$OWIEW_API_URL/v1/t/$OWIEW_TENANT_ID/campaigns?since=2026-09-01&until=2026-09-30" \
      -H "Authorization: Bearer $OWIEW_TOKEN"

  5. Leia o resultado de forma legível.

    Janela do terminal
    curl -sS "$OWIEW_API_URL/v1/t/$OWIEW_TENANT_ID/campaigns?since=2026-09-01&until=2026-09-30" \
      -H "Authorization: Bearer $OWIEW_TOKEN" \
      | jq -r '.campaigns[] | [.campaign_name, .currency, .spend_micros, .conversions_micros] | @tsv'

Resultado esperado

Seção intitulada “Resultado esperado”

O passo 2 devolve um JSON parecido com este (valores de exemplo):

{
  "access_token": "TOKEN_DE_EXEMPLO",
  "expires_at": "2026-10-28T12:02:00Z",
  "tenant_id": "ID_DO_CLIENTE_EXEMPLO",
  "tenant_slug": "cliente-exemplo",
  "tenant_name": "Cliente Exemplo",
  "role": "viewer",
  "permissions": ["insights.read", "account.read"],
  "accounts": ["*"],
  "display_currency": "BRL"
}

O passo 4 devolve o período consultado e uma lista de campanhas (valores de exemplo):

{
  "since": "2026-09-01",
  "until": "2026-09-30",
  "campaigns": [
    {
      "campaign_id": "120000000000001",
      "campaign_name": "Marca - Busca",
      "account_id": "conta-exemplo-1",
      "provider": "meta",
      "days": 30,
      "budget_kind": "daily",
      "spend_micros": 1500000000,
      "impressions": 100000,
      "clicks": 2000,
      "conversions_micros": 75000000,
      "conversion_value_micros": 6000000000,
      "currency": "BRL",
      "revisions": 0
    }
  ]
}

Leia assim: spend_micros: 1500000000 são 1.500,00 na moeda BRL, e conversions_micros: 75000000 são 75 conversões. As duas grandezas estão em micros. Detalhes em Unidades e tipos.

Se algo der errado

Seção intitulada “Se algo der errado”
  • 401 no passo 2: a chave está errada, vencida ou foi revogada. A resposta não distingue os casos. Confira se o valor está completo e se não ficou com espaço ou aspas.
  • 401 no passo 4: o token venceu. Refaça os passos 2 e 3.
  • 403 no passo 4: o identificador do cliente no caminho não é o do token, ou a chave não tem a permissão da rota. Use o tenant_id devolvido pela troca.
  • 400 com INVALID_WINDOW: as datas estão fora do formato AAAA-MM-DD, invertidas ou além do máximo de 400 dias.

Mais códigos em Erros.

Próximos passos

Seção intitulada “Próximos passos”