La API de RevRake.

URLs base

La API son cuatro endpoints firmados para la plataforma del operador, dos de escritura y dos de lectura, y el enlace de tracking que abren los visitantes. Los endpoints firmados también se publican como un archivo OpenAPI 3.1.

Los portales en app.revrake.com usan sus propios endpoints tras una sesión iniciada. No son una API pública y pueden cambiar sin aviso. Los informes, el libro mayor y las filas de pagos también se pueden descargar allí como CSV.

Claves

Hay dos tipos de clave. Cada una tiene un ID de clave y un secreto, y cada una firma las peticiones de la misma forma. Las claves nunca se comparten: cada parte tiene la suya.

• Una clave nueva revoca la anterior al instante, en ambos tipos. Un afiliado también puede revocar su clave y quedarse sin ninguna.
• Una clave de afiliado solo funciona mientras el afiliado esté aprobado en el programa. Si no, una lectura responde 403 affiliate_inactive.
• Con una clave de afiliado, el parámetro affiliate se ignora y by=affiliate se responde por día.
• El límite de frecuencia de las lecturas se cuenta por clave.

Autenticación

Cada petición a /v1 se firma con una clave. Cada petición lleva tres cabeceras:

Para firmar una petición:

1. Construye el cuerpo y conserva los bytes exactos que vas a enviar.
2. Toma la hora Unix actual en segundos, como texto decimal.
3. Concatena el timestamp, un punto (.) y el cuerpo.
4. Calcula el HMAC-SHA256 de eso con tu secreto y escríbelo en hexadecimal en minúsculas.
5. Envía el cuerpo sin cambios, con las tres cabeceras.

Firmar una lectura

Un GET no tiene cuerpo, así que la firma cubre en su lugar el destino de la petición: la ruta y la query exactamente como se envían, por ejemplo 1790000000./v1/reports?by=link&days=7. Sin query, es el timestamp, un punto y la ruta. Construye la dirección una vez, firma ese texto y envía ese texto: un cliente que reordena o recodifica la query después de firmar rompe la firma.

• Primero se comprueba la clave, luego el timestamp y luego la firma.
• La cabecera Content-Type no es obligatoria. Envía application/json para eventos y text/csv para archivos.
• Una clave rotada deja de funcionar al instante.

Ejemplos de firma

Cada ejemplo tiene una función de firma, envía un registro y después lee un informe. Sustituye el ID de clave y el secreto por los tuyos.

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))
}

Vector de prueba

Con estas entradas, tu código debe producir exactamente estas firmas:

Secreto

test_secret

Timestamp

1791072000

Cuerpo

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

Firma

115d8c73c6069d8953a36ca3a68c114da6232e4ba31889fd519d41ab1350a603

Destino de la petición de una lectura

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

Firma de la lectura

ed1ed72dd7ddef22c762f63b8919011e7c36c7214b55b72693c5927fb4b911d0

Límites

Estos son todos los límites que el producto aplica hoy a integraciones, tracking y afiliados, con sus cifras. El inicio de sesión, el cambio de contraseña y las solicitudes también tienen límites contra el abuso.

Los dos endpoints de escritura, POST /v1/postback y POST /v1/files, tienen un límite por clave (ver la tabla). Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining; un rechazo es 429 con Retry-After. Envía al ritmo de tus eventos y usa lotes para una carga histórica. El enlace de tracking no tiene límite de frecuencia; una ráfaga inusual de clics en un enlace desde una misma dirección genera una alerta de fraude y aun así se redirige.

El límite de frecuencia de las lecturas

• Cada clave puede hacer 120 lecturas por minuto. El cupo es un cubo de 120: una lectura gasta una, y cada medio segundo se recupera una. Una clave que ha estado inactiva puede hacer 120 lecturas de golpe; después, dos por segundo.
• Cada respuesta a una lectura lleva X-RateLimit-Limit (siempre 120) y X-RateLimit-Remaining (cuántas lecturas quedan en este momento).
• Superado el límite, la respuesta es 429 rate_limited con una cabecera Retry-After: los segundos que hay que esperar. Espera y envía la misma petición de nuevo, firmada con un timestamp nuevo.
• El límite se cuenta por clave: la clave del operador y la clave de cada afiliado tienen su propio cupo.

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."}

