API

Gebruik alle WebwinkelKeur mogelijkheden

WebwinkelKeur heeft een industrie standaard REST API geïmplementeerd. De enige eis is dat je het https protocol gebruikt en jezelf identificeert a.d.h. van je webwinkel's ID en persoonlijke API code.

Beide kunnen op de API pagina binnen het dashboard gevonden worden.

Gebruik je PHP? Dan kun je de API client via Composer installeren, en daarmee van de API gebruik maken.


UITNODIGINGEN TOEVOEGEN

Gebruik een POST request om een uitnodiging te versturen (of in te plannen).

URL

POST /1.0/invitations.json

GET
parameters
Veld Voorbeeld Standaard Beschrijving
id 1 Verplicht De ID van de webwinkel.
code "123456789abc123456789" Verplicht Je persoonlijke API code.
POST
parameters
Veld Voorbeeld Standaard Beschrijving
email "johndoe@gmail.com" Verplicht Het volledige e-mailadres van de klant die de uitnodiging dient te ontvangen.
order "order123" "" Het (optionele) bestelnummer.
language "en" "<webwinkel's standaard>" De (optionele) taal in ISO-639-1 formaat.
delay 0 0 De (optionele) vertraging in dagen (gebruik 0 om de uitnodiging z.s.m. te versturen).
customer_name "Jan Jansen" "" De (optionele) klantnaam.
phone_numbers ["+31612345678"] null De (optionele) telefoonnummers van de klant als een array.
order_total 1500.99 null Het (optionele) totaalbedrag als decimaal getal, met een punt als decimaalteken.
client "wordpress" null De (optionele) naam van de software/het systeem waar de request vandaan komt.
platform_version "wp-4.9.2-wc-3.2.6" null De (optionele) versie van de software/het systeem waar de request vandaan komt.
plugin_version "1.6.0" null De (optionele) versie van de code/plugin waar de request vandaan komt.
Antwoord
JSON

Het antwoord zal een JSON gecodeerd object met 2 waardes bevatten: status en message.

{
    "status": "success",
    "message": "Invite successfully added to queue!"
}

De volgende combinaties van status en message zijn mogelijk:

status message Uitleg
success Invitation successfully added to queue! De uitnodiging is succesvol aan de wachtrij toegevoegd.
success Invitation already sent for this order. De combinatie van email en order is al voor een andere uitnodiging gebruikt.
error Not all obligated variables are set. Één of meer van de vereiste variabelen (id, code en/of email) werden niet meegegeven.
error Incorrect authentication credentials. De combinatie van id en code is incorrect.
error Unexpected error while processing. Please contact WebwinkelKeur. Een onbekende fout is opgetreden. Deze kan waarschijnlijk alleen door het WebwinkelKeur opgelost worden.
PHP cURL
voorbeeld
<?php
$id 
1;
$code "123456789abc123456789";

$post = [
    
"email" => "johndoe@gmail.com",
    
"order" => "order123",
    
"language" => "en",
    
"delay" => 0,
    
"customer_name" => "Jan Jansen",
    
"phone_numbers" => ["+31612345678"],
    
"order_total" => 1500.99,
    
"client" => "wordpress",
    
"platform_version" => "wp-4.9.2-wc-3.2.6",
    
"plugin_version" => "1.6.0",
];

$curl curl_init("https://dashboard.webwinkelkeur.nl/api/1.0/invitations.json?id=".$id."&code=".$code);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
    
CURLOPT_POST => true,
    
CURLOPT_POSTFIELDS => http_build_query($post)
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data zal er ongeveer zo uitzien:

    $data = [
        "status" => "success",
        "message" => "Invitation successfully added to queue!"
    ];
    */
} else {
    
// Er is een fout ontstaan
}
?>

UITNODIGINGEN OPHALEN

Gebruik een GET request om een lijst van datumgesorteerde (nieuwste bovenaan) uitnodigingen te krijgen.

URL

GET /1.0/invitations.json

GET
parameters
Veld Voorbeeld Standaard Beschrijving
id 1 Verplicht De ID van de webwinkel.
code "123456789abc123456789" Verplicht Je persoonlijke API code.
offset 0 0 Offset van de uitnodigingen. Bijvoorbeeld: een offset van 10 betekent dat de eerste 10 uitnodigingen uitgesloten worden.
order 10 10 Het maximum aantal opgehaalde uitnodigingen. De mogelijke waardes liggen tussen 1 - 100.
Antwoord
JSON

