Addrevenue API-referentie

Addrevenue API-referentie

Onze REST API is ontwikkeld om te voldoen aan de behoeften van affiliates en adverteerders. De API maakt gebruik van OAuth 2.0 en je genereert handmatig een API-token met een levenslange geldigheidsduur in onze gebruikersinterface. Dit Bearer-token wordt vervolgens als Authorization-header verzonden.

Basis-URL van de API

Alle eindpunten beginnen met de basis-URL:

https://addrevenue.io/api/v2

Zorg ervoor dat je altijd het HTTPS-protocol gebruikt.

Authenticatie

Om een API-token te genereren, log je in op Addrevenue, klik je op API-tokens en vervolgens op ‘Een nieuw API-token genereren’. Dit genereert een uniek, levenslang geldig API-token voor de ingelogde gebruiker, waarmee de client gemachtigd wordt om namens deze gebruiker te handelen.

Het token moet vervolgens als een Bearer-token worden meegestuurd in alle verzoeken aan API-eindpunten.

Voorbeeld van een header:

Authorization: Bearer 1892cd44-c59c-42bf-9f1d-a5316ea695cc Content-type: application/json

Fouten

Het verzenden van een leeg of ongeldig Bearer-token resulteert in een van de volgende HTTP-fouten:

403 Authorization header not found

Dit geeft aan dat de Authorization-header ontbreekt of op een of andere manier onjuist is geformuleerd, bijvoorbeeld doordat "Bearer" string ontbreekt.

403 Invalid token
De header is correct geformatteerd, maar het opgegeven API-token bestaat niet.

403 Inactive account
De header is correct geformatteerd en het opgegeven API-token bestaat, maar het behoort tot een account dat niet actief is.

Reacties

Alle reacties zijn in JSON-formaat en bevatten http_code (hetzelfde als in de reactieheader), count (aantal resultaatitems) en results (een array met resultaatitems).

Voorbeeld (verkort):

