Conversie-API

De Conversie-API stelt u in staat om niet-Stripe-conversies aan Selgeo te melden — aanmeldingen, formulierinzendingen, gratis proefversies, upgrades of aangepaste gebeurtenissen. U roept hem aan vanaf uw server nadat een conversie heeft plaatsgevonden, en Selgeo schrijft deze toe aan de verwijzende partner op basis van een click_id of promo_code.

API-versie: v1

Eindpunt: POST /api/v1/conversions

Authenticatie

Authorization: Bearer sk_test_YOUR_KEY

Stel geheime sleutels nooit bloot in frontend-code

Geheime sleutels (sk_*) mogen alleen worden gebruikt in server-side code.

Verzoektekst

Veld	Type	Vereist	Beschrijving
`click_id`	`string` (UUID)	Voorwaardelijk	De klik-ID van het trackingsnippet. Vereist als `promo_code` niet is opgegeven.
`promo_code`	`string`	Voorwaardelijk	Een promotiecode voor attributie. Vereist als `click_id` niet is opgegeven.
`external_transaction_id`	`string`	Ja	Uw unieke identificatiecode voor deze conversie. Gebruikt voor deduplicatie. Max 255 tekens.
`event_type`	`string`	Ja	Het type conversiegebeurtenis (bijv. `signup`, `purchase`, `upgrade`). Max 100 tekens.
`amount_cents`	`integer`	Nee	De conversiewaarde in centen. Standaard: `0`.
`currency`	`string`	Voorwaardelijk	ISO 4217 3-letterige valutacode. Vereist als `amount_cents > 0`.
`occurred_at`	`string` (ISO 8601)	Nee	Wanneer de conversie heeft plaatsgevonden. Standaard huidige tijd.
`prospect_email`	`string` (email)	Nee	Het e-mailadres van de gebruiker die de conversie uitvoert. Gebruikt voor zelf-referralfraude-detectie.
`metadata`	`object`	Nee	Willekeurige niet-persoonlijke sleutel-waardeparen voor eigen gebruik. Neem geen persoonsgegevens of bijzondere categorieën van persoonsgegevens op. Max 4 KB.

Houd persoonsgegevens uit metadata

Stuur geen onnodige persoonsgegevens en nooit bijzondere categorieën van persoonsgegevens (artikel 9 AVG — bijvoorbeeld gegevens over gezondheid, etnische afkomst, religie of politieke opvattingen) in het veld metadata. Selgeo verwerkt niet opzettelijk bijzondere categorieën van persoonsgegevens en kan deze niet betrouwbaar detecteren in vrije-tekstvelden, dus het weren ervan is uw verantwoordelijkheid als verwerkingsverantwoordelijke. Let op: prospect_email is een persoonsgegeven: u levert het uitsluitend voor detectie van zelfverwijzingsfraude, en het wordt verwerkt onder uw verantwoordelijkheid als verwerkingsverantwoordelijke.

Voorbeeldverzoek

curl -X POST https://app.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

HTTP-statuscodes

Status	Betekenis
`201`	Conversie succesvol aangemaakt
`400`	Validatiefout
`401`	Ongeldige of ontbrekende API-sleutel
`409`	Dubbele `external_transaction_id`
`422`	Geen attributiesignaal of test/live-modus mismatch
`429`	Frequentielimiet overschreden

Testen

Stel een testprogramma en een partner in. Maak het programma aan in het Selgeo-dashboard en nodig een testpartner uit, log vervolgens als die partner in op het partnerportaal en maak een verwijzingslink aan (onder Links).
Bezoek uw site via de trackinglink om een klik te registreren.
Lees de click_id uit de browserconsole:
```
__selgeo.getClickId()
```

Stuur een testconversie vanaf uw terminal:

curl -X POST https://app.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "PLAK_HIER_DE_CLICK_ID",
    "external_transaction_id": "test_001",
    "event_type": "signup",
    "amount_cents": 0
  }'

Controleer het antwoord — attributed zou true moeten zijn en attribution_source zou "link" moeten zijn.
Verifieer in het dashboard — de conversie zou in Analytics moeten verschijnen, toegewezen aan de testpartner.

Volgende stappen

Webhooks — meldingen ontvangen wanneer conversies worden toegeschreven
Testmodus — gedetailleerde testgids voor uw integratie
Probleemoplossing — veelvoorkomende problemen en oplossingen

Authenticatie​

Verzoektekst​

Voorbeeldverzoek​

HTTP-statuscodes​

Testen​

Volgende stappen​