Het antwoord zal een JSON gecodeerd object met 3 waardes bevatten: status, message en invitations.

{
    "status": "success",
    "message": "Invitations successfully retrieved!",
    "invitations": [{
        "email": "john.doe@example.com",
        "order": "",
        "delay": 0,
        "datetimes": {
            "created": "2019-12-05 12:06:13",
            "scheduled": "2019-12-05 12:06:13",
            "sent": "2019-12-05 13:36:13"
        }
    }, {
        "email": "jane.doe@example.com",
        "order": "5468",
        "delay": 2,
        "datetimes": {
            "created": "2019-12-05 12:06:13",
            "scheduled": "2019-12-07 12:06:13",
            "sent": false
        }
    }]
}

De volgende combinaties van status, message en invitations zijn mogelijk:

status message invitations Uitleg
success Invitations successfully retrieved! Zie voorbeeld De uitnodigingen zijn succesvol opgehaald.
error Not all obligated variables are set. [ ] Één of meer van de vereiste variabelen (id, code en/of email) werden niet meegegeven.
error Incorrect authentication credentials. [ ] De combinatie van id en code is incorrect.
error Unexpected error while processing. Please contact WebwinkelKeur. [ ] Een onbekende fout is opgetreden. Deze kan waarschijnlijk alleen door het WebwinkelKeur opgelost worden.
PHP cURL
voorbeeld
<?php
$id 
1;
$code "123456789abc123456789";
$offset 0;
$order 10;

$curl curl_init("https://dashboard.webwinkelkeur.nl/api/1.0/invitations.json?id=".$id."&code=".$code."&offset=".$offset."&order=".$order);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data zal er ongeveer zo uitzien:

    $data = [
        "status" => "success",
        "message" => "Invitations successfully retrieved!",
        "invitations" => Zie voorbeeld
    ];
    */
} else {
    
// Er is een fout ontstaan
}
?>

BEOORDELINGEN OPHALEN

Gebruik een GET request om een lijst van datumgesorteerde (nieuwste bovenaan) ervaringen te krijgen.

URL

GET /1.0/ratings.json

GET
parameters
Veld Voorbeeld Standaard Beschrijving
id 1 Verplicht De ID van de webwinkel.
code "123456789abc123456789" Verplicht Je persoonlijke API code.
offset 0 0 Offset van de beoordelingen. Bijvoorbeeld: een offset van 10 betekent dat de eerste 10 beoordelingen uitgesloten worden.
limit 10 10 Het maximum aantal opgehaalde ervaringen. De mogelijke waardes liggen tussen 1 - 100.
Antwoord
JSON

Het antwoord zal een JSON gecodeerd object met 3 waardes bevatten: status, message en ratings.

{
    "status: "success",
    "message": "Ratings successfully retrieved!",
    "ratings": [{
        "name": "J. Doe",
        "email": "john.doe@example.com",
        "rating": 4,
        "ratings": {
            "shippingtime": 5,
            "customerservice": 3,
            "pricequality": 4,
            "aftersale": 4
        },
        "comment": "Fantastisch product, hele mooie webwinkel!",
        "date": "2016-02-14",
        "created": "2016-02-14 19:08:00",
        "read": false,
        "quarantine": false
    }, {
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "rating": 1,
        "ratings": {
            "shippingtime": 1,
            "customerservice": 2,
            "pricequality": 4,
            "aftersale": 1
        },
        "comment": null,
        "date": "2016-02-12",
        "created": "2016-02-12 12:34:12",
        "read": true,
        "quarantine": true
    }]
}

De volgende combinaties van status, message en ratings zijn mogelijk:

status message ratings Uitleg
success Ratings successfully retrieved! Zie voorbeeld De beoordelingen zijn succesvol opgehaald.
error Not all obligated variables are set. [ ] Één of meer van de vereiste variabelen (id, code en/of email) werden niet meegegeven.
error Incorrect authentication credentials. [ ] De combinatie van id en code is incorrect.
error Unexpected error while processing. Please contact WebwinkelKeur. [ ] Een onbekende fout is opgetreden. Deze kan waarschijnlijk alleen door het WebwinkelKeur opgelost worden.
PHP cURL
voorbeeld
<?php
$id 
1;
$code "123456789abc123456789";
$offset 0;
$limit 10;

