A API da RevRake.

URLs base

A API tem quatro endpoints assinados para a plataforma do operador, dois de escrita e dois de leitura, e o link de rastreamento que os visitantes abrem. Os endpoints assinados também estão publicados em um arquivo OpenAPI 3.1.

Os portais em app.revrake.com usam seus próprios endpoints, atrás de uma sessão autenticada. Eles não são uma API pública e podem mudar sem aviso. Os relatórios, o livro-razão e as linhas de pagamento também podem ser baixados ali em CSV.

Chaves

Há dois tipos de chave. Cada uma tem um ID de chave e um segredo, e todas assinam as requisições da mesma forma. As chaves nunca são compartilhadas: cada parte tem a sua.

• Uma nova chave revoga a antiga imediatamente, nos dois tipos. Um afiliado também pode revogar sua chave e ficar sem nenhuma.
• Uma chave de afiliado só funciona enquanto o afiliado está aprovado no programa. Caso contrário, uma leitura responde 403 affiliate_inactive.
• Com uma chave de afiliado, o parâmetro affiliate é ignorado e by=affiliate é respondido por dia.
• O limite de taxa das leituras é contado por chave.

Autenticação

Toda requisição a /v1 é assinada com uma chave. Cada requisição leva três cabeçalhos:

Para assinar uma requisição:

1. Monte o corpo e guarde os bytes exatos que você vai enviar.
2. Pegue o horário Unix atual em segundos, como texto decimal.
3. Concatene o timestamp, um ponto (.) e o corpo.
4. Calcule o HMAC-SHA256 desse texto com o seu segredo e escreva-o em hexadecimal minúsculo.
5. Envie o corpo sem alterações, com os três cabeçalhos.

Como assinar uma leitura

Um GET não tem corpo, então a assinatura cobre o alvo da requisição: o caminho e a query exatamente como enviados, por exemplo 1790000000./v1/reports?by=link&days=7. Sem query, é o timestamp, um ponto e o caminho. Monte o endereço uma vez, assine esse texto e envie esse texto: um cliente que reordena ou recodifica a query depois de assinar quebra a assinatura.

• Primeiro verifica-se a chave, depois o timestamp, depois a assinatura.
• O cabeçalho Content-Type não é obrigatório. Envie application/json para eventos e text/csv para arquivos.
• Uma chave rotacionada para de funcionar imediatamente.

Exemplos de assinatura

Cada exemplo tem uma única função de assinatura, envia um cadastro e depois lê um relatório. Substitua o ID da chave e o segredo pelos seus.

KEY="pb_your_key_id"
SECRET="your_secret"
BASE="https://app.revrake.com"

# sign <payload>: hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret
sign() { printf '%s.%s' "$TS" "$1" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //'; }

# Write: the payload is the body.
TS=$(date +%s)
BODY='{"type":"registration","player_id":"PLR-1001","click_id":"CID_FROM_LANDING_URL"}'
curl -X POST "$BASE/v1/postback" \
  -H "Content-Type: application/json" \
  -H "X-RevRake-Key: $KEY" \
  -H "X-RevRake-Timestamp: $TS" \
  -H "X-RevRake-Signature: $(sign "$BODY")" \
  -d "$BODY"

# Read: the payload is the path and the query, exactly as sent.
TS=$(date +%s)
TARGET='/v1/reports?by=link&days=7'
curl "$BASE$TARGET" \
  -H "X-RevRake-Key: $KEY" \
  -H "X-RevRake-Timestamp: $TS" \
  -H "X-RevRake-Signature: $(sign "$TARGET")"

import { createHmac } from 'node:crypto';

const KEY = 'pb_your_key_id';
const SECRET = 'your_secret';
const BASE = 'https://app.revrake.com';

// hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret
function sign(secret, timestamp, payload) {
  return createHmac('sha256', secret).update(`${timestamp}.${payload}`).digest('hex');
}

function headers(payload) {
  const ts = Math.floor(Date.now() / 1000).toString();
  return { 'X-RevRake-Key': KEY, 'X-RevRake-Timestamp': ts, 'X-RevRake-Signature': sign(SECRET, ts, payload) };
}

// Write: the payload is the body. Send the same string you signed.
const body = JSON.stringify({ type: 'registration', player_id: 'PLR-1001', click_id: 'CID_FROM_LANDING_URL' });
const write = await fetch(`${BASE}/v1/postback`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', ...headers(body) },
  body,
});
console.log(write.status, await write.json());

// Read: the payload is the path and the query, exactly as sent.
const target = '/v1/reports?by=link&days=7';
const read = await fetch(BASE + target, { headers: headers(target) });
console.log(read.status, await read.json());

import hashlib
import hmac
import json
import time
import urllib.error
import urllib.request

KEY = "pb_your_key_id"
SECRET = "your_secret"
BASE = "https://app.revrake.com"


def sign(secret: str, timestamp: str, payload: bytes) -> str:
    """hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret"""
    return hmac.new(secret.encode(), timestamp.encode() + b"." + payload, hashlib.sha256).hexdigest()


def call(method: str, target: str, body: bytes | None = None):
    ts = str(int(time.time()))
    # Write: the payload is the body. Read: the path and the query, as sent.
    payload = body if body is not None else target.encode()
    headers = {"X-RevRake-Key": KEY, "X-RevRake-Timestamp": ts, "X-RevRake-Signature": sign(SECRET, ts, payload)}
    if body is not None:
        headers["Content-Type"] = "application/json"
    req = urllib.request.Request(BASE + target, data=body, method=method, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=10) as res:
            return res.status, json.load(res)
    except urllib.error.HTTPError as e:
        return e.code, json.load(e)