{
    "http_code": 200,
    "count": 2,
    "results": [
        {
            "id": 1000,
            "description": "Voorbeeldcampagne A"
        },
        {
            "id": 1001,
            "description": "Voorbeeldcampagne B"
        }
    ]

 

API-eindpunten

Omdat deze API zich nog in een bètaversie bevindt die in ontwikkeling is, hebben we de exacte documentatie van de responsbody van alle eindpunten uitgesteld.

• Adverteerders
• Banners
• Campagnes
• Kanalen
• Evenementen
• Uitbetalingen
• Producten
• Product feeds
• Relaties
• Statistieken
• Transacties

 

Verzoekparameters

Over het algemeen kun je verzoekparameters in de querystring verzenden met dezelfde namen als in het antwoord om het verzoek te filteren. Als je bijvoorbeeld alleen de klikken voor clickId 6230fe5f0fc866.4851567a wilt ophalen, ziet het verzoek er als volgt uit.: /events?type=Click&clickId=6230fe5f0fc866.4851567a.

 

Datumintervallen

Voor sommige eindpunten worden datumintervalparameters gebruikt, bijvoorbeeld voor transacties en gebeurtenissen. Deze worden opgegeven met behulp van fromDate en/of toDate.

Ze kunnen samen worden gebruikt om een interval in te stellen, of slechts één ervan. In veel endpoints kun je ook updatedFromDate en/of updatedToDate gebruiken, waarmee wordt gefilterd op de datum waarop het is bijgewerkt in plaats van de aanmaakdatum.

Adverteerders ophalen

GET /advertisers

Als je bent geauthenticeerd als een affiliate-account, bevat het antwoord een array met alle actieve adverteerders. Als een channelId is opgegeven, bevat het antwoord alleen adverteerders met een relatie (actief, in behandeling of afgewezen). De relatiestatus wordt geretourneerd als relationStatus.

Indien geverifieerd als een adverteerdersaccount, bevat het antwoord alleen het geverifieerde adverteerdersaccount zelf.

Verzoekparameters:

Parameter	Beschrijving
channelId integer	Optioneel. Als er een kanaal-ID wordt opgegeven, bevat het antwoord alleen adverteerders die een relatie hebben met het opgegeven kanaal.

 

Banners ophalen

GET /banners

Dit eindpunt retourneert een array met alle bannergroepen en de bijbehorende banners.

Indien geverifieerd als een affiliate-account, bevat het antwoord een array met alle bannergroepen en de bijbehorende banners voor alle adverteerders.

Als er een channelId wordt opgegeven en er een goedgekeurde relatie bestaat tussen het kanaal en de adverteerder, wordt er een trackingcode voor elke banner in het antwoord opgenomen.

Indien geverifieerd als adverteerdersaccount, bevat het antwoord een array met alle bannergroepen en de bijbehorende banners voor deze adverteerder.

Verzoekparameters:

Parameter	Beschrijving
channelId integer	Optioneel. Als er een kanaal-ID wordt opgegeven, worden trackingcodes voor alle banners in het antwoord opgenomen.

 

 

Campagnes ophalen

GET /campaigns

Dit eindpunt retourneert een array met alle campagnes (kortingscodes en aanbiedingen).

Indien geverifieerd als een affiliate-account, bevat het antwoord alle openbare actieve campagnes voor alle adverteerders, plus alle exclusieve campagnes voor kanalen die bij deze specifieke affiliate horen. Als een channelId-verzoekparameter wordt meegegeven, worden alleen campagnes geretourneerd voor adverteerders met een goedgekeurde relatie tot het kanaal en wordt voor elke campagne een trackingLink in het antwoord opgenomen.

Indien geverifieerd als een adverteerdersaccount, bevat het antwoord alle campagnes (zowel actieve als niet-actieve, en zowel openbare als kanaalexclusieve) voor deze adverteerder.

Verzoekparameters:

Parameter	Beschrijving
channelId integer	Optioneel. Als er een kanaal-ID wordt opgegeven, worden alleen campagnes van adverteerders met een goedgekeurde relatie tot het kanaal opgenomen. Kanaalspecifieke trackinglinks voor alle campagnes worden in het antwoord opgenomen.

 

 

Kanalen ophalen

GET /channels

Indien geverifieerd als affiliate-account, bevat het antwoord een array met alle kanalen die bij het geverifieerde account horen.

Indien geverifieerd als adverteerdersaccount, wordt een 403 Forbidden-antwoordheader geretourneerd.

 

Evenementen ophalen

GET /events

Retourneert alle tracking-events voor het geverifieerde account.

Uitbetalingen ophalen

GET /payouts

Retourneert alle uitbetalingen voor het geverifieerde affiliate-account. Als het geverifieerde account geen affiliate is, wordt een 403 Forbidden-foutmelding geretourneerd.

Producten ophalen

GET /products

Retourneert alle producten in de productcatalogus. Het antwoord is gepagineerd.

Verzoekparameters:

Parameter	Beschrijving
limit geheel getal	Optioneel. Aantal producten in het antwoord. Standaard is 100. Maximum is 1000.
offset geheel getal	Optioneel. De offset van de paginering. De standaardwaarde is 0, wat de eerste producten oplevert (limit). Als je 1 doorgeeft, krijg je de volgende limit resultaten terug.

Voorbeeld:

/products?limit=50&offset=3

Productfeeds ophalen

GET /productfeeds?channelId=xxxxxxx

Dit eindpunt retourneert een array met alle productfeeds voor het opgegeven kanaal.

Als je bent geauthenticeerd als adverteerdersaccount, krijg je een 403 Forbidden-respons, omdat dit eindpunt alleen bedoeld is voor affiliates.

Aanvraagparameters:

Parameter	Beschrijving
channelID geheel getal	Vereist. De kanaal-ID is vereist, omdat deze wordt opgenomen in de gegenereerde productfeed-URL's.

Relaties ophalen

GET /relations

Retourneert alle relaties tussen kanalen en adverteerders voor het geauthenticeerde account.

Statistieken ophalen

GET /stats

Retourneert geaggregeerde statistieken zoals bannervertoningen, klikken, transacties, enz. voor het geauthenticeerde account.

Aanvraagparameters:

Parameter	Beschrijving
groupBy string	Optioneel. Indien opgenomen, wordt het antwoord geaggregeerd op het groupBy-niveau. Geaccepteerde opties voor groupBy zijn datum, adverteerder, kanaal en programma. Indien niet opgegeven, wordt het antwoord geaggregeerd tot één enkel blok. Om te groeperen op meerdere dimensies kun je een komma als scheidingsteken gebruiken.

 

Transacties ophalen

GET /transactions

Retourneert alle transacties voor het geauthenticeerde account.

Aanvraagparameters:

Parameter	Beschrijving
includeClicks Integer	Optioneel. Indien opgenomen en ingesteld op 1, zal het antwoord ook een array bevatten van alle klikken die aan de transactie voorafgingen.

In ontwikkeling!

Deze API-referentie wordt bijgewerkt wanneer er meer eindpunten worden toegevoegd.

Houd er rekening mee dat deze API zich in de bètaversie bevindt en dat de documentatie van de responsen op verzoeken is uitgesteld.

Wijzigingslogboek

18-09-2024: De namen van de pagineringsparameters zijn gewijzigd van productsPerPage en selectedPage naar limit en offset.

12-05-2022: Nieuw /payouts-eindpunt toegevoegd waarmee affiliates alle uitbetalingen kunnen ophalen.

28-04-2022: Nieuw /productfeeds-eindpunt toegevoegd waarmee affiliates een lijst met alle productfeed-URL's kunnen ophalen.

27-04-2022: Nieuw /relations-eindpunt toegevoegd om je relaties tussen kanalen en adverteerders weer te geven.

22-04-2022: Mogelijkheid toegevoegd om /stats te groeperen op meerdere dimensies.

21-04-2022: channelId toegevoegd als verzoekparameter naar het /advertiser-eindpunt, om de respons te beperken tot adverteerders met een relatie tot het opgegeven kanaal.

2022-04-20: Het /stats-eindpunt toegevoegd voor het verkrijgen van geaggregeerde statistieken.

2022-04-19: De mogelijkheid toegevoegd om de respons van bepaalde eindpunten, zoals transacties en gebeurtenissen, te beperken door gebruik te maken van de query-stringparameters fromDate en/of toDate.

2022-03-22: Bij het verzenden van channelId naar het /campaigns-eindpunt worden nu alleen campagnes weergegeven van adverteerders met een goedgekeurde relatie tot het kanaal.

2022-03-19: De requestparameter includeClicks toegevoegd aan het /transactions-eindpunt, om alle voorgaande klikken in een array op te nemen.

2022-03-18: trackingLink toegevoegd aan de respons van het /campaigns-eindpunt, indien parameter Het kanaal-ID is opgegeven.

2022-03-18: AdvertiserName toegevoegd aan het antwoord van het /campaigns-eindpunt.

2022-03-18: AdvertiserName toegevoegd aan het antwoord van het /banners-eindpunt.