Cómo tratar un 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 de un evento de la plataforma del operador. El cuerpo es un objeto JSON con un type y los campos de ese tipo, o un array JSON de esos objetos (un lote).

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

• type es uno de registration, deposit, chargeback, ngr.
• Un campo que no figura en la lista del tipo se rechaza con 422, así que una errata nunca se ignora en silencio.
• ts es la hora del evento en formato RFC 3339 (2026-10-04T08:15:00Z). Si se omite, se usa la hora de la petición. Debe llevar un desfase UTC (Z o +03:00); una hora sin él se rechaza. No puede estar más de un día en el futuro.
• Un importe es un decimal, como texto JSON o como número JSON: "25.00" o 25.5. Sin separador de miles, sin exponente y sin más decimales de los que tiene la moneda.
• currency es un código ISO 4217 de tres letras. Se aceptan minúsculas. Si se omite, se usa la moneda de informes del workspace.
• A los valores de texto se les quitan los espacios de ambos extremos, salvo a click_id y btag: envíalos exactamente como llegaron a la landing page.

registration

Un jugador nuevo. Envía click_id, btag, promo_code, o varios de ellos; sin ninguno, el jugador se registra como no atribuido. El jugador se atribuye una sola vez, aquí. Respuesta: 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

Envía un evento deposit por cada depósito, con tu ID de transacción en txn_id. El deal define si el mínimo para CPA se compara con el primer depósito o con los depósitos acumulados, descontados los chargebacks. La calificación crea una comisión CPA por jugador, en retención.

{"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

Envía un evento chargeback con su propio txn_id y el txn_id del depósito original en ref_txn_id. Revierte el depósito completo. En CPA acumulado, la comisión solo se retira si el total válido restante cae por debajo del mínimo: una comisión en retención se cancela; una aprobada o pagada recibe una fila de reversión.

{"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

Los ingresos netos de juego (NGR) de un jugador en un día o en un mes. Generan el RevShare de la versión del deal vigente al final del periodo, en retención. El jugador debe estar registrado. Respuesta: 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"
  }
}

La respuesta

Un evento que se guardó, o que ya estaba guardado, se responde con 200 y un objeto JSON. Los campos que no aplican se omiten.

{
  "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" }
}

Una comisión se crea con el estado hold. Se aprueba automáticamente cuando termina el periodo de retención del deal, salvo que algo la siga reteniendo: una alerta de fraude abierta, un afiliado que no está aprobado o un tipo de cambio que falta.

Motivos de atribución

Primero se prueba el click ID. Si no es uno de los tuyos, se prueba el btag. Cuando la política dice que gana el btag y el btag coincide con un enlace, se prueba primero el btag. Un btag que coincide con un enlace atribuye al jugador aunque no se encuentre ningún clic. Un código promocional se prueba al final, solo cuando ni el click ID ni el btag atribuyeron al jugador. La política, su ventana y cuál de los dos gana se definen en la página Integración; cada cambio es una nueva versión. Cuando la política dice que gana el código promocional, un código que coincide con un enlace se prueba antes que ambos, y uno que no coincide vuelve a ellos. Un acuerdo puede fijar su propia ventana, que sustituye a la de la política para los clics en los enlaces de sus afiliados.

Por qué no se creó ninguna comisión

Lotes

El cuerpo puede ser un array JSON de 1 a 1.000 eventos, enviado al mismo endpoint con las mismas cabeceras. La firma cubre el array entero. Los eventos se procesan en orden, cada uno por separado, así que un evento rechazado nunca detiene a los demás.

Un lote que se pudo leer se responde con 200, también cuando todos sus eventos se rechazaron. Mira los recuentos.

