L'API RevRake.

URL de base

L'API se compose de quatre endpoints signés pour la plateforme de l'opérateur, deux pour écrire et deux pour lire, et du lien de tracking qu'ouvrent les visiteurs. Les endpoints signés sont aussi publiés sous forme de fichier OpenAPI 3.1.

Les portails sur app.revrake.com utilisent leurs propres endpoints derrière une session connectée. Ce n'est pas une API publique, et ils peuvent changer sans préavis. Les rapports, le grand livre et les lignes de paiement peuvent aussi y être téléchargés en CSV.

Clés

Il existe deux sortes de clé. Chacune a un identifiant de clé et un secret, et chacune signe les requêtes de la même façon. Les clés ne se partagent jamais : chaque partie a la sienne.

• Une nouvelle clé révoque l'ancienne immédiatement, pour les deux sortes. Un affilié peut aussi révoquer sa clé et n'en avoir aucune.
• Une clé affilié ne fonctionne que tant que l'affilié est approuvé dans le programme. Sinon, une lecture répond 403 affiliate_inactive.
• Avec une clé affilié, le paramètre affiliate est ignoré et by=affiliate est traité par jour.
• La limite de débit des lectures est comptée par clé.

Authentification

Chaque requête /v1 est signée avec une clé. Chaque requête porte trois en-têtes :

Pour signer une requête :

1. Construisez le corps et gardez les octets exacts que vous allez envoyer.
2. Prenez l'heure Unix actuelle en secondes, en texte décimal.
3. Concaténez le timestamp, un point (.) et le corps.
4. Calculez le HMAC-SHA256 de ce texte avec votre secret et écrivez-le en hexadécimal minuscule.
5. Envoyez le corps inchangé, avec les trois en-têtes.

Signer une lecture

Un GET n'a pas de corps : la signature porte donc sur la cible de la requête, c'est-à-dire le chemin et la query exactement tels qu'ils sont envoyés, par exemple 1790000000./v1/reports?by=link&days=7. Sans query, c'est le timestamp, un point et le chemin. Construisez l'adresse une fois, signez ce texte et envoyez ce texte : un client qui réordonne ou réencode la query après la signature casse la signature.

• La clé est vérifiée d'abord, puis le timestamp, puis la signature.
• L'en-tête Content-Type n'est pas obligatoire. Envoyez application/json pour les événements et text/csv pour les fichiers.
• Une clé renouvelée cesse de fonctionner immédiatement.

Exemples de signature

Chaque exemple a une seule fonction de signature, envoie une inscription puis lit un rapport. Remplacez l'identifiant de clé et le secret par les vôtres.

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

Vecteur de test

Avec ces entrées, votre code doit produire exactement ces signatures :

Secret

test_secret

Timestamp

1791072000

Corps

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

Signature

115d8c73c6069d8953a36ca3a68c114da6232e4ba31889fd519d41ab1350a603

Cible de la requête d'une lecture

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

Signature de la lecture

ed1ed72dd7ddef22c762f63b8919011e7c36c7214b55b72693c5927fb4b911d0

Limites

Voici toutes les limites que le produit applique aujourd'hui aux intégrations, au tracking et aux affiliés, avec leurs valeurs. La connexion, la réinitialisation du mot de passe et les candidatures ont aussi des limites contre les abus.

Les deux endpoints d'écriture, POST /v1/postback et POST /v1/files, sont limités par clé (voir le tableau). Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining ; un refus est un 429 avec Retry-After. Envoyez au rythme de vos événements et utilisez des lots pour un rattrapage. Le lien de tracking n'a pas de limite de débit ; une rafale inhabituelle de clics sur un lien depuis une même adresse lève un signalement de fraude et est tout de même redirigée.

La limite de débit des lectures

• Chaque clé peut faire 120 lectures par minute. Le quota est une réserve de 120 : une lecture en prend une, et une revient toutes les demi-secondes. Une clé restée inactive peut faire 120 lectures d'un coup ; ensuite, deux par seconde.
• Chaque réponse à une lecture porte X-RateLimit-Limit (toujours 120) et X-RateLimit-Remaining (combien de lectures il reste à cet instant).
• Au-delà de la limite, la réponse est 429 rate_limited avec un en-tête Retry-After : le nombre de secondes à attendre. Attendez, puis renvoyez la même requête, signée avec un timestamp frais.
• La limite est comptée par clé : la clé de l'opérateur et la clé de chaque affilié ont chacune leur quota.

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