event = {"type": "registration", "player_id": "PLR-1001", "click_id": "CID_FROM_LANDING_URL"}
print(*call("POST", "/v1/postback", json.dumps(event).encode()))
print(*call("GET", "/v1/reports?by=link&days=7"))

<?php
const KEY = 'pb_your_key_id';
const SECRET = 'your_secret';
const BASE = 'https://app.revrake.com';

// hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret
function sign(string $secret, string $timestamp, string $payload): string
{
    return hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
}

function call(string $method, string $target, ?string $body = null): array
{
    $ts = (string) time();
    // Write: the payload is the body. Read: the path and the query, as sent.
    $payload = $body ?? $target;
    $headers = [
        'X-RevRake-Key: ' . KEY,
        'X-RevRake-Timestamp: ' . $ts,
        'X-RevRake-Signature: ' . sign(SECRET, $ts, $payload),
    ];
    $ch = curl_init(BASE . $target);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10]);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $answer = curl_exec($ch);
    return [curl_getinfo($ch, CURLINFO_RESPONSE_CODE), json_decode($answer, true)];
}

$event = ['type' => 'registration', 'player_id' => 'PLR-1001', 'click_id' => 'CID_FROM_LANDING_URL'];
print_r(call('POST', '/v1/postback', json_encode($event)));
print_r(call('GET', '/v1/reports?by=link&days=7'));

package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"net/http"
	"strconv"
	"time"
)

const (
	key    = "pb_your_key_id"
	secret = "your_secret"
	base   = "https://app.revrake.com"
)

// sign is the hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret.
func sign(secret, timestamp string, payload []byte) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(payload)
	return hex.EncodeToString(mac.Sum(nil))
}

func call(method, target string, body []byte) (int, string, error) {
	ts := strconv.FormatInt(time.Now().Unix(), 10)
	// Write: the payload is the body. Read: the path and the query, as sent.
	payload := body
	if body == nil {
		payload = []byte(target)
	}
	req, err := http.NewRequest(method, base+target, bytes.NewReader(body))
	if err != nil {
		return 0, "", err
	}
	req.Header.Set("X-RevRake-Key", key)
	req.Header.Set("X-RevRake-Timestamp", ts)
	req.Header.Set("X-RevRake-Signature", sign(secret, ts, payload))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	res, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
	if err != nil {
		return 0, "", err
	}
	defer res.Body.Close()
	answer, err := io.ReadAll(res.Body)
	return res.StatusCode, string(answer), err
}

func main() {
	event := []byte(`{"type":"registration","player_id":"PLR-1001","click_id":"CID_FROM_LANDING_URL"}`)
	fmt.Println(call("POST", "/v1/postback", event))
	fmt.Println(call("GET", "/v1/reports?by=link&days=7", nil))
}

Vetor de teste

Com estas entradas, seu código deve produzir exatamente estas assinaturas:

Segredo

test_secret

Timestamp

1791072000

Corpo

{"type":"registration","player_id":"PLR-1001","btag":"1001_1"}

Assinatura

115d8c73c6069d8953a36ca3a68c114da6232e4ba31889fd519d41ab1350a603

Alvo da requisição de uma leitura

/v1/reports?by=link&days=7

Assinatura da leitura

ed1ed72dd7ddef22c762f63b8919011e7c36c7214b55b72693c5927fb4b911d0

Limites

Estes são todos os limites que o produto aplica hoje a integrações, rastreamento e afiliados, com seus números. Login, redefinição de senha e candidaturas também têm limites contra abuso.

Os dois endpoints de escrita, POST /v1/postback e POST /v1/files, têm limite por chave (veja a tabela). Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining; uma recusa é 429 com Retry-After. Envie no ritmo dos seus eventos e use lotes para uma carga retroativa. O link de rastreamento não tem limite de taxa; uma rajada incomum de cliques em um link a partir de um mesmo endereço gera um alerta de fraude e ainda é redirecionada.

O limite de taxa das leituras

• Cada chave pode fazer 120 leituras por minuto. A cota é um balde de 120: uma leitura consome uma unidade, e uma unidade volta a cada meio segundo. Uma chave que ficou parada pode fazer 120 leituras de uma vez; depois disso, duas por segundo.
• Toda resposta de leitura traz X-RateLimit-Limit (sempre 120) e X-RateLimit-Remaining (quantas leituras restam neste momento).
• Acima do limite, a resposta é 429 rate_limited com um cabeçalho Retry-After: os segundos a esperar. Espere e envie a mesma requisição de novo, assinada com um timestamp novo.
• O limite é contado por chave: a chave do operador e a chave de cada afiliado têm sua própria cota.

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 1

{"error":"rate_limited","message":"Too many requests: at most 120 reads a minute per key. One more is allowed every half second; wait the seconds in Retry-After and try again."}

Como tratar um 429

// read(target) signs one GET with a fresh timestamp and sends it,
// as in the signing samples.
async function readWithRetry(target, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await read(target);
    if (res.status !== 429) return res;
    const seconds = Number(res.headers.get('Retry-After')) || 1;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
  throw new Error('still rate limited after ' + tries + ' tries');
}

POST /v1/postback

Informa um evento da plataforma do operador. O corpo é um objeto JSON com um type e os campos desse tipo, ou um array JSON desses objetos (um lote).

POST https://app.revrake.com/v1/postback

