Offers API. Seu design, nossas ofertas.
Receba as ofertas de cada usuário em JSON, com imagens, etapas e recompensas já na sua moeda, e mostre-as nos seus próprios cards, ao lado do seu conteúdo. As recompensas chegam por postback, igual ao offerwall.
- JSONREST sobre HTTPS
- 600Requisições por minuto
- OpenAPIEspecificação incluída
curl -G "https://api.moonetix.com/v1/offers" \
-d user_id=user_1234 -d country=US -d device=android \
-H "Authorization: Bearer $MOONETIX_API_KEY"Entre no ar em três passos.
Copie o código, substitua os placeholders pelos valores do seu painel em Offerwalls, seu offerwall, Integration, e teste antes de lançar.
-
Peça as ofertas de um usuário
Chame a API a partir do seu servidor com a API key do seu app, o ID do usuário, o país onde o usuário está e o dispositivo ou user agent dele. A lista deixa de fora as ofertas que o usuário já concluiu ou que ainda não pode fazer de novo.
Terminalcurl -G "https://api.moonetix.com/v1/offers" \ -d user_id=user_1234 -d country=US -d device=android \ -H "Authorization: Bearer $MOONETIX_API_KEY"offers.php<?php $query = http_build_query([ 'user_id' => $userId, 'country' => $countryCode, 'ua' => $_SERVER['HTTP_USER_AGENT'] ?? '', ]); $ch = curl_init('https://api.moonetix.com/v1/offers?' . $query); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey], ]); $data = json_decode((string)curl_exec($ch), true);offers.jsconst params = new URLSearchParams({ user_id: userId, country: countryCode, ua: req.headers['user-agent'] || '', }); const res = await fetch(`https://api.moonetix.com/v1/offers?${params}`, { headers: { Authorization: `Bearer ${process.env.MOONETIX_API_KEY}` }, }); const data = await res.json();offers.pyimport os, requests r = requests.get( "https://api.moonetix.com/v1/offers", params={"user_id": user_id, "country": country_code, "ua": user_agent}, headers={"Authorization": f"Bearer {os.environ['MOONETIX_API_KEY']}"}, timeout=10, ) data = r.json() -
Mostre-as com o seu próprio design
Cada oferta vem com título, imagem, etapas e a recompensa na sua moeda. Exiba como quiser e envie o usuário para a start_url da oferta quando ele escolher uma. A página da oferta abre na Moonetix e, de lá, leva o usuário ao anunciante.
JSON{ "ok": true, "currency": "Coins", "offers": [ { "id": 58, "title": "Nova Quest: reach level 10", "reward": 975, "payout_usd": 1.5, "start_url": "https://wall.moonetix.com/..." } ] }offers.jsfor (const offer of data.offers) { list.append(card({ title: offer.title, reward: `${offer.reward} ${data.currency}`, href: offer.start_url, })); } -
Credite as recompensas com o postback
Cada recompensa chega ao seu servidor como um postback assinado. Verifique o hash, adicione a recompensa uma única vez por ID de transação e retire-a se um postback posterior a estornar. Postbacks com falha são reenviados até 5 vezes.
Painel, aba Postbackhttps://yoursite.com/postback?user={user_id}&tx={transaction_id}&status={status}&reward={reward}&hash={hash}postback.php<?php $tx = $_GET['tx'] ?? ''; $userId = $_GET['user'] ?? ''; $reward = $_GET['reward'] ?? ''; $status = $_GET['status'] ?? ''; $secret = getenv('MOONETIX_POSTBACK_SECRET'); $expected = hash_hmac('sha256', "$tx:$userId:$reward:$status", $secret); if (!hash_equals($expected, $_GET['hash'] ?? '')) { http_response_code(403); exit; } if ($status === '1') { credit_once($userId, $tx, $reward); // once per transaction ID } elseif ($status === '2') { reverse_if_credited($userId, $tx, $reward); } http_response_code(200);postback.jsconst crypto = require('crypto'); app.get('/postback', (req, res) => { const { tx, user, reward, status, hash } = req.query; const secret = process.env.MOONETIX_POSTBACK_SECRET; const expected = crypto.createHmac('sha256', secret) .update(`${tx}:${user}:${reward}:${status}`) .digest('hex'); const valid = typeof hash === 'string' && hash.length === expected.length && crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected)); if (!valid) return res.sendStatus(403); if (status === '1') creditOnce(user, tx, reward); // once per transaction ID if (status === '2') reverseIfCredited(user, tx, reward); res.sendStatus(200); });postback.pyimport hmac, hashlib, os from flask import request, abort @app.get("/postback") def postback(): a = request.args parts = [a.get(k, "") for k in ("tx", "user", "reward", "status")] msg = ":".join(parts) secret = os.environ["MOONETIX_POSTBACK_SECRET"].encode() expected = hmac.new(secret, msg.encode(), hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, a.get("hash", "")): abort(403) if a.get("status") == "1": credit_once(a["user"], a["tx"], a["reward"]) # once per transaction ID elif a.get("status") == "2": reverse_if_credited(a["user"], a["tx"], a["reward"]) return "", 200
{
"title": "Nova Quest: reach level 10",
"goals": [
{ "name": "Create an account", "reward": 325 },
{ "name": "Reach level 10", "reward": 650 }
],
"reward": 975,
"start_url": "https://wall.moonetix.com/..."
}
- Crie uma conta+325
- Chegue ao nível 10+650
Do JSON para o seu design
Cada oferta chega pronta para exibir, com as etapas e as recompensas já na sua moeda.
O que a API oferece
- Ofertas por usuário
As ofertas correspondem ao país e ao dispositivo que você envia, e as que o usuário já concluiu ficam de fora.
- Recompensas na sua moeda
Cada recompensa já vem calculada com a sua taxa de conversão, a divisão com o usuário, o arredondamento e qualquer bônus em andamento.
- Etapas e imagens
As ofertas de várias etapas listam cada etapa com a própria recompensa, para que você mostre exatamente o que paga.
- Sub IDs
Envie até cinco valores próprios. Eles são adicionados a cada start_url e voltam no postback.
- Ofertas ocultas continuam ocultas
As ofertas que você oculta na página Offers também ficam de fora da API, então ela corresponde ao seu offerwall.
- Especificação OpenAPI
Um openapi.json legível por máquina descreve cada campo, pronto para geradores de código e agentes de programação com IA.
Teste e depois lance.
Tudo o que você precisa verificar antes que usuários reais vejam o seu offerwall, com as ferramentas integradas ao seu painel.
Open as a test user
Em Integration status, na aba Integration, abra o seu offerwall como o usuário owner-test. Visitas de teste não são contadas como usuários.
Chame a API com curl
Peça a lista para um ID de usuário de teste e um país onde haja ofertas ativas, e abra uma start_url em um navegador.
Send a test postback
Escolha o usuário, o status e o pagamento, e veja exatamente o que o seu servidor respondeu, com o código de resposta e o tempo. Os IDs de transação de teste começam com test_.
Teste a partir de uma conexão normal
VPNs, proxies, Tor e redes de nuvem são bloqueados, então teste no Wi-Fi de casa ou nos dados móveis, em um país onde haja ofertas ativas.
Checklist de lançamento
0 de 10 prontos
Pronto para lançar. Seu progresso fica salvo neste navegador.
Erros comuns, resolvidos rápido.
O que pode aparecer enquanto você integra a Offers API, a causa e a solução.
400 invalid_countryUm parâmetro está ausente ou incorreto: invalid_user_id, invalid_country ou invalid_device.
SoluçãoCorrija o parâmetro indicado no código de erro.
401 invalid_api_keyA chave está ausente, incorreta ou foi substituída.
SoluçãoEnvie-a no header Authorization como Bearer e copie-a novamente na aba Integration.
403 app_not_liveO app está pausado, ou a sua conta não está aprovada ou ativa.
SoluçãoConfira suas notificações. Com user_blocked, não mostre ofertas a esse usuário.
429 rate_limitedMais de 600 requisições em um minuto para este app.
SoluçãoAguarde os segundos indicados em Retry-After e guarde em cache a lista de cada usuário por 1 a 5 minutos.
Empty offers listEsta é uma resposta normal: não há nada disponível para esse usuário no momento.
SoluçãoMostre um estado vazio amigável e confira o país e o dispositivo que você envia.
VPN detected on start_urlO usuário está em uma VPN, um proxy ou uma rede de nuvem quando a página da oferta abre.
SoluçãoPeça ao usuário para desativá-la. As requisições à API feitas pelo seu servidor não são verificadas.
Postback log shows 403 or 404O seu script rejeitou o postback, ou a URL está errada.
SoluçãoAbra a URL do log em um navegador e confira o seu código de hash.
Postback log shows a timeoutO seu script leva mais de 6 segundos para responder.
SoluçãoResponda primeiro com 200 e execute o trabalho demorado em segundo plano.
Postback log shows 301 or 302A sua URL redireciona, por exemplo de http para https.
SoluçãoUse a URL final. Os postbacks não seguem redirecionamentos.
Nenhum resultado. Veja a lista completa na documentação ou fale conosco.
Em resumo
- Endpoint
- GET https://api.moonetix.com/v1/offers
- Autenticação
- API key Bearer, uma por app, apenas no servidor
- Parâmetros obrigatórios
- user_id, country e device ou ua
- Limite de requisições
- Até 600 requisições por minuto para cada app
- Formato
- JSON, com uma descrição OpenAPI
- Preço
- Gratuito para publishers aprovados
Outras integrações
- SiteUm link, um iframe ou um botão Earn flutuante. Não precisa de SDK.
- Android SDKUma tela de offerwall nativa para apps em Kotlin e Java.
- iOS SDKUm offerwall nativo para Swift, SwiftUI e Objective-C.
- Unity SDKOfertas com recompensa para jogos Android e iOS, em C#.
- Flutter SDKUm plugin em Dart para Android e iOS.
- React Native SDKPara apps React Native e Expo, com tipos de TypeScript.
- Todas as integraçõesCompare lado a lado.
Perguntas sobre a Offers API
O que os desenvolvedores perguntam antes de adicionar a Offers API.
Travou em alguma coisa? Fale conosco
Quando devo usar a Offers API em vez do offerwall?
Use o link do offerwall para entrar no ar mais rápido. Use a Offers API quando quiser as ofertas dentro do seu próprio site ou app, com o seu próprio design, por exemplo ao lado de ofertas de outras fontes ou na sua própria loja de recompensas.
Posso chamar a Offers API de um navegador ou de um app mobile?
Não. Chame-a apenas a partir do seu servidor, porque a requisição leva a sua API key. Se a chave vazar, crie uma nova na aba Integration e a antiga para de funcionar na hora.
Qual país devo enviar?
O país onde o usuário realmente está, como um código de duas letras, por exemplo US. As ofertas e as recompensas dependem dele, e o país e o dispositivo são verificados de novo quando o usuário inicia uma oferta.
As recompensas são diferentes das do offerwall?
Não. A API retorna as mesmas ofertas do seu offerwall, com as mesmas recompensas, e cada etapa concluída chega ao seu servidor pelo mesmo postback assinado.
Existe um limite de requisições?
Sim, até 600 requisições por minuto para cada app. Guarde a lista em cache por pouco tempo para cada usuário se você a exibe com frequência.
A mesma chave serve para mais alguma coisa?
Sim. A API key de um app também funciona para a Reporting API e para as sessões dos SDKs mobile.
Transforme o seu tráfego em ganhos.
Crie uma conta de publisher gratuita e ganhe com cada oferta que seus usuários concluírem no seu site, app, jogo ou comunidade.