[
  {"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

Envía un archivo CSV diario, como alternativa a subirlo en la página Integración o a dejar que RevRake lo descargue desde una dirección donde tu plataforma lo publica. El cuerpo es el propio archivo; las cabeceras y la firma son las de un evento, y la firma cubre el timestamp y el archivo. El nombre del archivo va en el parámetro de query filename; se muestra en el portal y no se usa para nada más.

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

La fila de cabecera decide de qué archivo se trata: un archivo con una columna registration_date es un archivo REG, y uno con una columna activitydate es un archivo SALES. Los nombres de las columnas se comparan sin distinguir mayúsculas de minúsculas. Las columnas que no figuran abajo pueden quedarse en el archivo; se ignoran.

Las fechas admitidas son YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, RFC 3339 o YYYY/MM/DD. Sin desfase UTC, se aplica la zona de archivos de Ajustes del workspace (UTC por defecto). Un timestamp con desfase identifica un instante exacto; para SALES se usa su día de calendario en la zona de archivos. Día y mes nunca se adivinan: 30/09/2026 se rechaza.

Archivo REG: una fila por jugador registrado

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

Archivo SALES: una fila por jugador y día

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 fila SALES registra un resumen monetario diario y, si hay celdas de ingresos rellenas, un evento NGR separado. Se procesan de forma independiente: rechazar el resumen monetario no deshace ingresos aceptados, ni al revés. Revisa todos los problemas de la respuesta.
• Un resumen por marca, jugador y día de actividad; la primera moneda aceptada queda fija. Los valores monetarios idénticos son replays aunque renombres o reordenes el archivo. Cambiar importes, moneda o límites de zona horaria de un día aceptado genera conflicto, incluso al cambiar ceros. El dinero ya registrado no cambia.
• deposits, first_deposit_amount y chargeback son columnas obligatorias. Las celdas vacías equivalen a cero. Los importes deben ser decimales no negativos con la precisión de la moneda de la fila. Confirma estas definiciones con tu plataforma antes de conectar su exportación.
• Envía REG antes de SALES. Los resúmenes monetarios recibidos antes se guardan y calculan al llegar el registro. El NGR de un jugador desconocido se rechaza: después de REG, reenvía SALES o NGR. El resumen monetario guardado será un replay.
• El resumen cubre los postbacks individuales de su día de actividad y moneda en la zona de archivos, sin sumar importes dos veces. Los IDs de transacción siguen disponibles como referencias. Los depósitos o chargebacks conocidos que superen el resumen, o pruebas contradictorias del primer depósito, generan conflicto.
• En CPA acumulado, depósitos menos chargebacks deben alcanzar el mínimo del deal. Cada flujo diario usa el tipo de cambio de su fecha de actividad; los postbacks individuales usan su propio día UTC. Si faltan tipos, la liquidación queda en retención bajo fx_rate_missing. Si falta el tipo de un chargeback, se bloquea el pago bajo chargeback_fx_missing hasta la conciliación, incluso para comisiones ya incluidas en un pago.
• En CPA de primer depósito, un chargeback agregado puede no identificar el depósito revertido. Un resumen monetario ambiguo de un jugador ya registrado se rechaza. Si llegó antes de REG, se conserva y el registro se acepta, pero el CPA resultante queda en retención bajo chargeback_reference_missing. Para revisar la referencia de la transacción, envía un chargeback con ref_txn_id igual al ID de transacción del depósito original.
• Los ingresos son independientes de los totales monetarios inmutables: cambiar el NGR diario es una rectificación, y la diferencia de comisión se registra como ajuste.

La respuesta

Un archivo legible devuelve 200. Los contadores son por evento, no solo por fila: una fila SALES puede registrar resumen monetario y NGR por separado, incluso con éxito parcial. Comprueba siempre rejected y 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

Devuelve el informe de la página Informes: clics, clics marcados, registros, primeros depósitos y ganancias, agrupados de una forma, para los días hasta hoy en la zona horaria del workspace. Las cifras de hoy se actualizan cuando se pide un informe, como máximo cada 30 segundos en un programa con mucha actividad.

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
  }
}

Como CSV

Con format=csv la respuesta es un archivo. Su primera columna lleva el nombre de la agrupación y contiene la etiqueta; después vienen clicks, flagged_clicks, registrations, first_deposits y earnings_<currency> como decimal. La última línea es el 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