Gérer 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

Déclare un événement de la plateforme de l'opérateur. Le corps est un objet JSON avec un type et les champs de ce type, ou un tableau JSON de tels objets (un lot).

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

• type vaut registration, deposit, chargeback ou ngr.
• Un champ qui n'est pas listé pour le type est refusé avec un 422, de sorte qu'une faute de frappe n'est jamais ignorée en silence.
• ts est l'heure de l'événement au format RFC 3339 (2026-10-04T08:15:00Z). S'il est omis, l'heure de la requête est utilisée. Il doit porter un décalage UTC (Z ou +03:00) ; une heure sans décalage est refusée. Il ne peut pas être à plus d'un jour dans le futur.
• Un montant est un décimal, en texte JSON ou en nombre JSON : "25.00" ou 25.5. Pas de séparateur de milliers, pas d'exposant, et pas plus de décimales que la devise n'en a.
• currency est un code ISO 4217 à trois lettres. Les minuscules sont acceptées. S'il est omis, la devise de reporting de l'espace de travail est retenue.
• Les espaces en début et en fin des valeurs de texte sont retirées, sauf pour click_id et btag : envoyez-les exactement tels qu'ils sont arrivés sur la landing page.

registration

Un nouveau joueur. Envoyez click_id, btag, promo_code, ou plusieurs d'entre eux ; sans aucun, le joueur est enregistré comme non attribué. Le joueur est attribué une seule fois, ici. Réponse : 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

Envoyez un événement deposit par dépôt, avec votre identifiant de transaction dans txn_id. Le deal compare son minimum CPA au premier dépôt ou aux dépôts cumulés, déduction faite des chargebacks. La qualification crée une commission CPA par joueur, en rétention.

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

Envoyez un événement chargeback avec son propre txn_id et le txn_id du dépôt initial dans ref_txn_id. Il annule ce dépôt en totalité. Pour le CPA cumulé, la commission est reprise seulement si le total admissible restant passe sous le minimum : une commission en rétention est annulée ; une commission approuvée ou payée reçoit une ligne d’annulation.

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

Le revenu net de jeu (NGR) d'un joueur pour un jour ou un mois. Il rapporte le RevShare de la version du deal en vigueur à la fin de la période, en rétention. Le joueur doit être inscrit. Réponse : 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 réponse

Un événement qui a été enregistré, ou qui l'était déjà, reçoit un 200 et un objet JSON. Les champs qui ne s'appliquent pas sont omis.

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

Une commission est créée avec le statut hold. Elle est approuvée automatiquement à la fin de la période de rétention du deal, sauf si quelque chose la retient encore : une alerte de fraude ouverte, un affilié qui n'est pas approuvé, ou un taux de change manquant.

Raisons d'attribution

Le click ID est essayé d'abord. S'il n'est pas l'un des vôtres, le btag est essayé. Quand la politique dit que le btag l'emporte et que le btag correspond à un lien, le btag est essayé d'abord. Un btag qui correspond à un lien attribue le joueur même quand aucun clic n'est trouvé. Un code promo est essayé en dernier, seulement si ni le click ID ni le btag n'ont attribué le joueur. La politique, sa fenêtre et lequel des deux l'emporte se règlent sur la page Intégration ; chaque changement est une nouvelle version. Quand la politique fait primer le code promo, un code qui correspond à un lien est essayé avant les deux, et un code qui ne correspond pas revient à eux. Un accord peut fixer sa propre fenêtre, qui remplace celle de la politique pour les clics sur les liens de ses affiliés.

Pourquoi aucune commission n'a été créée

Lots

Le corps peut être un tableau JSON de 1 à 1 000 événements, envoyé au même endpoint avec les mêmes en-têtes. La signature porte sur le tableau entier. Les événements sont traités dans l'ordre, chacun séparément, de sorte qu'un événement refusé n'arrête jamais les autres.

Un lot qui a pu être lu reçoit un 200, même quand tous ses événements ont été refusés. Regardez les compteurs.

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

Envoie un fichier CSV quotidien, au lieu de l'importer sur la page Intégration ou de laisser RevRake le récupérer à une adresse où votre plateforme le publie. Le corps est le fichier lui-même ; les en-têtes et la signature sont ceux d'un événement, et la signature porte sur le timestamp et le fichier. Le nom du fichier va dans le paramètre de query filename ; il est affiché dans le portail et ne sert à rien d'autre.

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