• type é um destes: registration, deposit, chargeback, ngr.
• Um campo que não esteja listado para o tipo é recusado com 422, então um erro de digitação nunca é ignorado em silêncio.
• ts é o horário do evento no formato RFC 3339 (2026-10-04T08:15:00Z). Se for omitido, usa-se o horário da requisição. Ele precisa trazer um deslocamento UTC (Z ou +03:00); um horário sem deslocamento é recusado. Ele não pode estar mais de um dia no futuro.
• Um valor é um decimal, como texto JSON ou número JSON: "25.00" ou 25.5. Sem separador de milhar, sem expoente e sem mais casas decimais do que a moeda tem.
• currency é um código ISO 4217 de três letras. Minúsculas são aceitas. Se for omitido, usa-se a moeda de relatório do workspace.
• Os espaços no início e no fim dos valores de texto são removidos, exceto em click_id e btag: envie-os exatamente como chegaram à landing page.

registration

Um novo jogador. Envie click_id, btag, promo_code, ou vários deles; sem nenhum, o jogador é registrado como não atribuído. O jogador é atribuído uma única vez, aqui. Resposta: attribution.

{"type":"registration","player_id":"PLR-1001","click_id":"01K6QF3M8Z5T7W9XB2C4D6E8GH","btag":"1001_1"}

{
  "status": "accepted",
  "event_type": "registration",
  "event_id": "0199b2c4-6f1e-7a53-9d0c-2b8f4e1a7c33",
  "attribution": {
    "attributed": true,
    "reason": "click",
    "affiliate_number": 1001,
    "link_number": 1,
    "click_id": "01K6QF3M8Z5T7W9XB2C4D6E8GH",
    "policy_version": 1,
    "window_days": 30,
    "model": "last_click"
  }
}

deposit

Envie um evento deposit para cada depósito, com seu ID de transação em txn_id. O deal define se o mínimo para CPA é comparado ao primeiro depósito ou aos depósitos acumulados, descontados os chargebacks. A qualificação cria uma comissão CPA por jogador, em retenção.

{"type":"deposit","player_id":"PLR-1001","txn_id":"TX-88213","amount":"25.00","currency":"KES","first":true}

{
  "status": "accepted",
  "event_type": "deposit",
  "event_id": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
  "commission": {
    "effect": "created",
    "type": "cpa",
    "amount_minor": 4000,
    "status": "hold"
  }
}

chargeback

Envie um evento chargeback com seu próprio txn_id e o txn_id do depósito original em ref_txn_id. Ele reverte o depósito inteiro. No CPA acumulado, a comissão só é retirada se o total qualificado restante ficar abaixo do mínimo: uma comissão em retenção é cancelada; uma aprovada ou paga recebe uma linha de estorno.

{"type":"chargeback","txn_id":"CB-5001","ref_txn_id":"TX-88213"}

{
  "status": "accepted",
  "event_type": "chargeback",
  "event_id": "0199cc10-7b2d-7c41-a3f0-5d2e8b9c1f47",
  "commission": {
    "effect": "cancelled",
    "type": "cpa",
    "amount_minor": 4000,
    "status": "rejected"
  }
}

ngr

A receita líquida de jogo (NGR) de um jogador em um dia ou em um mês. Ela rende o RevShare da versão do deal em vigor no fim do período, em retenção. O jogador precisa estar cadastrado. Resposta: commission.

{"type":"ngr","player_id":"PLR-1001","period":"2026-10-03","amount":"118.40","currency":"KES"}

{
  "status": "accepted",
  "event_type": "ngr",
  "event_id": "0199b2d1-5c0e-7b42-8a17-3e9d6f0c4b21",
  "commission": {
    "effect": "created",
    "type": "revshare",
    "amount_minor": 2960,
    "status": "hold"
  }
}

A resposta

Um evento que foi gravado, ou que já estava gravado, é respondido com 200 e um objeto JSON. Os campos que não se aplicam são omitidos.

{
  "status": "accepted",
  "event_type": "deposit",
  "event_id": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
  "waiting_for_player": true
}

{
  "status": "duplicate",
  "event_type": "deposit",
  "event_id": "0199b31f-8c02-7a66-b4e1-2d7f9a3c6e15",
  "duplicate_of": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
  "detail": "The same deposit (TX-88213) was already reported through the API; this one adds nothing."
}

{
  "status": "duplicate",
  "event_type": "deposit",
  "event_id": "0199b2ca-11d4-7f09-8c55-0a6e2d4b7f90",
  "commission": { "effect": "none", "reason": "not_first" }
}

Uma comissão é criada com o status hold. Ela é aprovada automaticamente quando o período de retenção do deal termina, a menos que algo ainda a retenha: um alerta de fraude aberto, um afiliado que não está aprovado ou uma taxa de câmbio ausente.

Motivos de atribuição

Primeiro tenta-se o click ID. Se ele não é um dos seus, tenta-se o btag. Quando a política diz que o btag vale e o btag corresponde a um link, o btag é tentado primeiro. Um btag que corresponde a um link atribui o jogador mesmo quando nenhum clique é encontrado. Um código promocional é tentado por último, só quando nem o click ID nem o btag atribuíram o jogador. A política, a janela e qual dos dois vale são definidas na página Integração; cada mudança é uma nova versão. Quando a política diz que vale o código promocional, um código que corresponde a um link é tentado antes dos dois, e um que não corresponde volta para eles. Um acordo pode definir sua própria janela, que substitui a da política para cliques nos links dos seus afiliados.

Por que nenhuma comissão foi criada

Lotes

O corpo pode ser um array JSON de 1 a 1.000 eventos, enviado ao mesmo endpoint com os mesmos cabeçalhos. A assinatura cobre o array inteiro. Os eventos são tratados em ordem, cada um separadamente, então um evento recusado nunca interrompe os demais.

