Toon Klusio blogs op je eigen website

Wat gebeurt er precies?

Snelle start

1. Maak ingelogd een API-key aan bij Instellingen → API.
2. Kopieer de key meteen; Klusio toont hem maar één keer volledig.
3. Laat je website de key op de server meesturen.
4. Vraag eerst één artikel op en controleer daarna de vormgeving.

Basisadres

Eerste test met cURL

curl --request GET \
  --url "https://klusio.nl/api/v1/blogs?company_id=JOUW_BEDRIJFS_ID&limit=1" \
  --header "X-API-Key: JOUW_API_KEY"

Een geslaagde request geeft HTTP-status 200 en begint met {"success":true.

API-key veilig gebruiken

Een API-key werkt als een wachtwoord voor de koppeling. Stuur hem bij voorkeur mee met de header X-API-Key. Een Bearer-header wordt ook ondersteund.

X-API-Key: JOUW_API_KEY

# Alternatief
Authorization: Bearer JOUW_API_KEY

• Geef iedere website of koppeling een eigen key met een herkenbare naam.
• Schakel een key uit wanneer een koppeling tijdelijk stopt.
• Verwijder en vervang een key die mogelijk is uitgelekt.
• Gebruik een vervaldatum voor tijdelijke externe toegang.

Welke gegevens kun je opvragen?

Gebruik per request één hoofdkeuze: een lijst, één artikel, een topic, een pillar of gerelateerde artikelen. Combineer slug, topic_id, pillar_url en related_to niet; de API weigert zo'n dubbelzinnige request met HTTP 400.

Parameters voor lijsten

Elk artikel in een lijst heeft ook url (het volledige adres in de vorm van je site), updated_at, topic_id, author_id en noindex.

Zo ziet een response eruit

Lijst met artikelen

{
  "success": true,
  "total": 75,
  "limit": 1,
  "offset": 0,
  "posts": [{
    "id": 2042,
    "slug": "voorbeeld-artikel",
    "title": "Voorbeeldtitel",
    "meta_description": "Korte omschrijving voor Google.",
    "featured_image": "https://voorbeeld.nl/afbeelding.webp",
    "featured_image_alt": "Beschrijving van de afbeelding",
    "author": "Naam auteur",
    "published_at": "2026-08-12 09:00:00",
    "reading_time": 6,
    "views_count": 123,
    "is_indexed": true,
    "content_type": "how_to_guide"
  }],
  "reviews": {
    "google_rating": 4.8,
    "total_reviews": 47,
    "rating_distribution": {"5":42,"4":3,"3":1,"2":0,"1":1},
    "business_name": "Voorbeeldbedrijf",
    "latest_reviews": []
  },
  "filters_applied": {
    "search": null,
    "sort": "recent",
    "visibility": {"min_views":0,"require_indexed":false,"hide_after_days":null}
  }
}

De lijst bevat bewust geen volledige artikeltekst. Vraag een artikel daarna op via slug.

Eén volledig artikel

De single-post response bevat post met onder andere content, meta_description, featured_image, cta_text, cta_link, topicvelden en eventuele FAQ-, HowTo- en claimdata. Daarnaast krijg je:

• author_details en reviewer_details voor zichtbare expertiseblokken;
• schema_markup en seo_head voor correcte SEO-uitvoer;
• pillar_post wanneer het artikel aan een hoofdpagina is gekoppeld;
• tracking_script en tracking_token voor veilige paginameting;
• reviews met de laatst gesynchroniseerde Google Reviews.

Compleet PHP-voorbeeld

Dit voorbeeld haalt op de server vijf blogs op. De API-key staat in een environment variable en komt dus niet in de browser terecht.

<?php
$apiKey = getenv('KLUSIO_API_KEY');
$url = 'https://klusio.nl/api/v1/blogs?company_id=JOUW_BEDRIJFS_ID&limit=5&sort=recent';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: ' . $apiKey,
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);

if ($body === false || $curlError !== '') {
    throw new RuntimeException('Klusio API is niet bereikbaar: ' . $curlError);
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200 || empty($data['success'])) {
    throw new RuntimeException($data['error'] ?? 'Onbekende API-fout');
}

foreach ($data['posts'] as $post) {
    echo '<a href="/blog/' . rawurlencode($post['slug']) . '">';
    echo htmlspecialchars($post['title'], ENT_QUOTES, 'UTF-8');
    echo '</a>';
}

Artikelweergaven meten

Vraag je één artikel via slug op, dan levert Klusio een kant-en-klaar tracking_script. Dat script gebruikt een kortlevend token dat alleen bij dat artikel en bedrijf past.