La ligne d'en-tête détermine de quel fichier il s'agit : un fichier avec une colonne registration_date est un fichier REG, un fichier avec une colonne activitydate est un fichier SALES. Les noms de colonnes sont comparés sans tenir compte de la casse. Les colonnes qui ne sont pas listées ci-dessous peuvent rester dans le fichier ; elles sont ignorées.

Formats acceptés : YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, RFC 3339 ou YYYY/MM/DD. Sans décalage UTC, le fuseau des fichiers défini dans les Paramètres s’applique (UTC par défaut). Un horodatage avec décalage désigne un instant précis ; pour SALES, son jour civil dans le fuseau des fichiers est retenu. Le jour et le mois ne sont jamais devinés : 30/09/2026 est refusé.

Fichier REG : une ligne par joueur inscrit

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

Fichier SALES : une ligne par joueur et par jour

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,

• Chaque ligne SALES enregistre un récapitulatif monétaire quotidien et, si des cellules de revenu sont remplies, un événement NGR distinct. Ils sont traités indépendamment : refuser le récapitulatif monétaire n’annule pas le revenu accepté, ni l’inverse. Vérifiez tous les problèmes dans la réponse.
• Un récapitulatif par marque, joueur et jour d’activité ; la première devise acceptée est définitive. Des montants identiques sont des replays, même après renommage ou réordonnancement du fichier. Modifier les montants, la devise ou les limites horaires d’un jour accepté crée un conflit, y compris pour des zéros. Les montants déjà enregistrés restent inchangés.
• deposits, first_deposit_amount et chargeback sont obligatoires. Une cellule vide vaut zéro. Les montants doivent être des décimaux non négatifs respectant la précision de la devise de la ligne. Confirmez ces définitions avec votre plateforme avant de connecter son export.
• Envoyez REG avant SALES. Les récapitulatifs monétaires reçus avant sont conservés et calculés à l’arrivée de l’inscription. Le NGR d’un joueur inconnu est refusé : après REG, renvoyez SALES ou NGR. Le récapitulatif monétaire conservé sera un replay.
• Le récapitulatif couvre les postbacks individuels de son jour d’activité et de sa devise dans le fuseau des fichiers, sans additionner les montants deux fois. Les identifiants de transaction restent utilisables comme références. Des dépôts ou chargebacks connus dépassant le récapitulatif, ou des preuves contradictoires du premier dépôt, créent un conflit.
• Pour le CPA cumulé, les dépôts moins les chargebacks doivent atteindre le minimum du deal. Chaque flux quotidien utilise le taux de change de sa date d’activité ; chaque postback utilise son propre jour UTC. Sans taux, le règlement reste en rétention sous fx_rate_missing. Un taux de chargeback manquant bloque le paiement sous chargeback_fx_missing jusqu’au rapprochement, même pour les commissions déjà incluses dans un paiement.
• Pour le CPA sur premier dépôt, un chargeback agrégé peut ne pas identifier le dépôt annulé. Un récapitulatif monétaire ambigu d’un joueur déjà inscrit est refusé. S’il est arrivé avant REG, il est conservé et l’inscription réussit, mais le CPA créé reste en rétention sous chargeback_reference_missing. Pour vérifier la référence de transaction, envoyez un chargeback dont ref_txn_id contient l’identifiant de transaction du dépôt initial.
• Le revenu est distinct des totaux monétaires immuables : modifier le NGR quotidien constitue une rectification, et la différence de commission devient un ajustement.

La réponse

Un fichier lisible renvoie 200. Les compteurs portent sur les événements, pas seulement les lignes : une ligne SALES peut enregistrer séparément un récapitulatif monétaire et du NGR, avec un succès partiel. Vérifiez toujours rejected et 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

Renvoie le rapport de la page Rapports : clics, clics signalés, inscriptions, premiers dépôts et gains, groupés d'une seule façon, pour les jours jusqu'à aujourd'hui dans le fuseau horaire de l'espace de travail. Les chiffres du jour sont actualisés quand un rapport est demandé, au plus toutes les 30 secondes sur un programme chargé.

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

En CSV

Avec format=csv, la réponse est un fichier. Sa première colonne porte le nom du groupement et contient le libellé ; viennent ensuite clicks, flagged_clicks, registrations, first_deposits et earnings_<currency> en décimal. La dernière ligne est le 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

Renvoie une page du grand livre des commissions, les plus récentes d'abord sauf si vous triez autrement. Le montant d'une ligne n'est jamais modifié et une ligne n'est jamais supprimée, mais son status change après son écriture : hold, puis approved, puis paid, ou rejected. Une synchronisation doit relire une période et mettre à jour les lignes d'après leur id, pas seulement récupérer les nouvelles lignes.

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
}

Une ligne de commission

Listes du programme : affiliés, liens, accords

Votre backend peut lister le programme tel que le portail le montre, signé comme les autres lectures et compté dans la même limite. GET /v1/affiliates et GET /v1/deals demandent la clé de l'opérateur ; avec une clé d'affilié ils répondent 403 operator_key_required. GET /v1/links répond les liens de la marque, ou ceux d'un affilié avec affiliate=<numéro> ; avec une clé d'affilié, les siens.

Les listes sont paginées avec page (à partir de 1) et per_page (de 1 à 500, 100 par défaut) et portent total. GET /v1/affiliates accepte aussi status : pending, approved, rejected ou suspended. Créer des affiliés ou des liens par l'API n'est pas encore proposé : dites-nous à quoi cela vous servirait.

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

Chaque affilié

Chaque lien

Chaque accord

Export vers l’entrepôt de données

Réglé sur la page Intégration : chaque nuit, RevRake écrit la veille de chaque marque dans votre propre bucket, sur tout service compatible S3, à <dossier>/<marque>/<AAAA-MM-JJ>/, le jour étant compté dans le fuseau horaire de l’espace de travail. Quatre fichiers CSV compressés en gzip (UTF-8, une ligne d’en-tête, guillemets selon la RFC 4180), puis manifest.json. Le manifeste est écrit en dernier : chargez un jour une fois qu’il existe, et vérifiez rows, bytes et sha256 de chaque fichier.

Une ligne appartient au jour où elle est arrivée (un clic : quand il a eu lieu) : un fichier quotidien en retard est dans le jour où il est arrivé, jamais perdu. Les heures sont en RFC 3339, UTC avec millisecondes ; les montants sont des décimaux dans leur devise. Les statuts sont ceux du moment de l’export : celui d’une commission change ensuite, relisez donc GET /v1/commissions pour le statut actuel. Un jour en échec est réessayé toutes les heures et rattrapé jusqu’à sept jours en arrière ; réexporter un jour écrase ses fichiers. De nouvelles colonnes peuvent être ajoutées en fin de fichier ; schema_version du manifeste change quand un chargeur doit changer.

manifest.json : schema_version, workspace, brand, day, timezone, from et to (les bornes du jour en UTC), generated_at et files : pour chacun, name, rows, bytes, sha256 (du fichier compressé).

clicks.csv.gz : tous les clics sur les liens de la marque ce jour-là, signalés compris.

players.csv.gz : les joueurs dont l’inscription est arrivée ce jour-là.

events.csv.gz : tous les événements acceptés de la marque arrivés ce jour-là, y compris les récapitulatifs quotidiens SALES, avec leur contenu.

commissions.csv.gz : les lignes de commission écrites ce jour-là.

Idempotence

Chaque événement possède une clé naturelle. Un nouvel envoi identique renvoie la réponse conservée avec "status":"duplicate". La réponse d’un dépôt en attente d’inscription est mise à jour à son arrivée. Des données monétaires modifiées peuvent créer un conflit ; les rectifications NGR utilisent des révisions. Après un délai dépassé, réessayez avec un nouvel horodatage de signature.

Statuts et erreurs

Toutes les réponses que l'API peut donner et tous les statuts qu'un enregistrement peut avoir, au même endroit. Une erreur reçoit un objet JSON : error (le code), message (une phrase en anglais) et, pour invalid, field.

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

Statuts HTTP et codes d'erreur

• Un lot sans événement ou de plus de 1 000 événements est refusé avec un 422 invalid, sans field.
• Un 401 pour un timestamp ou une signature incorrects avec une clé opérateur figure dans le journal des entrées comme bad_signature. Une requête avec une clé inconnue, ou avec une clé affilié, n'est pas journalisée.
• Une lecture ne répond 422 que pour une période de rapport inutilisable (from et to). Tout autre paramètre dont la valeur n'est pas autorisée est ignoré et sa valeur par défaut est utilisée. Vérifiez by, page et per_page dans la réponse.
• Réessayez sur un délai dépassé, sur un 429 et sur un 500. Ne renvoyez aucun autre 4xx inchangé.

Ce que field désigne dans un 422

Le statut d'un événement

Dans la réponse à un événement, et par événement dans les results d'un lot.

L'effet d'un événement sur le grand livre

Types de commission

Statuts d'une commission

Une ligne est écrite une fois et ses montants ne changent jamais. Son statut, lui, change :

Valeurs de status_reason

Vide si la ligne attend seulement sa période de rétention, et normalement pour les commissions approuvées ou payées. Un taux de chargeback manquant peut aussi bloquer une ligne approuvée. Les rétentions pour fraude attendent l’opérateur ou l’expiration configurée du signalement.

Statuts des paiements

Un mois se clôture en un lot de paiement, avec un élément par affilié et par devise. Les lots et les éléments se traitent dans le portail ; l'API montre leur résultat par le statut paid des lignes de commission.

Pourquoi une ligne de fichier est refusée

Une ligne refusée est comptée dans rejected, listée dans problems sous la forme line N: reason, et conservée dans le journal des entrées avec la ligne elle-même. En plus des raisons pour lesquelles un événement peut être refusé :

• La ligne n’est pas un CSV valide.
• REG : registration_date ou player_id manque ou est illisible.
• SALES : activitydate ou player_id manque ou est illisible.
• SALES, revenu : le joueur n’est pas inscrit.
• SALES, montants : un montant est négatif, illisible ou comporte trop de décimales pour sa devise.
• SALES : le premier dépôt dépasse le total brut des dépôts.
• SALES : un jour accepté est réexporté avec des totaux monétaires, une devise ou des limites horaires modifiés.
• SALES : les dépôts ou chargebacks individuels connus dépassent le récapitulatif du jour.
• SALES : les données du premier dépôt contredisent un autre jour ou une transaction connue.
• SALES : un chargeback agrégé est ambigu pour le CPA sur premier dépôt d’un joueur déjà inscrit.

Résultats dans le journal des entrées

États d'un envoi de postback

Statuts d'un affilié

Le lien de tracking

Un lien de tracking est ouvert par un visiteur, pas appelé par votre plateforme. Il enregistre le clic et répond par une redirection 302 vers la landing page de la marque. Tant que la marque n'a pas vérifié son site, le visiteur voit d'abord une courte page indiquant où mène le lien. L'hôte de destination vient des réglages de la marque ; un lien ne peut choisir qu'un chemin sur celui-ci.

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

Paramètres sur le lien

Paramètres ajoutés à l'URL d'arrivée

• Si l'URL d'arrivée de la marque contient {click_id} dans sa query, le click ID y est placé et cid n'est pas ajouté.
• Un clic sur le lien d'un affilié qui n'est pas approuvé est enregistré et signalé, et arrive sans cid ni btag : il ne peut pas être attribué.
• Les bots, les aperçus de liens, les requêtes HEAD, les requêtes sans user agent et les clics répétés dans l'heure sont enregistrés et signalés, pas écartés. Les rapports les excluent.
• Les autres paramètres du lien ne sont ni enregistrés ni transmis.
• Un lien auquel l'affilié a donné un nom court répond aussi à /go/<name>, exactement comme à /c/<code>. Une marque qui a son propre domaine de tracking vérifié sert aussi les deux chemins sur ce domaine.
• Un code inconnu reçoit un 404 et une page d'erreur HTML, tout comme un lien dont la marque n'a pas encore défini de destination.

Postbacks vers les trackers des affiliés

Cette partie ne demande aucun travail à l'opérateur. Chaque affilié ajoute jusqu'à 10 destinations dans son portail : un modèle d'adresse avec des macros, et les événements dont il veut être informé. Quand un événement est enregistré pour l'un des joueurs de l'affilié, RevRake complète le modèle et l'appelle par une requête GET.

Événements

Mots de statut par preset

Une destination créée à partir d'un preset envoie, dans {status}, les mots que son tracker connaît. Les presets de Voluum, PeerClick et FunnelFlux Pro, ainsi que « Other / custom », envoient les mots du tableau ci-dessus. Les mots suivent le preset que porte la destination ; son adresse enregistrée n'est jamais modifiée.

Macros

Une macro est un nom entre accolades. Elle est remplacée par sa valeur, encodée pour l'URL. Les noms sont comparés sans tenir compte de la casse. Un nom que RevRake ne connaît pas est envoyé tel quel, de sorte qu'une faute de frappe apparaît dans le journal des envois. Une valeur qui n'est pas connue est vide.