Um lote que pôde ser lido é respondido com 200, mesmo quando todos os eventos dele foram recusados. Olhe as contagens.

[
  {"type":"deposit","player_id":"PLR-1001","txn_id":"TX-88213","amount":"25.00","first":true},
  {"type":"ngr","player_id":"PLR-1001","period":"2026-10-03","amount":"118.40"},
  {"type":"ngr","player_id":"PLR-1002","period":"October","amount":"-12.50"}
]

{
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "event_type": "deposit",
      "event_id": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
      "commission": { "effect": "created", "type": "cpa", "amount_minor": 4000, "status": "hold" }
    },
    {
      "index": 1,
      "status": "duplicate",
      "event_type": "ngr",
      "event_id": "0199b2d1-5c0e-7b42-8a17-3e9d6f0c4b21",
      "commission": { "effect": "created", "type": "revshare", "amount_minor": 2960, "status": "hold" }
    },
    {
      "index": 2,
      "status": "rejected",
      "field": "period",
      "message": "period must be a day (2026-10-03) or a month (2026-10), not in the future."
    }
  ],
  "accepted": 1,
  "duplicate": 1,
  "rejected": 1
}

POST /v1/files

Envia um arquivo CSV diário, como alternativa ao envio pela página Integração ou a deixar a RevRake buscá-lo num endereço onde a sua plataforma o publica. O corpo é o próprio arquivo; os cabeçalhos e a assinatura são os de um evento, e a assinatura cobre o timestamp e o arquivo. O nome do arquivo vai no parâmetro de query filename; ele é exibido no portal e não é usado para mais nada.

POST https://app.revrake.com/v1/files?filename=sales-2026-10-03.csv

A linha de cabeçalho decide qual arquivo é: um arquivo com uma coluna registration_date é um arquivo REG, um com uma coluna activitydate é um arquivo SALES. Os nomes das colunas são comparados sem diferenciar maiúsculas de minúsculas. Colunas que não estão listadas abaixo podem ficar no arquivo; são ignoradas.

As datas aceitas são YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, RFC 3339 ou YYYY/MM/DD. Sem offset UTC, vale o fuso dos arquivos em Configurações do workspace (UTC por padrão). Um timestamp com offset identifica um instante exato; em SALES, usa-se seu dia de calendário no fuso dos arquivos. Dia e mês nunca são adivinhados: 30/09/2026 é recusado.

Arquivo REG: uma linha por jogador cadastrado

brand_name,registration_date,btag,promo_code,player_id,player_country
Example,2026-10-03,1001_1,,PLR-1001,KE
Example,2026-10-03,,,PLR-1002,KE
Example,2026-10-03,,GARAGE50,PLR-1003,KE

Arquivo SALES: uma linha por jogador por dia

brand_name,activitydate,player_id,btag,currency,deposits,first_deposit_amount,chargeback,casino_net_revenue,sports_net_revenue
Example,2026-10-03,PLR-1001,1001_1,KES,3500.00,2500.00,0,118.40,0
Example,2026-10-03,PLR-1002,,KES,900.00,0,0,-12.50,

• Cada linha SALES registra um resumo monetário diário e, quando há células de receita preenchidas, um evento NGR separado. São processados independentemente: um resumo monetário recusado não desfaz uma receita aceita, nem o contrário. Confira todos os problemas na resposta.
• Um resumo por marca, jogador e dia de atividade; a primeira moeda aceita fica fixa. Valores monetários idênticos são replays mesmo após renomear ou reordenar o arquivo. Alterar valores, moeda ou limites de fuso horário de um dia aceito é conflito, inclusive ao alterar zeros. O dinheiro já registrado permanece inalterado.
• deposits, first_deposit_amount e chargeback são colunas obrigatórias. Células vazias significam zero. Os valores devem ser decimais não negativos com a precisão da moeda da linha. Confirme essas definições com sua plataforma antes de conectar a exportação.
• Envie REG antes de SALES. Resumos monetários recebidos antes são guardados e precificados quando o cadastro chega. NGR de jogador desconhecido é recusado: após REG, reenvie SALES ou NGR. O resumo monetário salvo será um replay.
• O resumo cobre postbacks individuais do dia de atividade e da moeda no fuso dos arquivos, sem somar valores duas vezes. Os IDs de transação continuam referenciáveis. Depósitos ou chargebacks conhecidos acima do resumo, ou evidências inconsistentes de primeiro depósito, geram conflito.
• No CPA acumulado, depósitos menos chargebacks devem atingir o mínimo do deal. Cada fluxo diário usa a taxa de câmbio da data de atividade; postbacks individuais usam seu próprio dia UTC. A falta de taxas mantém a liquidação em retenção sob fx_rate_missing. Taxas de chargeback ausentes bloqueiam o pagamento sob chargeback_fx_missing até a reconciliação, inclusive para comissões já incluídas em um pagamento.
• No CPA de primeiro depósito, um chargeback agregado pode não identificar o depósito revertido. Um resumo monetário ambíguo de jogador já cadastrado é recusado. Se chegou antes de REG, é guardado e o cadastro é aceito, mas o CPA resultante permanece em retenção sob chargeback_reference_missing. Para revisar a referência da transação, envie um chargeback com ref_txn_id definido como o ID de transação do depósito original.
• A receita é separada dos totais monetários imutáveis: alterar o NGR diário é uma reapresentação, e a diferença de comissão vira um ajuste.

A resposta

Um arquivo legível retorna 200. Os contadores são por evento, não apenas por linha: uma linha SALES pode registrar resumo monetário e NGR separadamente, inclusive com sucesso parcial. Sempre confira rejected e problems.