Devuelve una página del libro mayor de comisiones, con las más recientes primero salvo que ordenes de otra forma. Los importes de las filas nunca se editan y las filas nunca se borran, pero el status de una fila cambia después de escribirse: hold, luego approved, luego paid, o rejected. Una sincronización debe leer de nuevo un periodo y actualizar las filas por id, no solo traer las filas nuevas.

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
}

Una fila de comisión

Listas del programa: afiliados, enlaces, acuerdos

Tu backend puede listar el programa como lo muestra el portal, firmado como las demás lecturas y contado en el mismo límite. GET /v1/affiliates y GET /v1/deals necesitan la clave del operador; con una clave de afiliado responden 403 operator_key_required. GET /v1/links responde los enlaces de la marca, o los de un afiliado con affiliate=<número>; con una clave de afiliado, los suyos.

Las listas se paginan con page (desde 1) y per_page (de 1 a 500, por defecto 100) e incluyen total. GET /v1/affiliates acepta también status: pending, approved, rejected o suspended. Crear afiliados o enlaces por la API aún no se ofrece: cuéntanos para qué lo usarías.

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

Cada afiliado

Cada enlace

Cada acuerdo

Exportación al data warehouse

Se configura en la página Integración: cada noche RevRake escribe el día anterior de cada marca en tu propio bucket de cualquier servicio compatible con S3, en <carpeta>/<marca>/<AAAA-MM-DD>/, con el día contado en la zona horaria del espacio de trabajo. Cuatro archivos CSV comprimidos con gzip (UTF-8, fila de cabecera, comillas según RFC 4180) y después manifest.json. El manifiesto se escribe el último: carga un día cuando exista y comprueba rows, bytes y sha256 de cada archivo.

Una fila pertenece al día en que llegó (un clic: cuando se hizo), así que un archivo diario que llega tarde está en el día en que llegó, nunca se pierde. Las horas son RFC 3339 en UTC con milisegundos; los importes, decimales en su moneda. Los estados son los del momento de la exportación: el de una comisión cambia después, así que vuelve a leer GET /v1/commissions para el actual. Un día fallido se reintenta cada hora y se recupera hasta siete días atrás; exportar un día de nuevo sobrescribe sus archivos. Pueden añadirse columnas al final de un archivo; schema_version del manifiesto cambia cuando un cargador debe cambiar.

manifest.json: schema_version, workspace, brand, day, timezone, from y to (los límites del día en UTC), generated_at y files: para cada uno, name, rows, bytes, sha256 (del archivo comprimido).

clicks.csv.gz: todos los clics en los enlaces de la marca ese día, también los marcados.

players.csv.gz: jugadores cuyo registro llegó ese día.

events.csv.gz: todos los eventos aceptados de la marca que llegaron ese día, incluidos los resúmenes diarios SALES, con su payload.

commissions.csv.gz: filas de comisión escritas ese día.

Idempotencia

Cada evento tiene una clave natural. Un reintento idéntico devuelve la respuesta guardada con "status":"duplicate". La respuesta de un depósito pendiente de registro se actualiza al llegar este. Los datos monetarios cambiados pueden generar conflicto; las rectificaciones NGR usan revisiones. Tras un timeout, reintenta con un timestamp de firma nuevo.

Estados y errores

Todas las respuestas que la API puede dar y todos los estados que puede tener un registro, en un solo lugar. Un error se responde con un objeto JSON: error (el código), message (una frase en inglés) y, para invalid, field.

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

Estados HTTP y códigos de error

• Un lote sin eventos o con más de 1.000 se rechaza con 422 invalid y sin field.
• Un 401 por un timestamp o una firma incorrectos con una clave de operador aparece en el registro de entrada como bad_signature. Una petición con una clave desconocida, o con una clave de afiliado, no se registra.
• Una lectura responde 422 solo para un periodo de informe que no se puede usar (from y to). Cualquier otro parámetro con un valor no permitido se ignora y se usa su valor por defecto. Comprueba by, page y per_page en la respuesta.
• Reintenta ante un tiempo de espera agotado, ante un 429 y ante un 500. No reintentes ningún otro 4xx sin cambios.