Autres noms pour les mêmes macros

Les trackers emploient des noms différents pour les mêmes choses. Ceux-ci sont aussi acceptés :

Presets

Le portail affilié fournit ces modèles. L'affilié remplace l'hôte par celui de son tracker. Chacun suit la documentation de son tracker : {conversion_id} est dans le paramètre de transaction là où le tracker met à jour une conversion qui arrive de nouveau sous le même identifiant, {event_id} là où il écarterait les événements ultérieurs.

Un exemple

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

Envoi

• Un postback est mis en file d'attente dans la même transaction que l'événement qu'il annonce, et envoyé en une dizaine de secondes, le plus ancien d'abord.
• La requête est un GET avec le user agent RevRake-Postback/1. Elle suit trois redirections au plus et abandonne après 5 secondes. Les certificats sont vérifiés.
• Une réponse 2xx est un succès. Toute autre réponse est un échec, retenté après 1 minute, 5 minutes, 25 minutes, 2 heures, 10 heures et 24 heures.
• Après le dernier essai, l'envoi est marqué comme abandonné. L'affilié peut le relancer à la main.
• Chaque tentative est enregistrée avec sa durée, le statut et les 500 premiers caractères de la réponse.
• Après 5 puis 15 échecs d'affilée, le propriétaire de la destination reçoit un e-mail. À 20, la destination est désactivée. Ses envois, y compris ceux des événements qui surviennent pendant qu'elle est désactivée, continuent d'être mis en file d'attente et sont envoyés quand l'affilié la réactive. Une destination que l'affilié a désactivée lui-même ne reçoit rien de nouveau.
• RevRake n'appelle que des adresses publiques. Les adresses de bouclage, privées, link-local et de NAT opérateur (CGNAT) sont refusées au moment de la connexion, de sorte qu'une redirection ne peut pas contourner ce contrôle.
• Le modèle doit être une adresse http:// ou https:// complète de 2 000 caractères au plus.

Pourquoi une tentative a échoué

Webhooks opérateur

Les webhooks informent les propres systèmes de l'opérateur (un CRM, un entrepôt de données, un canal de discussion) de ce qui se passe dans le programme. Un admin de l'espace de travail ajoute un endpoint sur la page Intégration du portail opérateur : l'adresse sur votre serveur, les événements à envoyer et une description facultative. Pour chacun de ces événements, RevRake envoie un POST JSON signé à cette adresse. Les autres membres de l'équipe ne peuvent ni voir ni modifier les endpoints.

L'adresse est une adresse https:// complète sur un hôte public (http:// est accepté, mais utilisez https://). Chaque endpoint a son propre secret, qui commence par whsec_. Il n'est affiché qu'une fois, quand l'endpoint est créé ou que son secret est renouvelé : copiez-le à ce moment-là. Le renouvellement crée un nouveau secret immédiatement, et l'ancien cesse de signer.

Un endpoint peut aussi être un canal Slack ou Microsoft Teams : choisissez « Message Slack » ou « Message Microsoft Teams » et collez l'adresse de webhook entrant du canal (pour Teams, un flux « Quand une requête webhook Teams est reçue »). Chaque événement arrive alors en une phrase dans le canal au lieu du JSON signé, et un montant peut ne garder que les premiers dépôts à partir de cette taille.

Événements

Cochez-en un ou plusieurs par endpoint. Les champs de data sont décrits plus bas ; un champ qui ne s'applique pas est omis.

Le corps

Chaque requête transporte un objet 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"
  }
}

Les clés peuvent arriver dans n'importe quel ordre, et l'espacement du JSON n'est pas fixe. Vérifiez les octets tels que reçus, puis analysez-les.

En-têtes

La requête porte aussi Content-Type: application/json et l'agent utilisateur 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>">

Les champs de data

Vérifier une requête

1. Lisez le corps brut en octets, avant toute analyse JSON.
2. Vérifiez que RevRake-Timestamp est à moins de 5 minutes de votre horloge, et refusez la requête sinon, afin qu'une requête enregistrée ne puisse pas être rejouée plus tard.
3. Calculez le HMAC-SHA256 en hexadécimal du timestamp, d'un point et du corps brut sous le secret de l'endpoint, et comparez-le à RevRake-Signature en temps constant.
4. Seulement ensuite, analysez le corps. Si vous avez déjà traité son id, répondez 2xx et ne faites rien.
5. Répondez par n'importe quel 2xx en moins de 5 secondes, et faites le travail lent ensuite.