{
  "id": "0199b31e-2a40-7d18-9b6c-4f1e7a2c5d03",
  "filename": "sales-2026-10-03.csv",
  "kind": "sales",
  "uploaded_at": "2026-10-04T02:00:07Z",
  "rows_total": 2,
  "accepted": 3,
  "duplicates": 0,
  "rejected": 1,
  "skipped": 0,
  "problems": ["line 3: Player PLR-1002 is not registered. Send the registration first."]
}

GET /v1/reports

Devolve o relatório da página Relatórios: cliques, cliques sinalizados, cadastros, primeiros depósitos e ganhos, agrupados de uma forma, para os dias até hoje no fuso horário do workspace. Os números de hoje são atualizados quando um relatório é solicitado, no máximo a cada 30 segundos em um programa movimentado.

GET https://app.revrake.com/v1/reports?by=link&days=7

{
  "by": "link",
  "from": "2026-09-28",
  "to": "2026-10-04",
  "currency": "KES",
  "rows": [
    {
      "key": "0199a7f0-41c2-7e55-b1d9-6c3a8e2f7b10",
      "label": "telegram-october",
      "clicks": 1840,
      "flagged_clicks": 212,
      "registrations": 96,
      "ftds": 31,
      "earnings_minor": 12400000
    }
  ],
  "total": {
    "key": "",
    "label": "",
    "clicks": 1840,
    "flagged_clicks": 212,
    "registrations": 96,
    "ftds": 31,
    "earnings_minor": 12400000
  }
}

Em CSV

Com format=csv a resposta é um arquivo. A primeira coluna leva o nome do agrupamento e contém o rótulo; depois vêm clicks, flagged_clicks, registrations, first_deposits e earnings_<currency> como decimal. A última linha é o total.

link,clicks,flagged_clicks,registrations,first_deposits,earnings_KES
telegram-october,1840,212,96,31,124000.00
total,1840,212,96,31,124000.00

GET /v1/commissions

Devolve uma página do livro-razão de comissões, das mais recentes para as mais antigas, a menos que você ordene de outra forma. As linhas nunca têm seus valores editados e nunca são apagadas, mas o status de uma linha muda depois que ela é gravada: hold, depois approved, depois paid, ou rejected. Uma sincronização precisa ler um período de novo e atualizar as linhas pelo id, não apenas buscar linhas novas.

GET https://app.revrake.com/v1/commissions?from=2026-09-01&to=2026-10-01&per_page=500

