API REST

Tudo o que o painel faz, por HTTPS com uma chave de API.

Autenticação

Crie uma chave em Configurações → API keys e envie como token Bearer. As chaves aparecem uma única vez.

curl https://api.adjoin.dev/v1/me \
  -H "Authorization: Bearer adj_live_…"

read: Requisições GET.
write: Criar e alterar campanhas, sites e placements.
conversions: Só os endpoints de conversão servidor a servidor.

Uma chave nunca é admin e não pode criar chaves nem pedir saques — isso exige uma pessoa logada.

Valores são sempre inteiros em micros: 1 USD = 1.000.000.

Endpoints

GET /v1/me: De quem é a chave.
GET /v1/campaigns: Suas campanhas com status, lance, orçamento e gasto.
POST /v1/campaigns: Cria uma campanha; começa em revisão. O orçamento é reservado do saldo pré-pago.
POST /v1/campaigns/plan: Lance inicial, previsão de alcance e reserva para um orçamento, antes de se comprometer.
GET /v1/refunds?campaign_id=cmp_…: Cliques que filtramos e não cobramos, com o motivo.
POST /v1/conversions/s2s: Confirma uma conversão pelo seu servidor.
POST /v1/conversions/s2s/refund: Estorna um pedido dentro do prazo de devolução.
GET /v1/sites · POST /v1/sites: Seus sites; registra um domínio.
POST /v1/sites/{site_id}/verify: Verifica a posse do domínio (DNS TXT, arquivo ou meta tag).
GET /v1/placements?site_id= · POST /v1/placements: Espaços de um site; cria um.
GET /v1/placements/{placement_id}/live: Se um espaço recebeu requisições nas últimas 24 horas.
GET /v1/boost · POST /v1/boost: Status do Launch Day Boost; aplicar a uma campanha.
GET /v1/credits: Saldo de crédito de promoção cruzada e atividade recente.
GET /v1/segments: Rótulos de audiência definidos pelos publishers, com pageviews de 7 dias (só 100+). Use em target_segments / exclude_segments ao criar uma campanha.

Criar uma campanha

pricing_model é cpc, cpm, cpa, affiliate, guaranteed ou cross_promo (pago em crédito, sem orçamento em dinheiro). Um 402 significa saldo disponível insuficiente.

curl -X POST https://api.adjoin.dev/v1/campaigns \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{
    "name": "Launch",
    "pricing_model": "cpc",
    "bid_micros": 300000,
    "total_budget_micros": 50000000,
    "daily_cap_micros": 5000000,
    "target_categories": ["devtools"],
    "creatives": [{ "headline": "Ship faster", "body": "…", "cta": "Try it",
                    "landing_url": "https://myapp.dev", "format": "card" }]
  }'

Conversões servidor a servidor

Mude a origem de conversão da campanha para s2s e confirme pedidos pelo seu servidor com uma chave de escopo conversions. O pixel deixa de cobrar essa campanha, então um pedido nunca é cobrado pelos dois caminhos. Cliques podem ser confirmados por 7 dias.

# the ad click lands on https://myapp.dev/?aj_t=… — keep aj_t with the order
curl -X POST https://api.adjoin.dev/v1/conversions/s2s \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{ "click_token": "<aj_t>", "order_id": "order_1234", "value_micros": 29000000 }'

# a return or cancellation, inside the return window
curl -X POST https://api.adjoin.dev/v1/conversions/s2s/refund \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{ "campaign_id": "cmp_…", "order_id": "order_1234" }'

Erros

Erros são JSON com um campo detail. 401: chave ausente ou inválida. 403: falta o escopo. Objetos de outras contas também retornam 404, sem revelar que existem.

Dúvidas: [email protected]