$curl curl_init("https://dashboard.webwinkelkeur.nl/api/1.0/ratings.json?id=".$id."&code=".$code."&offset=".$offset."&limit=".$limit);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data zal er ongeveer zo uitzien:

    $data = [
        "status" => "success",
        "message" => "Ratings successfully retrieved!",
        "ratings" => Zie voorbeeld
    ];
    */
} else {
    
// Er is een fout ontstaan
}
?>

BEOORDELINGEN SAMENVATTING OPHALEN

Gebruik een GET request om een samenvatting van alle ervaringen op te halen.

URL

GET /1.0/ratings_summary.json

GET
parameters
Veld Voorbeeld Standaard Beschrijving
id 1 Verplicht De ID van de webwinkel.
code "123456789abc123456789" Verplicht Je persoonlijke API code.
Antwoord
JSON

Het antwoord zal een JSON gecodeerd object met 3 waardes bevatten: status, message en data.

{
    status: "success",
    message: "Rating summary successfully retrieved!",
    data: {
        amount: 26,
        rating_average: 4.194546,
        ratings_average: {
            shippingtime: 4.851756,
            customerservice: 4.658711,
            pricequality: 3.678985,
            aftersale: 4.087224
        }
    }
}

De volgende combinaties van status, message en data zijn mogelijk:

status message data Uitleg
success Ratings summary successfully retrieved! Zie voorbeeld De uitnodigingen zijn succesvol opgehaald.
error Not all obligated variables are set. null Één of meer van de vereiste variabelen (id, code en/of email) werden niet meegegeven.
error Incorrect authentication credentials. null De combinatie van id en code is incorrect.
error Unexpected error while processing. Please contact WebwinkelKeur. null Een onbekende fout is opgetreden. Deze kan waarschijnlijk alleen door het WebwinkelKeur opgelost worden.
PHP cURL
voorbeeld
<?php
$id 
1;
$code "123456789abc123456789";

$curl curl_init("https://dashboard.webwinkelkeur.nl/api/1.0/ratings_summary.json?id=".$id."&code=".$code);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data zal er ongeveer zo uitzien:

    $data = [
        "status" => "success",
        "message" => "Ratings summary successfully retrieved!",
        "data" => Zie voorbeeld
    ];
    */
} else {
    
// Er is een fout ontstaan
}
?>

WEBWINKELS OPHALEN

Gebruik een GET request om meer informatie over de webwinkel op te halen.

URL

GET /1.0/webshop.json

GET
parameters
Veld Voorbeeld Standaard Beschrijving
id 1 Verplicht De ID van de webwinkel.
code "123456789abc123456789" Verplicht Je persoonlijke API code.
Antwoord
JSON

Het antwoord zal een JSON gecodeerd object met 3 waardes bevatten: status, message en data.

{
    "status": "success",
    "message": "Webshop details successfully retrieved!",
    "data": {
        "name": "Webshop.com",
        "address": {
            "street": "Stationsweg",
            "housenumber": "1A",
            "postalcode": "1234AB",
            "city": "Amsterdam"
        },
        "logo": "https://dashboard.webwinkelkeur.nl/img/uploads/logos/1/valuedshops.png",
        "languages": [{
            "name": "Dutch",
            "url": "https://www.webwinkelkeur.nl/leden/WebwinkelKeurnl-Test_1_3.html",
            "iso": "nl",
            "all": true,
            "main": true
        }, {
            "name": "English",
            "url": "https://www.valuedshops.com/members/WebwinkelKeurnl-Test_1_3.html",
            "iso": "en",
            "all": false,
            "main": false
        }]
    }
}

De volgende combinaties van status, message en data zijn mogelijk:

status message data Uitleg
success Webshop details successfully retrieved! Zie voorbeeld De webwinkel is succesvol opgehaald.
error Incorrect authentication credentials. [ ] De combinatie van id en code is incorrect.
error Unexpected error while processing. Please contact WebwinkelKeur. [ ] Een onbekende fout is opgetreden. Deze kan waarschijnlijk alleen door het WebwinkelKeur opgelost worden.
PHP cURL
voorbeeld
<?php
$id 
1;
$code "123456789abc123456789";

$curl curl_init("https://dashboard.webwinkelkeur.nl/api/1.0/webshop.json?id=".$id."&code=".$code);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data zal er ongeveer zo uitzien:

    $data = [
        "status" => "success",
        "message" => "Webshop details successfully retrieved!",
        "data" => Zie voorbeeld
    ];
    */
} else {
    
// Er is een fout ontstaan
}
?>

JAVASCRIPT SIDEBAR + TOOLTIP

