Server-side API integration

1. Maak een API-sleutel

1. Log in met een geverifieerd adverteerdersaccount.
2. Open Dashboard → API-sleutels en maak een sleutel.
3. Kopieer de volledige sleutel direct. MUNK bewaart alleen een SHA-256-hash en kan de volledige sleutel later niet opnieuw tonen.
4. Bewaar de sleutel als servergeheim, bijvoorbeeld in je hostingomgeving of een configuratiebestand buiten de publieke webroot. Geef alleen toegang aan de applicatie die de postback verstuurt.

Deel de sleutel niet in HTML, JavaScript, mobiele apps, screenshots, tickets of Git-repositories. Trek een sleutel direct in als je vermoedt dat deze gelekt is.

2. Waar plaats je de sleutel?

Plaats hem op de server van je website in een environment variable, bijvoorbeeld MUNK_API_KEY. Gebruik geen vaste sleutel in een publiek bestand. De backend leest de sleutel uit de omgeving en stuurt de postback pas nadat een order werkelijk is aangemaakt.

# Voorbeeld configuratie op de server (geen echte sleutel)
MUNK_API_KEY=munk_VERVANG_DIT_MET_JE_EIGEN_SLEUTEL

3. Endpoint en beveiligingsheaders

POST /api/v1/conversion.php

• Content-Type: application/json
• X-Munk-Key: jouw_api_sleutel
• X-Munk-Timestamp: unix_timestamp
• X-Munk-Signature: HMAC-SHA256(timestamp + "." + raw_body, api_key)
• De sleutel moet de scope conversion:write hebben.

De timestamp mag maximaal vijf minuten afwijken. Onderteken exact de ruwe JSON-body die je verstuurt; serialiseer de body niet opnieuw nadat de handtekening is gemaakt.

4. Koppel de klik aan de bestelling

Herkomstregistratie: bij de eerste trackingklik registreert MUNK automatisch de verwijzende domeinnaam (indien de browser die meestuurt), een globale browserherkenning en apparaattype. Deze gegevens worden via de click_id gekoppeld aan de latere conversie en zijn zichtbaar voor de beheerder bij de commissiebeoordeling. Een ontbrekende verwijzer betekent niet automatisch dat de link rechtstreeks is geopend: apps, privacyinstellingen en browsers kunnen de verwijzer weglaten. De ruwe verwijzende URL en volledige user-agent worden niet opgeslagen.

Een MUNK-trackinglink stuurt de bezoeker door naar je productpagina met de parameter munk_click_id. Sla deze waarde server-side op bij de sessie of order. Vertrouw niet op een door de bezoeker aangeleverde omzetwaarde. Stuur bij een voltooide en betaalde order de eerder opgeslagen click-ID mee.

5. Voorbeeld: click-ID veilig bewaren

Lees de click-ID op de landingspagina uit de querystring, valideer het formaat en sla hem op in de server-side sessie of ordercontext. Gebruik nooit een click-ID die later door de browser opnieuw kan worden aangepast.

session_start();
$clickId = (string)($_GET['munk_click_id'] ?? '');
if (preg_match('/^[a-f0-9]{32}$/', $clickId)) {
    $_SESSION['munk_click_id'] = $clickId;
}

6. Voorbeeld request (PHP)

$apiKey = getenv('MUNK_API_KEY');
$timestamp = (string) time();
$payload = json_encode([
    'click_id' => $storedClickId, // 32 hex-tekens uit de order/session
    'conversion_ref' => $uniqueOrderId, // unieke order- of registratie-ID
    'conversion_type' => 'sale', // gebruik een van: registration, lead, signup, download, app_install, appointment, qualified_call
    'gross_amount' => $verifiedOrderTotal // gebruik 0 voor registraties
], JSON_UNESCAPED_SLASHES);
$signature = hash_hmac('sha256', $timestamp . '.' . $payload, $apiKey);

$ch = curl_init('/api/v1/conversion.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-Munk-Key: ' . $apiKey,
    'X-Munk-Timestamp: ' . $timestamp,
    'X-Munk-Signature: ' . $signature
  ],
  CURLOPT_CONNECTTIMEOUT => 5,
  CURLOPT_TIMEOUT => 10
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Ondersteunde conversietypen

Gebruik exact één van deze waarden in conversion_type: sale, registration, lead, signup, download, app_install, appointment of qualified_call. Voor sale is een positief gross_amount verplicht. Voor de overige actiegebeurtenissen stuurt de integratie gross_amount: 0. De campagne moet hetzelfde vergoedingstype hebben en de klik moet bij de betreffende adverteerder horen. Elke conversie wordt eerst als pending review geregistreerd.

