Overview

Investimento em mídia paga, auditável, por cliente.

owiew: API de leitura 1.0.0

API de LEITURA do owiew. Ela devolve o que as plataformas de anúncio reportaram, exatamente como reportaram, com a trilha de quando cada número foi observado.

Antes de escrever uma linha de código, quatro coisas

1. Dinheiro está em micros. Todo campo terminado em _micros é um inteiro em que 1.000.000 vale uma unidade da moeda. Divida por 1.000.000, com aritmética inteira. Tratar micros como centavos infla tudo dez mil vezes, e o erro é grande demais para passar despercebido — o perigoso é o inverso, quem divide por 1.000.000 em ponto flutuante e perde um centavo por linha.

2. Conversões TAMBÉM estão em micros. conversions_micros: 75000000 são 75 conversões, não 75 milhões. A plataforma reporta conversão fracionária por causa de atribuição parcial, e é por isso que o campo não é inteiro.

3. Métrica derivada não vem pronta, e é de propósito. CPA, CPC, CTR e ROAS são calculados a partir dos totais somados — nunca pela média das linhas. Enviá-los prontos convidaria a somá-los, e somar razões é errado.

4. O mesmo número pode ser reescrito depois. As plataformas revisam dado já reportado por dias. Se você guarda histórico, reconcilie por /audit/revisions — sem isso o seu banco diverge do nosso em silêncio.

Autenticação, em dois passos

1. Troque a chave por um token. A chave começa com adv_ e vai no cabeçalho — nunca no corpo, nunca na URL:

curl -s -X POST https://dash.owiew.com/v1/token \
  -H "Authorization: Bearer $CHAVE_DE_API"

2. Use o token nas leituras. Ele é assinado, dura dois minutos e é escopado a um cliente e a um conjunto de contas. Renove quando expirar — não guarde, e não tente adivinhar quando falta pouco: a resposta traz expires_at.

A vida curta é intencional. É o que permite revogar um acesso sem manter lista de revogação, e o que faz cada leitura ser verificada por assinatura, sem consultar banco nenhum.

O que a chave nunca pode fazer

Escrever. O papel é restrito a viewer e analyst — os dois únicos que não concedem execução na plataforma de anúncio nem reescrita da classificação do relatório. A restrição é imposta pelo servidor, na criação da chave e de novo na emissão do token.

Não é excesso de zelo: a permissão de execução gasta dinheiro real, e as três barreiras que a protegem (interruptor por cliente, confirmação na tela, trilha imutável) foram desenhadas para uma pessoa que decide. Uma chave no arquivo de configuração de um servidor de terceiro não passa por nenhuma.

Prazo e rotação

Toda chave expira — não existe opção “nunca”. O padrão é 90 dias e o teto é 365. Quando ela vence, a troca passa a responder 401 e a integração para: é uma falha visível e reversível, em vez de uma porta que ninguém lembra de fechar.

Isolamento

O cliente vem sempre do CAMINHO (/v1/t/{tenantID}/...) e é conferido contra o token. Não há cabeçalho nem cookie que troque de cliente. Um token usado num caminho de outro cliente recebe 403 — nunca uma resposta vazia, que seria indistinguível de ‘não há dados’.

owiew

https://owiew.com

Information

OpenAPI version: 3.1.0

Authentication

chaveDeAPI

A credencial de MÁQUINA, criada por quem administra o cliente. Vale só em POST /v1/token — ela não abre nenhuma rota de leitura diretamente, e é isso que permite à API verificar cada requisição por assinatura, sem consultar banco.

Security scheme type: http

Bearer format: adv_...

tokenDeAcesso

Token de acesso assinado, com dois minutos de validade, escopado a um cliente e a um conjunto de contas. Obtido em POST /v1/token.