// Na een geslaagde single-post request:
echo $data['post']['content'];
echo $data['tracking_script']; // bij voorkeur vlak voor </body>

Voor een eigen implementatie stuur je een POST naar https://klusio.nl/api/v1/track met post_id, company_id en de ontvangen tracking_token. Optioneel zijn visitor_id, time_spent, scroll_depth, referrer en converted.

Statische pagina's of een eigen cache

Bouwt je site de artikelen zelf als pagina's op de server, haal een artikel dan op met count_view=0: dat ophalen is geen lezer. Geef de meting van de lezer door vanaf je eigen server met dezelfde POST, maar met de API-key in X-API-Key in plaats van tracking_token. Klusio bewaart dan geen IP-adres en browser van je server. Zet de API-key nooit in de browser.

Heeft je site een synchronisatieadres (bijvoorbeeld /klusio/sync.php), dan roept Klusio dat aan vlak voor de controle of een nieuw of vernieuwd artikel live staat. Laat Klusio dat adres instellen.

Artikelen in andere talen

Zet het bedrijf in Klusio bij Blog › Instellingen een taal aan, dan vertaalt Klusio elk nieuw goedgekeurd artikel en zet het in de API met lang. Dat kan vanaf Groei Pro. De inhoud is dezelfde als in het Nederlands; Klusio controleert de vertaling op betekenis, cijfers, namen en links.

Elk artikel heeft language en translations: per vertaling de taal, slug, titel, url en live. Een los artikel heeft ook alternates (hreflang naar adres), en seo_head bevat dezelfde regels.

"language": "nl",
"translations": [
  {
    "language": "en",
    "slug": "how-to-choose-a-roofer",
    "title": "How to choose a roofer",
    "url": "https://voorbeeld.nl/en/blog/how-to-choose-a-roofer/",
    "live": false
  }
]

Zo zet je ze op je website

Toon de vertaling onder het adres dat in url staat. Dat adres kiest het bedrijf in Blog › Instellingen; standaard is het /en/blog/<slug>/. Een taalkeuze op de pagina maak je met translations.

Herkenbaar AI-verkeer meten

Doorkliks vanuit AI-assistenten en bezoeken van AI-crawlers geef je vanaf je eigen server door met POST /api/v1/ai-traffic. Klusio heeft hiervoor geen WordPress-plugin. Stuur de API-key via X-API-Key. Klusio accepteert alleen herkenbare AI-referrals en AI-user-agents; een gewone Googlebot, Bingbot of zoekmachinereferral telt niet als AI.

{
  "event_type": "crawler",
  "event_key": "unieke-idempotency-key-per-request",
  "landing_url": "https://voorbeeld.nl/dienstpagina",
  "user_agent": "OAI-SearchBot/1.0"
}

Google Reviews

Responses bevatten het laatst gesynchroniseerde reviewoverzicht: gemiddelde beoordeling, aantal reviews, verdeling per ster, bedrijfsnaam en maximaal tien zichtbare recente reviews. Deze gegevens zijn niet live per seconde; Klusio ververst ze periodiek, normaal dagelijks.

Fouten begrijpen

Elke fout bevat success: false, een leesbare error, een vaste error_code en een request_id. Geef dat request-ID door aan support; technische serverdetails blijven veilig in de log.

{
  "success": false,
  "error": "Een geldige API-key is verplicht. Gebruik de X-API-Key-header.",
  "error_code": "invalid_api_key",
  "request_id": "a1b2c3d4e5f60708"
}

Limieten en caching

Nieuwe keys starten standaard op 100 requests per uur. In API-beheer kun je per key een limiet van 1 tot 1.000 instellen. Na geldige authenticatie zie je het verbruik in deze responseheaders:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1786525200

• Cache een artikellijst 5 tot 15 minuten.
• Cache een volledig artikel tot maximaal één uur.
• Vraag Google Reviews niet vaker dan dagelijks opnieuw op.
• Gebruik bij HTTP 429 de header Retry-After; blijf niet direct opnieuw proberen.

Bestaande koppelingen

Het oude endpoint /api/blog.php blijft voorlopig bestaan zodat huidige websites niet onverwacht uitvallen. Nieuwe koppelingen horen altijd /api/v1/blogs te gebruiken. V1 heeft verplichte authenticatie, vaste validatie en voorspelbare foutcodes.

Kom je er niet uit?

Stuur naar support@klusio.nl: je company_id, het gebruikte endpoint, de HTTP-status, het request_id en het tijdstip. Stuur nooit je volledige API-key mee.