{
  "currency": "KES",
  "totals": { "hold": 1240000, "approved": 3720000, "paid": 9800000 },
  "owed": { "KES": { "hold": 1240000, "approved": 3720000, "paid": 9800000 } },
  "period": true,
  "commissions": [
    {
      "id": "0199b2c9-0a11-7c3e-9f20-7d4b1e6a2c58",
      "occurred_at": "2026-09-14T08:20:00Z",
      "type": "cpa",
      "currency": "KES",
      "gross_currency": "KES",
      "reporting_minor": 400000,
      "affiliate_name": "Odds Garage",
      "affiliate_number": 1001,
      "player_ref": "PLR-1001",
      "deal_name": "CPA 4000",
      "deal_version": 2,
      "gross_minor": 250000,
      "rate_snapshot": 400000,
      "amount_minor": 400000,
      "status": "approved",
      "status_reason": "",
      "hold_until": "2026-10-14T08:20:00Z",
      "status_note": ""
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 500
}

Uma linha de comissão

Listas do programa: afiliados, links, acordos

Seu backend pode listar o programa como o portal mostra, assinado como as outras leituras e contado no mesmo limite. GET /v1/affiliates e GET /v1/deals exigem a chave do operador; com uma chave de afiliado respondem 403 operator_key_required. GET /v1/links responde os links da marca, ou os de um afiliado com affiliate=<número>; com uma chave de afiliado, os do próprio afiliado.

As listas são paginadas com page (a partir de 1) e per_page (de 1 a 500, padrão 100) e trazem total. GET /v1/affiliates aceita também status: pending, approved, rejected ou suspended. Criar afiliados ou links pela API ainda não é oferecido: conte-nos para que você usaria.

GET https://app.revrake.com/v1/links?affiliate=1001&per_page=100

Cada afiliado

Cada link

Cada acordo

Exportação para data warehouse

Configurada na página Integração: toda noite o RevRake grava o dia anterior de cada marca no seu próprio bucket, em qualquer serviço compatível com S3, em <pasta>/<marca>/<AAAA-MM-DD>/, com o dia contado no fuso horário do workspace. Quatro arquivos CSV compactados com gzip (UTF-8, linha de cabeçalho, aspas conforme RFC 4180) e depois manifest.json. O manifesto é gravado por último: carregue um dia quando ele existir e confira rows, bytes e sha256 de cada arquivo.

Uma linha pertence ao dia em que chegou (um clique: quando aconteceu), então um arquivo diário que chega atrasado fica no dia em que chegou, nunca se perde. Horários em RFC 3339, UTC com milissegundos; valores em decimais na própria moeda. Os status são os do momento da exportação: o de uma comissão muda depois, então leia GET /v1/commissions de novo para o atual. Um dia com falha é tentado de novo a cada hora e recuperado até sete dias atrás; exportar um dia de novo sobrescreve seus arquivos. Colunas novas podem ser adicionadas no fim de um arquivo; schema_version no manifesto muda quando um carregador precisa mudar.

manifest.json: schema_version, workspace, brand, day, timezone, from e to (os limites do dia em UTC), generated_at e files: para cada um, name, rows, bytes, sha256 (do arquivo compactado).

clicks.csv.gz: todos os cliques nos links da marca naquele dia, inclusive os sinalizados.

players.csv.gz: jogadores cujo cadastro chegou naquele dia.

events.csv.gz: todos os eventos aceitos da marca que chegaram nesse dia, incluindo resumos diários SALES, com seu payload.

commissions.csv.gz: linhas de comissão gravadas naquele dia.

Idempotência

Cada evento tem uma chave natural. Uma tentativa idêntica retorna a resposta salva com "status":"duplicate". Um depósito aguardando cadastro tem sua resposta atualizada quando o cadastro chega. Fatos monetários alterados podem gerar conflito; reapresentações de NGR usam revisões. Após um timeout, tente novamente com um novo timestamp de assinatura.

Status e erros

Todas as respostas que a API pode dar e todos os status que um registro pode ter, em um só lugar. Um erro é respondido com um objeto JSON: error (o código), message (uma frase em inglês) e, para invalid, field.

{"error":"invalid","field":"amount","message":"amount must be a positive decimal in KES, for example 25.00."}

Status HTTP e códigos de erro

• Um lote sem eventos ou com mais de 1.000 é recusado com 422 invalid e sem field.
• Um 401 por timestamp ou assinatura incorretos com uma chave de operador aparece no log de entrada como bad_signature. Uma requisição com chave desconhecida, ou com uma chave de afiliado, não é registrada.
• Uma leitura responde 422 apenas para um período de relatório que não pode ser usado (from e to). Qualquer outro parâmetro com um valor não permitido é ignorado e usa-se o valor padrão. Confira by, page e per_page na resposta.
• Reenvie em um timeout, em um 429 e em um 500. Não reenvie nenhum outro 4xx sem alterações.

O que field indica em um 422

O status de um evento

Na resposta a um evento, e por evento em results de um lote.

O efeito de um evento no livro-razão

Tipos de comissão

Status de comissão

Uma linha é gravada uma vez e seus valores nunca mudam. O status muda:

Valores de status_reason

Vazio quando a linha aguarda apenas o período de retenção e normalmente em comissões aprovadas ou pagas. A falta de taxa de chargeback também pode bloquear uma linha aprovada. Retenções por fraude aguardam o operador ou a expiração configurada do alerta.

Status de pagamento

Um mês fecha em um lote de pagamento com um item por afiliado e moeda. Lotes e itens são tratados no portal; a API mostra o resultado deles como o status paid das linhas de comissão.

Por que uma linha de arquivo é recusada

Uma linha recusada é contada em rejected, listada em problems como line N: reason e mantida no log de entrada com a própria linha. Além dos motivos pelos quais um evento pode ser recusado:

• A linha não é um CSV válido.
• REG: registration_date ou player_id está ausente ou ilegível.
• SALES: activitydate ou player_id está ausente ou ilegível.
• SALES, receita: o jogador não está cadastrado.
• SALES, dinheiro: um valor é negativo, ilegível ou tem casas decimais demais para a moeda.
• SALES: o primeiro depósito supera os depósitos brutos.
• SALES: um dia aceito foi reexportado com totais monetários, moeda ou limites de fuso horário alterados.
• SALES: depósitos ou chargebacks individuais conhecidos superam o resumo do dia.
• SALES: a evidência de primeiro depósito conflita com outro dia ou uma transação conhecida.
• SALES: um chargeback agregado é ambíguo para CPA de primeiro depósito de um jogador já cadastrado.

Resultados no log de entrada

Estados de uma entrega de postback

Status de um afiliado

O link de rastreamento

Um link de rastreamento é aberto por um visitante, não chamado pela sua plataforma. Ele grava o clique e responde com um redirecionamento 302 para a landing page da marca. Enquanto a marca não verificou o site, o visitante vê antes uma página curta dizendo para onde o link leva. O host de destino vem das configurações da marca; um link só pode escolher um caminho dentro dele.

GET https://track.revrake.com/c/a8Kq2Zx?sub1=TRACKER_CLICK_ID&utm_source=telegram

HTTP/1.1 302 Found
Location: https://your-site.example/landing?btag=1001_1&cid=01K6QF3M8Z5T7W9XB2C4D6E8GH&utm_source=telegram
Cache-Control: no-store

Parâmetros no link

Parâmetros acrescentados à URL de destino

• Se a URL de destino da marca contém {click_id} na query, o click ID é colocado ali e cid não é acrescentado.
• Um clique no link de um afiliado que não está aprovado é gravado e sinalizado, e chega sem cid e btag: ele não pode ser atribuído.
• Bots, prévias de link, requisições HEAD, requisições sem user agent e cliques repetidos dentro de uma hora são gravados e sinalizados, não descartados. Os relatórios os deixam de fora.
• Outros parâmetros no link não são gravados nem repassados.
• Um link a que o afiliado deu um nome curto também responde em /go/<name>, exatamente como em /c/<code>. Uma marca com o seu próprio domínio de rastreamento verificado serve os dois caminhos também nesse domínio.
• Um código desconhecido é respondido com 404 e uma página de erro em HTML, assim como um link cuja marca ainda não definiu um destino.

Postbacks para os trackers dos afiliados

Esta parte não exige trabalho do operador. Cada afiliado adiciona até 10 destinos no portal dele: um template de endereço com macros e os eventos sobre os quais quer ser avisado. Quando um evento é registrado para um dos jogadores do afiliado, a RevRake preenche o template e o chama com uma requisição GET.

Eventos

Palavras de status por preset

Um destino criado a partir de um preset envia, em {status}, as palavras que o tracker dele conhece. Os presets do Voluum, do PeerClick e do FunnelFlux Pro, e "Outro / personalizado", enviam as palavras da tabela acima. As palavras seguem o preset que o destino leva; o endereço salvo dele nunca é alterado.

Macros

Uma macro é um nome entre chaves. É substituída pelo seu valor, codificado para URL. Os nomes são comparados sem diferenciar maiúsculas de minúsculas. Um nome que a RevRake não conhece é enviado como está, então um erro de digitação aparece no log de entregas. Um valor que não é conhecido fica vazio.

Outros nomes para as mesmas macros

Os trackers usam nomes diferentes para as mesmas coisas. Estes também são aceitos:

Presets

O portal do afiliado traz estes templates. O afiliado substitui o host pelo do seu tracker. Cada um segue a documentação do seu tracker: {conversion_id} fica no parâmetro de transação quando o tracker atualiza uma conversão que chega de novo com o mesmo ID, e {event_id} quando ele descartaria os eventos posteriores.

Um exemplo

https://YOUR-TRACKER-DOMAIN/postback?click_id={sub1}&event={event}&status={status}&payout={commission}&currency={currency}&tid={conversion_id}&eid={event_id}

GET https://tracker.example/postback?click_id=TRACKER_CLICK_ID&event=ftd&status=sale&payout=40.00&currency=KES&tid=0199b2c9-0a11-7c3e-9f20-7d4b1e6a2c58&eid=0199b2c9-03aa-7e10-b6d2-91c07f5e2a18%3Aftd

Entrega

• Um postback entra na fila na mesma transação do evento que ele informa, e é enviado em cerca de dez segundos, do mais antigo para o mais novo.
• A requisição é um GET com o user agent RevRake-Postback/1. Ela segue no máximo três redirecionamentos e desiste após 5 segundos. Os certificados são verificados.
• Uma resposta 2xx é um sucesso. Qualquer outra coisa é uma falha e é reenviada após 1 minuto, 5 minutos, 25 minutos, 2 horas, 10 horas e 24 horas.
• Depois do último reenvio, a entrega é marcada como desistida. O afiliado pode reenviá-la manualmente.
• Cada tentativa é registrada com a duração, o status e os primeiros 500 caracteres da resposta.
• Depois de 5 e de 15 falhas seguidas, o dono do destino recebe um e-mail. Com 20, o destino é desligado. As entregas dele, inclusive as de eventos que acontecem enquanto está desligado, continuam entrando na fila e são enviadas quando o afiliado o liga de novo. Um destino que o próprio afiliado desligou não recebe nada novo.
• A RevRake só chama endereços públicos. Endereços de loopback, privados, link-local e de carrier-grade NAT são recusados no momento da conexão, então um redirecionamento não consegue contornar isso.
• O template deve ser um endereço http:// ou https:// completo, com no máximo 2.000 caracteres.

Por que uma tentativa falhou

Webhooks do operador

Os webhooks informam os sistemas do próprio operador (um CRM, um data warehouse, um canal de chat) sobre o que acontece no programa. Um admin do workspace adiciona um endpoint na página Integração do portal do operador: o endereço no seu servidor, os eventos a enviar e uma descrição opcional. Para cada um desses eventos, a RevRake envia um POST JSON assinado para o endereço. Os outros membros da equipe não podem ver nem alterar os endpoints.

O endereço é um endereço https:// completo em um host público (http:// é aceito, mas use https://). Cada endpoint tem o seu próprio segredo, que começa com whsec_. Ele é mostrado uma única vez, quando o endpoint é criado ou o segredo é rotacionado: copie-o nesse momento. Rotacionar cria um novo segredo na hora, e o antigo deixa de assinar.

Um endpoint também pode ser um canal do Slack ou do Microsoft Teams: escolha “Mensagem no Slack” ou “Mensagem no Microsoft Teams” e cole o endereço de incoming webhook do canal (no Teams, um fluxo “Quando uma solicitação de webhook do Teams for recebida”). Cada evento chega então como uma frase no canal em vez de JSON assinado, e um valor pode manter só os primeiros depósitos a partir desse tamanho.

Eventos

Marque um ou mais por endpoint. Os campos de data estão descritos abaixo; um campo que não se aplica é omitido.

O corpo

Toda requisição leva um objeto JSON:

{
  "id": "0199b2c9-0a11-7c3e-9f20-7d4b1e6a2c58",
  "type": "commission.created",
  "created_at": "2026-10-05T09:12:44.318204Z",
  "data": {
    "player_id": "PLR-1001",
    "occurred_at": "2026-10-05T09:12:40Z",
    "attributed": true,
    "affiliate_number": 1001,
    "affiliate_name": "Odds Garage",
    "commission_id": "0199b2c9-0a0f-7a51-8c3d-5e2f4a6b7c90",
    "commission_type": "cpa",
    "amount": "25.00",
    "amount_currency": "USD",
    "commission": "40.00",
    "commission_currency": "USD"
  }
}

As chaves podem vir em qualquer ordem, e o espaçamento do JSON não é fixo. Verifique os bytes como foram recebidos, depois interprete-os.

Cabeçalhos

A requisição também leva Content-Type: application/json e o user agent RevRake-Webhook/1.

POST /revrake-webhook HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: RevRake-Webhook/1
RevRake-Event: commission.created
RevRake-Delivery: 0199b2c9-0b7e-7d02-8a41-3c5e6f708192
RevRake-Timestamp: 1791191571
RevRake-Signature: <hex HMAC-SHA256 of "1791191571.<raw body>">

Os campos de data

Verifique uma requisição

1. Leia o corpo bruto como bytes, antes de qualquer interpretação do JSON.
2. Verifique se RevRake-Timestamp está a no máximo 5 minutos do seu relógio, e recuse a requisição caso contrário, para que uma requisição gravada não possa ser reproduzida mais tarde.
3. Calcule o HMAC-SHA256 em hex do timestamp, um ponto e o corpo bruto com o segredo do endpoint, e compare-o com RevRake-Signature em tempo constante.
4. Só então interprete o corpo. Se você já tratou o seu id, responda 2xx e não faça nada.
5. Responda com qualquer 2xx em até 5 segundos, e faça o trabalho demorado depois.

A mesma verificação em Node.js e Python, como a página Integração a mostra:

const crypto = require("node:crypto");

// raw: the body exactly as received (a Buffer), before parsing it as JSON.
function verify(raw, headers, secret) {
  const ts = headers["revrake-timestamp"] ?? "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(ts + ".").update(raw).digest();
  const got = Buffer.from(headers["revrake-signature"] ?? "", "hex");
  return got.length === expected.length && crypto.timingSafeEqual(got, expected);
}

import hashlib, hmac, time

# raw: the body exactly as received (bytes), before parsing it as JSON.
def verify(raw: bytes, headers, secret: str) -> bool:
    ts = headers.get("RevRake-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("RevRake-Signature", ""))

Entrega, reenvios e desligamento

• Uma entrega entra na fila na mesma transação da mudança que ela informa, então um evento é enviado se e somente se a mudança foi gravada. Ela é enviada em cerca de dez segundos, as mais antigas primeiro.
• A entrega é pelo menos uma vez: o mesmo evento pode chegar mais de uma vez, por exemplo quando a sua resposta se perde no caminho. Descarte repetições pelo id do corpo.
• A ordem não é garantida: um reenvio pode chegar depois de um evento posterior. Ordene os eventos por created_at ou occurred_at, não pelo momento em que chegam.
• Uma resposta 2xx em até 5 segundos é um sucesso. Qualquer outra coisa é uma falha e é reenviada após 1 minuto, 5 minutos, 25 minutos, 2 horas, 10 horas e 24 horas, com o mesmo corpo e um timestamp e uma assinatura novos.
• Depois do último reenvio a entrega é marcada como "desistiu". Um admin pode enviá-la de novo pelo log de entregas, com o botão "Enviar novamente"; ela então recebe todo o calendário de reenvios outra vez.
• Depois de 20 tentativas falhas seguidas o endpoint é desligado. Os seus eventos continuam na fila, e tudo o que entrou na fila é enviado quando um admin o liga de novo. Nenhum e-mail é enviado quando isso acontece: o estado de cada endpoint está na página Integração.
• Um endpoint que você mesmo desliga não recebe nada novo: nenhum evento entra na fila para ele enquanto está desligado.
• A RevRake só chama endereços públicos: desiste após 5 segundos e verifica os certificados. Endereços de loopback, privados, link-local e de NAT de operadora são recusados. Um redirecionamento não é seguido: uma resposta 3xx é uma falha com o erro redirect, e o log de entregas mostra o endereço para onde ela apontava.

Teste e leia o log de entregas

• Clique em "Enviar teste" em um endpoint: um evento webhook.test é enviado na hora, assinado como um real, e você vê o status que o seu endpoint respondeu e quanto tempo levou. Um teste não é reenviado, não aparece no log de entregas e não conta como falha.
• O log de entregas de um endpoint mostra as suas 100 entregas mais recentes: o evento, o estado ("aguardando", "repetindo", "desistiu" ou "entregue"), o número de tentativas, o último status ou erro, os primeiros 500 caracteres da sua resposta, a próxima tentativa e o corpo como foi enviado.
• Uma tentativa falha é descrita com as mesmas palavras de um postback (veja por que uma tentativa falhou), mais redirect: o seu endpoint respondeu com um 3xx. Os estados são os de uma entrega de postback.

{
  "id": "0199b2d4-5c60-7b1a-9e3f-1a2b3c4d5e6f",
  "type": "webhook.test",
  "created_at": "2026-10-05T09:30:02.104377Z",
  "data": {
    "message": "A test from RevRake. If you can read this, your endpoint works."
  }
}

Boas práticas

• Guarde o segredo no seu servidor, nunca em uma página ou em um app. Se ele vazar, rotacione-o e passe o seu endpoint para o novo na hora: o segredo antigo para imediatamente.
• Responda a uma requisição cuja assinatura não confere com um 4xx. Ela é reenviada, assinada com o segredo atual, então uma entrega feita enquanto você rotaciona não se perde.
• Guarde o id de cada evento que você tratou, e ignore um evento que você já viu.
• Responda primeiro, trabalhe depois: coloque o evento em uma fila sua e responda 2xx, para que um banco de dados lento nunca faça a RevRake reenviar.
• Informe o endereço final do seu endpoint. Um redirecionamento não é seguido: a tentativa falha com redirect, e o log de entregas mostra o endereço a usar no lugar.
• Use commission_id para juntar os eventos sobre uma comissão, e concilie com GET /v1/commissions: uma leitura noturna dos últimos 60 dias pega qualquer coisa que tenha faltado.
• Marque só os eventos que você usa. Cada um é uma requisição ao seu servidor.

Arquivo OpenAPI

Os quatro endpoints assinados, com todos os status e motivos como enumerações, estão descritos em openapi.yaml (OpenAPI 3.1), para geradores de código e clientes de API. O endereço dele não muda.