La même vérification en Node.js et en Python, telle que la page Intégration l'affiche :

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", ""))

Envoi, nouveaux essais et désactivation

• Un envoi est mis en file dans la même transaction que le changement qu'il signale : un événement est envoyé si et seulement si le changement a été enregistré. Il est envoyé en une dizaine de secondes environ, le plus ancien d'abord.
• L'envoi est « au moins une fois » : le même événement peut arriver plus d'une fois, par exemple quand votre réponse se perd en route. Écartez les doublons grâce à l'id du corps.
• L'ordre n'est pas garanti : un nouvel essai peut arriver après un événement plus récent. Ordonnez les événements par created_at ou occurred_at, pas par leur heure d'arrivée.
• Une réponse 2xx en moins de 5 secondes est un succès. Tout le reste est un échec et est réessayé après 1 minute, 5 minutes, 25 minutes, 2 heures, 10 heures et 24 heures, avec le même corps et un nouveau timestamp et une nouvelle signature.
• Après le dernier essai, l'envoi est marqué comme abandonné. Un admin peut le renvoyer depuis le journal des envois ; il repart alors pour tout le calendrier de nouveaux essais.
• Après 20 tentatives échouées d'affilée, l'endpoint est désactivé. Ses événements continuent de s'accumuler, et tout ce qui s'est accumulé est envoyé quand un admin le réactive. Aucun email n'est envoyé dans ce cas : l'état de chaque endpoint est visible sur la page Intégration.
• Un endpoint que vous désactivez vous-même ne reçoit rien de nouveau : aucun événement n'est mis en file pour lui tant qu'il est désactivé.
• RevRake n'appelle que des adresses publiques : il abandonne après 5 secondes et vérifie les certificats. Les adresses de bouclage, privées, link-local et de NAT de niveau opérateur sont refusées. Une redirection n'est pas suivie : une réponse 3xx est un échec avec l'erreur redirect, et le journal des envois montre l'adresse vers laquelle elle pointait.

Le tester et lire le journal des envois

• Cliquez sur « Envoyer un test » sur un endpoint : un événement webhook.test est envoyé immédiatement, signé comme un vrai, et vous voyez le statut répondu par votre endpoint et le temps qu'il a pris. Un test n'est pas réessayé, n'apparaît pas dans le journal des envois et ne compte pas comme un échec.
• Le journal des envois d'un endpoint montre ses 100 derniers envois : l'événement, l'état (en attente, nouvel essai, abandonné ou délivré), le nombre de tentatives, le dernier statut ou la dernière erreur, les 500 premiers caractères de votre réponse, le prochain essai, et le corps tel qu'il a été envoyé.
• Une tentative échouée est décrite avec les mêmes mots qu'un postback (voir pourquoi une tentative a échoué), plus redirect : votre endpoint a répondu par un 3xx. Les états sont ceux d'un envoi 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."
  }
}

Bonnes pratiques

• Gardez le secret sur votre serveur, jamais dans une page ou une application. S'il fuit, renouvelez-le et passez votre endpoint au nouveau immédiatement : l'ancien secret cesse de fonctionner aussitôt.
• Répondez par un 4xx à une requête dont la signature ne correspond pas. Elle est réessayée, signée avec le secret actuel, donc un envoi fait pendant un renouvellement n'est pas perdu.
• Conservez l'id de chaque événement traité, et ignorez un événement déjà vu.
• Répondez d'abord, travaillez ensuite : mettez l'événement dans votre propre file et répondez 2xx, pour qu'une base de données lente ne pousse jamais RevRake à réessayer.
• Saisissez l'adresse finale de votre endpoint. Une redirection n'est pas suivie : la tentative échoue avec redirect, et le journal des envois indique l'adresse à utiliser à la place.
• Utilisez commission_id pour relier les événements concernant une commission, et rapprochez avec GET /v1/commissions : une lecture nocturne des 60 derniers jours rattrape tout ce qui aurait été manqué.
• Ne cochez que les événements que vous utilisez. Chacun est une requête vers votre serveur.

Fichier OpenAPI

Les quatre endpoints signés, avec chaque statut et chaque raison sous forme d'énumération, sont décrits dans openapi.yaml (OpenAPI 3.1), pour les générateurs de code et les clients d'API. Son adresse ne change pas.