Docs

Embed-widget

Voeg dit script toe aan elke pagina. Maak een embed-key in het dashboard onder Embed.

<script
  src="https://fynd.chat/widget/fynd.js"
  data-key="YOUR_EMBED_KEY"
  data-bot="default"
  async></script>

• data-key: shop embed-key (pk_live_…)
• data-bot: bot-slug (standaardbot indien weggelaten)
• data-position: launcher-kant: right (standaard) of left
• data-launcher: launcher-emoji / label (standaard 💬)
• data-launcher-icon: optionele afbeeldings-URL voor de launcher-knop
• data-locale: optionele UI-locale override (bijv. nl, en)
• data-api: optionele API-base override

De publieke embed-key (pk_live_…) mag in de browser. Zet nooit een sk_live catalogus-key in frontend-code.

Catalog REST API

Push producten naar Fynd als alternatief of aanvulling op sitemap en feeds. Geïndexeerde producten voeden aanbevelingen, prijzen en productkaarten in de chat.

Authenticeer met Authorization: Bearer sk_live_…

Base URL: https://fynd.chat/api/v1/catalog

Maak een key aan onder API-keys in het dashboard (Growth+). De volledige key wordt één keer getoond. Bewaar hem veilig. Planlimieten gelden voor producten en API-keys (402 bij overschrijding).

Endpoints

• GET /products: lijst / zoeken (q, page, bot)
• PUT /products/{external_id}: één product aanmaken of bijwerken
• POST /products/bulk: bulk upsert (max 500 per request)
• DELETE /products/{external_id}: soft-delete (available: false)
• POST /sync: alle beschikbare producten opnieuw indexeren voor search / RAG

Schrijven gaat standaard naar de shop-brede (shared) catalogus. Voeg ?bot=slug toe voor een bot-specifieke overlay (overschrijft shared bij dezelfde external_id).

Productvelden

Voorbeeld: upsert

curl -X PUT https://fynd.chat/api/v1/catalog/products/MBP-14 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MacBook Pro 14\"",
    "description": "Powerful laptop for pros",
    "price": 1999,
    "currency": "EUR",
    "product_url": "https://shop.example/macbook-pro-14",
    "image_url": "https://shop.example/mbp.jpg",
    "category": "Laptops",
    "attributes": {"ram": "16GB"},
    "available": true
  }'

Voorbeeld: bulk

curl -X POST https://fynd.chat/api/v1/catalog/products/bulk \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "external_id": "SKU-1",
        "title": "Product A",
        "price": 49.99,
        "currency": "EUR",
        "product_url": "https://shop.example/a"
      },
      {
        "external_id": "SKU-2",
        "title": "Product B",
        "price": 79.00,
        "currency": "EUR",
        "product_url": "https://shop.example/b"
      }
    ]
  }'

Voorbeeld: zoeken, overlay, delete & sync

# Zoeken
curl "https://fynd.chat/api/v1/catalog/products?q=macbook&page=1" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Bot-overlay
curl -X PUT "https://fynd.chat/api/v1/catalog/products/MBP-14?bot=default" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"MacBook Pro 14\" (bot)","price":1899,"currency":"EUR"}'

# Soft-delete
curl -X DELETE https://fynd.chat/api/v1/catalog/products/MBP-14 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Opnieuw indexeren
curl -X POST https://fynd.chat/api/v1/catalog/sync \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Kennisbronnen

Naast de Catalog API sync je kennis vanuit het dashboard, zonder code.

• Custom knowledge: plak FAQ’s, policies en tips (alle plannen)
• Sitemap-crawl: elke URL wordt een sync-regel die je kunt volgen (Growth+)
• Productfeed XML/CSV: URL of upload (Growth+)
• REST pull: haal een remote catalogus op schema binnen (Growth+)
• Catalog push API: de REST-endpoints hierboven (Growth+)

Rate limits

Catalog API en widget hebben throttles per key en IP om misbruik te voorkomen.

• Catalog API: 120 requests / minuut per API-key, 60 / minuut per IP.
• Widget config/events: 120 requests / minuut per embed-key, 60 / minuut per IP.
• Widget chat: 20 berichten / minuut per embed-key, 10 / minuut per IP (lager op de publieke demo).
• Planlimieten (berichten, producten, bots) gelden naast technische throttles.

Foutcodes

API-fouten komen terug als JSON met een duidelijke statuscode.

• 401: ontbrekende of ongeldige API-key
• 402: plan- / licentielimiet bereikt (producten, feature)
• 403: geen toegang tot deze shop of feature
• 404: product of bot niet gevonden
• 422: validatiefout in de payload
• 429: rate limit bereikt; retry later

Widget events

De embed-widget stuurt allowlisted analytics events naar je shop-dashboard.

• widget_open: bezoeker opent de adviseur
• message_sent: bezoeker stuurt een bericht
• product_click: bezoeker klikt een aangeraden product
• lead_submit: bezoeker laat contactgegevens achter