7. Velden en reacties

• click_id: de eerder opgeslagen 32-teken hex-ID.
• conversion_ref: unieke orderreferentie; dubbele referenties worden geweigerd.
• gross_amount: door je backend vastgestelde orderomzet in de campagnevaluta. Voor een verkoop moet dit groter zijn dan 0; voor registraties exact 0. Dit bedrag wordt ter controle opgeslagen en bepaalt niet automatisch de affiliatecommissie; de campagnevergoeding in MUNK bepaalt de commissie.
• conversion_type: sale of registration; dit moet overeenkomen met het campagnedoel dat de adverteerder heeft ingesteld.

Bij succes antwoordt de API met HTTP 201 en status pending_review. De campagnevergoeding wordt bij goedkeuring standaard verdeeld in 75% netto affiliatecommissie en 25% MUNK-platformvergoeding; beide bedragen zitten binnen de ingestelde bruto vergoeding. HTTP 409 met duplicate_conversion_ref betekent dat de orderreferentie al is verwerkt. Gebruik een stabiele, unieke order-ID en verstuur bij timeouts dezelfde referentie opnieuw. HTTP 429 betekent dat de API-limiet is bereikt. MUNK controleert de conversie voordat een commissie definitief wordt. Veelvoorkomende fouten zijn 401 (sleutel/timestamp/handtekening), 404 (klik niet gevonden of niet bij deze adverteerder), 409 (campagne/budget niet geschikt) en 422 (ongeldige velden).

8. Controle door MUNK

Elke ontvangen conversie wordt als In beoordeling opgeslagen. De beheerder ziet de adverteerder, affiliate, campagne, orderreferentie, click-ID, gerapporteerde orderomzet, commissie en datum. Controleer bij verkoop de orderreferentie en betaalstatus in het eigen ordersysteem van de adverteerder voordat je goedkeurt. MUNK kan via een postback vaststellen dat de server van de adverteerder een verkoop heeft gemeld, maar kan zonder onafhankelijke betaalprovider- of webshopkoppeling niet zelfstandig bewijzen dat het geld daadwerkelijk is ontvangen. De postback is daarom een controleerbare verklaring van de adverteerder, geen onafhankelijk betalingsbewijs.

9. Promotiemateriaal en campagnedoel

Bij het aanmaken of bewerken van een campagne kiest de adverteerder of de vergoeding per geldige websiteklik, bevestigde registratie of goedgekeurde verkoop geldt. Klikken worden geregistreerd wanneer een bezoeker via de persoonlijke MUNK-trackinglink gaat. Voor registraties en verkopen moet de server van de adverteerder een ondertekende postback naar de API sturen. Een bannerbeeld op zichzelf registreert geen klik: de affiliate moet de MUNK-trackinglink instellen als klikbestemming van de banner. Meerdere bannerformaten kunnen per campagne worden geüpload en de afmetingen worden opgeslagen.

10. Wat kun je meten?

MUNK registreert campagnevertoningen in de openbare campagnecatalogus, trackinglink-klikken, conversiepostbacks, tijdstip, campagne, affiliate, status en gehashte technische signalen voor fraudebeoordeling. Rapportages tonen totalen per campagne. Een vertoning is geen unieke persoon; cookieblokkering, bots en browserprivacy kunnen metingen beïnvloeden. Verzamel alleen gegevens die nodig zijn en informeer bezoekers volgens je privacyverklaring.

11. Voorbeeld van de server-side flow

1. De bezoeker klikt op de persoonlijke MUNK-link.
2. MUNK stuurt de bezoeker naar je productpagina met munk_click_id.
3. Je backend bewaart de click-ID bij de winkelwagen / order, niet alleen in een vluchtige URL.
4. Na bevestiging van de bestelling verstuurt je backend één signed postback.
5. MUNK controleert de campagne, eigenaar, sleutel, scope, klik, budget en dubbele referentie.
6. De commissie blijft pending totdat deze is beoordeeld.

12. Test veilig

1. Gebruik eerst een eigen testcampagne en een testorder.
2. Controleer dat de click-ID server-side wordt opgeslagen.
3. Verifieer HTTP-status en response zonder API-sleutels in logs te schrijven.
4. Test een ongeldige handtekening en een dubbele orderreferentie.
5. Gebruik geen echte klantgegevens in testpayloads.