Qué indica field en un 422

El estado de un evento

En la respuesta a un evento, y por evento en results de un lote.

El efecto de un evento en el libro mayor

Tipos de comisión

Estados de una comisión

Una fila se escribe una vez y sus importes nunca cambian. Su estado sí:

Valores de status_reason

Vacío si la fila solo espera su periodo de retención y normalmente en comisiones aprobadas o pagadas. Un tipo de chargeback ausente también puede bloquear una fila aprobada. Las retenciones por fraude esperan al operador o al vencimiento configurado de la alerta.

Estados de los pagos

Un mes se cierra en un lote de pago con un elemento por afiliado y moneda. Los lotes y los elementos se gestionan en el portal; la API muestra su resultado como el estado paid de las filas de comisión.

Por qué se rechaza una fila de un archivo

Una fila rechazada se cuenta en rejected, aparece en problems como line N: reason y se conserva en el registro de entrada con la propia línea. Además de los motivos por los que se puede rechazar un evento:

• La línea no es CSV válido.
• REG: falta registration_date o player_id, o no puede leerse.
• SALES: falta activitydate o player_id, o no puede leerse.
• SALES, ingresos: el jugador no está registrado.
• SALES, dinero: un importe es negativo, ilegible o tiene demasiados decimales para su moneda.
• SALES: el primer depósito supera los depósitos brutos.
• SALES: se reexporta un día aceptado con totales monetarios, moneda o límites de zona horaria cambiados.
• SALES: los depósitos o chargebacks individuales conocidos superan el resumen del día.
• SALES: la prueba del primer depósito contradice otro día o una transacción conocida.
• SALES: un chargeback agregado es ambiguo para CPA de primer depósito de un jugador ya registrado.

Resultados en el registro de entrada

Estados de una entrega de postback

Estados de un afiliado

El enlace de tracking

Un enlace de tracking lo abre un visitante, no lo llama tu plataforma. Guarda el clic y responde con una redirección 302 a la landing page de la marca. Mientras la marca no haya verificado su sitio, el visitante ve antes una página breve que dice adónde lleva el enlace. El host de destino viene de la configuración de la marca; un enlace solo puede elegir una ruta dentro de él.

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 en el enlace

Parámetros añadidos a la URL de destino

• Si la URL de destino de la marca contiene {click_id} en su query, el click ID se pone ahí y no se añade cid.
• Un clic en el enlace de un afiliado que no está aprobado se guarda y se marca, y llega sin cid ni btag: no se puede atribuir.
• Los bots, las previsualizaciones de enlaces, las peticiones HEAD, las peticiones sin user agent y los clics repetidos en una hora se guardan y se marcan, no se descartan. Los informes los dejan fuera.
• Los demás parámetros del enlace no se guardan ni se pasan.
• Un enlace al que el afiliado ha dado un nombre corto responde también en /go/<name>, exactamente igual que en /c/<code>. Una marca con su propio dominio de tracking verificado sirve también ambas rutas en ese dominio.
• Un código desconocido se responde con 404 y una página de error en HTML, igual que un enlace cuya marca aún no ha fijado un destino.

Postbacks a los trackers de los afiliados

Esta parte no exige trabajo al operador. Cada afiliado añade hasta 10 destinos en su portal: una plantilla de dirección con macros y los eventos de los que quiere enterarse. Cuando se registra un evento de uno de los jugadores del afiliado, RevRake rellena la plantilla y la llama con una petición GET.

Eventos

Palabras de estado por preset

Un destino creado con un preset envía, en {status}, las palabras que conoce su tracker. Los presets de Voluum, PeerClick y FunnelFlux Pro, y "Otro / personalizado", envían las palabras de la tabla de arriba. Las palabras siguen al preset que lleva el destino; su dirección guardada no se cambia nunca.

Macros

Una macro es un nombre entre llaves. Se sustituye por su valor, codificado para URL. Los nombres se comparan sin distinguir mayúsculas de minúsculas. Un nombre que RevRake no conoce se envía tal cual, así que una errata se ve en el registro de entregas. Un valor que no se conoce queda vacío.