Onze sidebar en tooltips kunnen geprogrammeerd worden door de juiste JavaScript-variabelen te wijzigen. Houd er rekening mee dat beide ook zonder programmeerkennis van de betreffende pagina's binnen de dashboard geconfigureerd kunnen worden. De JavaScript-variabelen overschrijven altijd elke configuratie die via het dashboard is ingesteld, daarom raden we aan om de configuratieoptie in het dashboard te gebruiken als je wilt dat deze op alle pagina's van toepassing is.

SIDEBAR De sidebar is een klein maar krachtig element dat tegen de zijkant van de browser wordt weergegeven. Door erop te klikken kan een popup worden geopend. Deze geeft gedetailleerde informatie, klantervaringen en nog veel meer weer over de webwinkel.

TOOLTIP De tooltip verschijnt wanneer de muis over een element met de volgende klasse "webwinkelkeurPopup", "webwinkelkeurReviews" en "webwinkelkeurAddReview" gaat of over een widget beweegt. Wanneer u op een van deze elementen klikt, verschijnt er een popup.

Code
<script>
  _webwinkelkeur_id = <het ID van de webwinkel>
  //_webwinkelkeur_language = <webwinkel's standaard>
  //_webwinkelkeur_sidebar = true;
  //_webwinkelkeur_sidebar_position = "left";
  //_webwinkelkeur_sidebar_top = "300";
  //_webwinkelkeur_sidebar_theme = "dark";
  //_webwinkelkeur_mobile = "bottom";
  //_webwinkelkeur_mobile_tab = "left";
  //_webwinkelkeur_tooltip = true;
  //_webwinkelkeur_language = <webwinkel's standaard>;
</script>
<script async src="https://www.webwinkelkeur.nl/js/sidebar.js"></script>

De code toont de zijbalk en maakt het mogelijk om de tooltips op pagina's te laden. Het bevat al de enige vereiste variabele: _webwinkelkeur_id en heeft alle optionele configuratievariabelen becommentarieerd. Je dient dit aan te passen naar de ID van de webshop waarvan je de sidebar wil tonen.

Tooltip

Elk element (bij voorkeur <a> elementen) dat in een 'webwinkelkeurPopup', 'webwinkelkeurReviews' of 'webwinkelkeurAddReview' class wordt gegeven, zal een WebwinkelKeur tooltip laten zien als je eroverheen gaat met de muis. Je zit je score, het aantal recensies en de review badge. Bij een muisklik wordt een popup getoond die of gelijk is aan de sidebar's popup of de consument de mogelijkheid geeft zijn/haar ervaring direct te delen. Dit hangt af van de gekozen class, zie onderstaand voor meer informatie.

Let op! Indien je de tooltip uitgeschakeld hebt wordt bij het klikken op elementen met één van de onderstaande classes nog steeds de bijbehorende popup getoond.

webwinkelkeurPopup class

Opent de sidebar's popup die zowel WebwinkelKeur's uitgangspunten en de webwinkelgegevens toont. Net zoals de sidebar's popup biedt het de consument de mogelijkheid om de webwinkel's beoordelingen te bekijken zonder de popup te verlaten.

Voorbeeld <a href="#" class="webwinkelkeurPopup">Wij zijn geverifieerd door WebwinkelKeur</a>

webwinkelkeurReviews class

Opent de sidebar's popup en toont de reviews. Net zoals de sidebar's popup biedt het de consument de mogelijkheid WebwinkelKeur's uitgangspunten en webwinkelgegevens te bekijken zonder de popup te verlaten.

Voorbeeld <a href="#" class="webwinkelkeurReviews">Bekijk reviews</a>

webwinkelkeurAddReview class

Opent een popup met een formulier waarmee een consument zijn ervaring kan delen. Deze popup is vergelijkbaar met de popup die wordt weergegeven wanneer u op "Hoe beoordeel je deze webwinkel?" op je ledenpagina klikt.

