API documentatie - NKB Winkels

Publieke API voor deelnemende kringloopwinkels. Base URL: https://winkels.denationalekringloopbon.nl

Authenticatie

GET /api/stores vereist een applicatie-API-key. Maak keys aan in het admin-dashboard onder API Keys (één key per applicatie, bijv. denationalekringloopbon.nl).

curl 'https://winkels.denationalekringloopbon.nl/api/stores?limit=20' \
  -H 'Authorization: Bearer wkb_…'

De publieke HTML-pagina op /winkels gebruikt server-side data en client-side zoeken — geen API-key nodig voor bezoekers.

Integratie-advies

Gebruik altijd server-side zoeken en paginering via query parameters. Haal niet de volledige lijst op om client-side te filteren of pagineren.

Zoeken: stuur q (of search) mee — filtering en query-logging gebeuren op de server.
Paginering: gebruik limit en offset voor elke pagina. Lees X-Total-Count uit de response headers voor het totaal aantal treffers.
Debouncing: wacht ~300–500 ms na typen voordat je een zoek-request stuurt.
Caching: cache alleen requests zonder q, limit of offset.

Endpoints

GET /api/stores

Alle gepubliceerde winkels. Dit is de canonical winkel-API — de hoofdsite en andere frontends halen hier hun data vandaan.

Query	Beschrijving
`q` of `search`	Filter op naam, plaats, adres of categorie. Logt de zoekopdracht server-side (source: `api` of `?source=`).
`limit`	Maximaal aantal resultaten per pagina (1–100). Gebruik dit voor server-side paginering.
`offset`	Aantal over te slaan resultaten (standaard `0`). Combineer met `limit` voor volgende pagina's.

# Eerste pagina (20 resultaten)
curl 'https://winkels.denationalekringloopbon.nl/api/stores?limit=20&offset=0' \
  -H 'Authorization: Bearer wkb_JOUW_KEY'

# Zoeken + paginering
curl 'https://winkels.denationalekringloopbon.nl/api/stores?q=amsterdam&limit=20&offset=0' \
  -H 'Authorization: Bearer wkb_JOUW_KEY'

# Volgende pagina
curl 'https://winkels.denationalekringloopbon.nl/api/stores?q=amsterdam&limit=20&offset=20'

Response: JSON-array. Met limit bevat de response ook headers X-Total-Count, X-Offset en X-Limit. CORS: open (*). Zoekopdrachten worden server-side gelogd in D1.

POST /api/search-log

Publiek logging-endpoint voor zoekopdrachten op de HTML-pagina /winkels. Geen API-key nodig. Body (JSON):

{
  "query": "amsterdam",
  "result_count": 12,
  "source": "winkels-site",
  "referer": "https://www.denationalekringloopbon.nl/winkels"
}

source standaard winkels-site; override via body, query ?source= of header X-Winkels-Source. Minimaal 2 tekens in query.

Store object

Standaardvelden hieronder. Extra custom velden stel je in via het admin-dashboard. Per veld kun je kiezen of het op root-niveau in GET /api/stores wordt meegestuurd (bijv. shopify_product_id, shopify_component_id).

{
  "id": "uuid",
  "name": "055Fashion",
  "slug": "055fashion",
  "address": "Schotweg 4-b, Apeldoorn",
  "city": "Apeldoorn",
  "postal_code": "7311DT",
  "phone": "06 51036369",
  "email": "info@example.nl",
  "website": "https://www.example.nl",
  "latitude": 52.21,
  "longitude": 5.95,
  "categories": ["Tweedehands kledingwinkel"],
  "store_type": "winkel",
  "image_url": "https://…",
  "description": "<p>HTML beschrijving</p>",
  "status": "published",
  "participates_nkb": true,
  "has_action": false,
  "action_description": null,
  "shopify_product_id": "9858703425869",
  "shopify_component_id": "1732359086467"
}

Pagina's

GET / — Winkeloverzicht (HTML)
GET /winkels — Alias voor winkeloverzicht
GET /api/docs — Deze documentatie
GET /admin/dashboard/api-keys — Admin (API keys beheren)

Bron van data

winkels.denationalekringloopbon.nl is de bron van waarheid voor winkeldata. De database (D1) wordt beheerd via het admin-dashboard of het CRM. Andere websites — waaronder denationalekringloopbon.nl — consumeren GET /api/stores van dit domein. Er is geen automatische import meer vanuit de oude NKB-site; bewerkingen blijven behouden.