Otros nombres para las mismas macros

Los trackers usan nombres distintos para las mismas cosas. También se aceptan estos:

Presets

El portal de afiliado incluye estas plantillas. El afiliado sustituye el host por el de su tracker. Cada una sigue la documentación de su tracker: {conversion_id} va en el parámetro de transacción donde el tracker actualiza una conversión que llega de nuevo con el mismo ID, {event_id} donde descartaría los eventos posteriores.

Un ejemplo

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

• Un postback se pone en cola en la misma transacción que el evento del que informa, y se envía en unos diez segundos, los más antiguos primero.
• La petición es un GET con el user agent RevRake-Postback/1. Sigue como máximo tres redirecciones y abandona a los 5 segundos. Los certificados se verifican.
• Una respuesta 2xx es un éxito. Cualquier otra cosa es un fallo y se reintenta a 1 minuto, 5 minutos, 25 minutos, 2 horas, 10 horas y 24 horas.
• Tras el último reintento, la entrega se marca como abandonada. El afiliado puede reenviarla a mano.
• Cada intento se registra con su duración, el estado y los primeros 500 caracteres de la respuesta.
• Tras 5 y tras 15 fallos seguidos, el propietario del destino recibe un email. A los 20 el destino se desactiva. Sus entregas, incluidas las de los eventos que ocurren mientras está desactivado, siguen poniéndose en cola y se envían cuando el afiliado lo activa de nuevo. Un destino que el propio afiliado desactivó no recibe nada nuevo.
• RevRake solo llama a direcciones públicas. Las direcciones de loopback, privadas, link-local y de NAT de operador (carrier-grade NAT) se rechazan al establecer la conexión, así que una redirección no puede saltarse el control.
• La plantilla debe ser una dirección http:// o https:// completa de como máximo 2.000 caracteres.

Por qué falló un intento

Webhooks del operador

Los webhooks cuentan a los sistemas propios del operador (un CRM, un data warehouse, un canal de chat) lo que pasa en el programa. Un admin del workspace añade un endpoint en la página Integración del portal del operador: la dirección de tu servidor, los eventos que se envían y una descripción opcional. Por cada uno de esos eventos, RevRake envía un POST JSON firmado a la dirección. Los demás miembros del equipo no pueden ver ni cambiar los endpoints.

La dirección es una dirección https:// completa en un host público (se acepta http://, pero usa https://). Cada endpoint tiene su propio secreto, que empieza por whsec_. Se muestra una sola vez, cuando se crea el endpoint o se rota su secreto: cópialo en ese momento. Rotar crea un secreto nuevo al instante, y el anterior deja de firmar.

Un endpoint también puede ser un canal de Slack o Microsoft Teams: elige «Mensaje de Slack» o «Mensaje de Microsoft Teams» y pega la dirección de incoming webhook del canal (para Teams, un flujo «Cuando se recibe una solicitud de webhook de Teams»). Cada evento llega entonces como una frase en el canal en lugar de JSON firmado, y un importe puede dejar solo los primeros depósitos desde ese tamaño.

Eventos

Marca uno o varios por endpoint. Los campos de data se describen más abajo; un campo que no aplica se omite.

El cuerpo

Cada petición lleva un 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"
  }
}

Las claves pueden venir en cualquier orden, y el espaciado del JSON no es fijo. Verifica los bytes tal como llegan y después interprétalos.

Cabeceras

La petición también lleva Content-Type: application/json y el 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>">

Los campos de data

Verificar una petición

1. Lee el cuerpo en bruto como bytes, antes de interpretar el JSON.
2. Comprueba que RevRake-Timestamp está a menos de 5 minutos de tu reloj, y rechaza la petición si no, para que una petición grabada no se pueda reproducir más tarde.
3. Calcula el HMAC-SHA256 en hexadecimal del timestamp, un punto y el cuerpo en bruto con el secreto del endpoint, y compáralo con RevRake-Signature en tiempo constante.
4. Solo entonces interpreta el cuerpo. Si ya procesaste su id, responde 2xx y no hagas nada.
5. Responde con cualquier 2xx en menos de 5 segundos, y haz el trabajo lento después.

La misma comprobación en Node.js y Python, tal como la muestra la página Integración:

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, reintentos y desactivación

• Una entrega se pone en cola en la misma transacción que el cambio que informa, así que un evento se envía si y solo si el cambio se guardó. Se envía en unos diez segundos, el más antiguo primero.
• La entrega es al menos una vez: el mismo evento puede llegar más de una vez, por ejemplo cuando tu respuesta se pierde por el camino. Descarta las repeticiones por el id del cuerpo.
• El orden no está garantizado: un reintento puede llegar después de un evento posterior. Ordena los eventos por created_at u occurred_at, no por el momento en que llegan.
• Una respuesta 2xx en menos de 5 segundos es un éxito. Cualquier otra cosa es un fallo y se reintenta tras 1 minuto, 5 minutos, 25 minutos, 2 horas, 10 horas y 24 horas, con el mismo cuerpo y un timestamp y una firma nuevos.
• Tras el último reintento, la entrega se marca como abandonada. Un admin puede reenviarla con "Enviar de nuevo" desde el registro de entregas; entonces vuelve a recibir todo el calendario de reintentos.
• Tras 20 intentos fallidos seguidos, el endpoint se desactiva. Sus eventos siguen en cola, y todo lo que se acumuló se envía cuando un admin lo vuelve a activar. No se envía ningún email cuando esto ocurre: el estado de cada endpoint está en la página Integración.
• Un endpoint que desactivas tú mismo no recibe nada nuevo: no se pone en cola ningún evento para él mientras está desactivado.
• RevRake solo llama a direcciones públicas: se rinde tras 5 segundos y verifica los certificados. Las direcciones de loopback, privadas, link-local y de NAT de operador (CGNAT) se rechazan. Una redirección no se sigue: una respuesta 3xx es un fallo con el error redirect, y el registro de entregas muestra la dirección a la que apuntaba.

Pruébalo y lee el registro de entregas

• Pulsa "Enviar prueba" en un endpoint: se envía al instante un evento webhook.test, firmado como uno real, y ves el estado que respondió tu endpoint y cuánto tardó. Una prueba no se reintenta, no aparece en el registro de entregas y no cuenta como fallo.
• El registro de entregas de un endpoint muestra sus últimas 100 entregas: el evento, el estado (en espera, reintentando, abandonado o entregado), el número de intentos, el último estado o error, los primeros 500 caracteres de tu respuesta, el próximo intento y el cuerpo tal como se envió.
• Un intento fallido se describe con las mismas palabras que un postback (mira por qué falló un intento), más redirect: tu endpoint respondió con un 3xx. Los estados son los de una 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."
  }
}

Buenas prácticas

• Guarda el secreto en tu servidor, nunca en una página ni en una app. Si se filtra, rótalo y pasa tu endpoint al nuevo enseguida: el secreto anterior deja de valer al instante.
• Responde con un 4xx a una petición cuya firma no coincide. Se reintenta, firmada con el secreto actual, así que una entrega hecha mientras rotas no se pierde.
• Guarda el id de cada evento que hayas procesado, e ignora un evento que ya hayas visto.
• Responde primero y trabaja después: pon el evento en una cola propia y responde 2xx, para que una base de datos lenta nunca haga que RevRake reintente.
• Introduce la dirección final de tu endpoint. Una redirección no se sigue: el intento falla con redirect, y el registro de entregas indica la dirección que debes usar.
• Usa commission_id para unir los eventos sobre una misma comisión, y concilia con GET /v1/commissions: una lectura nocturna de los últimos 60 días recupera todo lo que se haya perdido.
• Marca solo los eventos que uses. Cada uno es una petición a tu servidor.

Archivo OpenAPI

Los cuatro endpoints firmados, con cada estado y cada motivo como una enumeración, están descritos en openapi.yaml (OpenAPI 3.1), para generadores de código y clientes de API. Su dirección no cambia.