Voorbeeld <a href="#" class="webwinkelkeurAddReview">Hoe beoordeel je deze webwinkel?</a>
Variabelen
Naam Waardes Standaard Beschrijving
_webwinkelkeur_id Numeriek Verplicht De ID van de webwinkel waarvoor je de sidebar wilt weergeven.
_webwinkelkeur_sidebar true of false true Activeert de sidebar.
_webwinkelkeur_sidebar_position "left" of "right" "left" Aan welke kant van het scherm de niet-mobiele sidebar getoond moet worden.
_webwinkelkeur_sidebar_top String met de hoeveelheid in pixels (bijv. "100") of een percentage (bijv. "20%") "300" De hoeveelheid offset vanaf de bovenkant van het scherm.
_webwinkelkeur_sidebar_theme "dark" of "light" "dark" Het thema van de sidebar.
_webwinkelkeur_sidebar_mobile "top", "top_left", "top_right", "top_manual", "bottom", "bottom_left", "bottom_right", "bottom_manual" of "none" "bottom" Activeert de sidebar voor mobiele bezoekers, en zo ja, waar het tabblad geplaatst wordt. Wanneer de mobiele sidebar in de eerste instantie wordt weergegeven is alleen een klein tabblad zichtbaar. Door op het tabblad te klikken schuift de sidebar in het scherm en wordt meer informatie weergegeven.
_webwinkelkeur_mobile_tab "left", "center" or "right" "left" Verandert de positie van de mobiele zijbalk, gebaseerd op de breedte van de tooltip.
_webwinkelkeur_tooltip true of false true Activeert de tooltip.
_webwinkelkeur_language De ISO-639-3 waarde van een van onze ondersteunde talen (bijv. "nld"), "url", "html" of "browser" <webwinkel's standaard> De taal van de sidebar en zijn popup. Naast het instellen van een specifieke taal, kun je ons ook laten bepalen welke taal het beste is a.d.v. de url ("url"), het language attribuut ("html") of de geprefereerde taal van de bezoeker ("browser").

JAVASCRIPT WIDGET

Onze widget stelt je in staat je klantervaringen direct op je webwinkel weer te geven. De kleur en ander fysieke eigenschappen zijn aanpasbaar zodat je de stijl van je webwinkel kunt matchen. We raden je aan de widget configuratie binnen het dashboard te gebruiken, ook als ondersteunende tool voor de programmatische configuratie.

Code
<iframe src="https://staging2.webwinkelkeur.nl/webshops/widget_html?id=<het ID van de webwinkel>&layout=new_default&theme=dark&color=%23ea0e8b&show=yes&view=slider&amount=6&width=manual&width_amount=280px&height=250px&interval=5000&language=nld" scrolling="no" class="wwk-widget-iframe wwk-widget--new_default wwk-widget--new_default--dark" style="border: 0; height: 250px!important; width: 280px!important;"></iframe>

De code plaatst de widget op de locatie waar de code geplaatst is. Je moet <het ID van de webwinkel> vervangen met het ID van de webwinkel waarvoor je de widget wilt tonen.
De breedte en hoogte van het iframe moeten worden gewijzigd, gebaseerd op de afmetingen van de widget. Ze moeten dezelfde zijn als de parameters.

Parameters
Naam Waardes Standaard Beschrijving Layouts
id Numeriek Verplicht De ID van de webwinkel waarvoor je de widget wilt tonen. Alle
layout "new_default", "new_badges" etc. Verplicht De layout van de widget. Alle
theme "light" of "dark" Verplicht Het type thema/achtergrond. new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
color String met CSS kleurcode (bijv. "#ea0e8b" of "rgb(234, 14, 139)") Verplicht De kleur van de prominente elementen van de widget. new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
show "yes" of "no" Verplicht Het tonen van klantervaringen. Indien niet ingeschakeld wordt de widget in hoogte verkleind. new_default
view "slider" of "list" Verplicht De methode waarmee de klantervaringen getoond worden. new_default
amount Numeriek (1-6 schaal) Verplicht De hoeveelheid klantervaringen die getoond worden. new_default
width "auto" of "manual" Verplicht De breedte van de widget; ofwel vullen ("auto") of vast/percentueel ("manual"). new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
width_amount String met CSS breedte (bijv. "100px" of "70%") Verplicht De breedte in het geval breedte is ingesteld op "handmatig". new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
height Numeriek Verplicht Hoogte van de widget in pixels. Alle
interval Numeriek Verplicht Het aantal milliseconden voor het overschakelen naar de volgende klantbeoordeling wanneer weergave is ingesteld op "slider". new_default
language Numeriek Verplicht De taal van de widget. De volgende waardes kunnen gebruikt worden:
"nld" (Nederlands)
"eng" (Engels)
"deu" (Duits)
"fra" (Frans)
"spa" (Spaans)
"ita" (Italian)
Je hebt een PRO-pakket nodig en de taal ingeschakeld hebben voor je webwinkel. Anders wordt de taal teruggezet op Engels.
new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon