Catalog API met sk_live-sleutel

Een catalogus-API koppelen met een sk_live-sleutel

Wanneer je de Catalog API gebruikt

De Fynd Catalog API is geschikt wanneer productdata in een systeem staat dat die rechtstreeks kan aanbieden, in plaats van een XML- of CSV-feed te publiceren. Een API-koppeling past bij custom storefronts, headless commerce, PIM-systemen, ERP-integraties of interne catalogusdiensten. Je integratie stuurt dan gestructureerde productkennis naar Fynd via geauthenticeerde verzoeken.

Gebruik de Catalog API voor catalogusfeiten zoals identifiers, titels, beschrijvingen, prijzen, voorraadstatus, product-URL’s, afbeeldingen, merken, categorieën en variantinformatie. Gebruik custom knowledge FAQs voor blijvende vragen die geen individueel productrecord zijn, zoals verzendinformatie of uitleg over een winkelbeleid. Gebruik een sitemap-crawl voor publieke redactionele pagina’s waarvan BlogPosting- of Article JSON-LD moet worden gevonden.

API-verzoeken gebruiken een live secret key in een Bearer-autorisatieheader. Een sleutel met het voorvoegsel sk_live is een geheime inloggegeven. Behandel deze als een wachtwoord: de sleutel kan wijzigingen aan je live cataloguskoppeling autoriseren.

Maak en bewaar het geheim veilig

Maak de live secret aan in het onderdeel voor API-sleutels in de Fynd-instellingen. Kopieer de sleutel alleen naar een veilige secret manager, deploymentsgeheim of versleutelde omgevingsvariabele. Plaats hem niet in een openbaar issue, frontendbundle, productfeed, browserscript of repository.

Bewaar de sleutel onder een duidelijke naam:

FYND_CATALOG_API_KEY=sk_live_vervang_dit_door_uw_geheim

Het voorvoegsel sk_live identificeert een live secret; het is geen waarde die je op zichzelf verstuurt. Gebruik de volledige sleutel die voor je workspace is gegenereerd. Is een sleutel zichtbaar geworden, trek hem dan direct in of roteer hem in Fynd, vervang het opgeslagen geheim en deploy opnieuw. Verwijder niet alleen een logregel: een eenmaal blootgesteld geheim moet als gecompromitteerd worden beschouwd.

Beperk toegang tot de sleutel tot de dienst of deploymentomgeving die de catalogus synchroniseert. Een browser mag hem nooit ontvangen. Iemand die client-side JavaScript of netwerkverzoeken kan inspecteren, mag je live sleutel niet kunnen achterhalen.

Verzoeken authenticeren

Stuur de sleutel in de gebruikelijke HTTP-header Authorization met het Bearer-schema:

curl -X POST "https://api.fynd.example/catalog" \
  -H "Authorization: Bearer $FYND_CATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @catalog-payload.json

Gebruik het daadwerkelijke endpoint en requestformaat uit je Fynd-API-documentatie of integratieconfiguratie. Het voorbeeld laat het authenticatiepatroon zien en vervangt niet het endpointcontract. Het belangrijke onderdeel is:

Authorization: Bearer sk_live_...

Gebruik geen queryparameter als ?api_key=. Querystrings komen gemakkelijk terecht in access logs, analysetools, proxies en browsergeschiedenis. De Authorization-header is bedoeld voor credentials, al moet je ook daar logging goed maskeren.

Gebruik altijd HTTPS. Verstuur een sk_live-sleutel nooit naar een HTTP-endpoint. Controleer dat redirects credentials niet doorsturen naar een andere host. Je HTTP-client moet veilig falen bij onverwachte redirects of certificaatfouten.

Ontwerp een betrouwbare catalogus-payload

Geef elk product een stabiele, unieke identifier. Een SKU of permanent product-ID is meestal geschikt. Met stabiele ID’s kan een update het juiste record vervangen in plaats van duplicaten te maken. Titel en beschrijving moeten leesbaar en feitelijk zijn. Neem product-URL’s op, zodat antwoorden naar de actuele winkelpagina kunnen verwijzen.

Een conceptueel record kan velden bevatten zoals:

{
  "id": "SKU-100",
  "title": "Reisbeker",
  "description": "Geïsoleerde roestvrijstalen beker met lekbestendige dop.",
  "price": 24.95,
  "currency": "EUR",
  "availability": "in_stock",
  "url": "https://voorbeeld.nl/products/reisbeker",
  "brand": "Voorbeeld",
  "categories": ["Drinkwaren", "Reizen"]
}

Volg altijd het exacte schema dat het endpoint verwacht. Ga er niet van uit dat alle velden uit dit voorbeeld verplicht zijn of dat de namen overal hetzelfde zijn. Valideer de payload eerst in een niet-productieworkflow wanneer die beschikbaar is en verstuur daarna een kleine echte steekproef voordat je de hele catalogus uploadt.

Vermijd louter marketingteksten, interne leveranciersnotities en data die niet bij klantvragen hoort. Correcte materialen, afmetingen, compatibiliteit, onderhoudsinstructies en voorraad zijn nuttiger dan brede claims. Normaliseer valuta, voorraadwaarden, URL’s en categoriewaarden, zodat hetzelfde gegeven niet in tegenstrijdige formats binnenkomt.

Bouw het synchronisatieproces

Laat synchronisatie draaien vanuit een vertrouwde server-side job, worker, CI-omgeving of integratieservice. Lees de sk_live-sleutel tijdens runtime uit de omgeving. Hardcode hem nooit in broncode. Maak het proces idempotent wanneer de API dat ondersteunt: het opnieuw uitvoeren van dezelfde run moet de bedoelde producten bijwerken, niet dupliceren.

Gebruik bij grote catalogi beheersbare batches. Leg per batch de product-ID’s, responsstatus en een niet-gevoelige foutmelding vast. Log nooit de Authorization-header, de volledige sleutel of volledige klantdata. Herhaal alleen tijdelijke fouten, zoals time-outs of tijdelijke serverreacties, en gebruik backoff om niet steeds hetzelfde falende verzoek te versturen.

Synchroniseer na wijzigingen die klantantwoorden beïnvloeden: productpublicaties, prijs- of voorraadwijzigingen, nieuwe beschrijvingen, correcties van compatibiliteit en uitfaseringen. Kies een planning die past bij de snelheid waarmee die wijzigingen beschikbaar moeten zijn in Fynd.

Test vóór een volledige update een kleine batch met een normaal product, een uitverkocht product, een product met varianten en een product met een lange beschrijving. Controleer dat de geïmporteerde records in Fynd overeenkomen met je bronsysteem. Daarmee vind je koppelingsfouten voordat ze de hele catalogus raken.

Controleer resultaten in Fynd

Bekijk na een run de Catalog API-bron in de kennis- of sync UI. Controleer geaccepteerde records, afgewezen records en fouten. Zoek op de identifiers uit je testbatch en vergelijk titel, prijs, URL en voorraadstatus met het bronsysteem.

Gebruikt de integratie ook een sitemapbron, onthoud dan dat de sync UI blogaantallen kan tonen voor sitemapinhoud. Die aantallen komen uit gecrawlde pagina’s met BlogPosting of Article, geclassificeerd als page_type=blog; het zijn geen Catalog API-records. Houd de taak van elke bron helder wanneer je een antwoord onderzoekt.

Stel monitoring in voor herhaalde authenticatiefouten, onverwachte dalingen in recordaantallen of batches met aanhoudende validatiefouten. Een 401 of 403 is vaak het eerste teken van een geroteerde of onjuist gedeployde sleutel. Zie dit als een credential- of permissieprobleem, niet als reden om eindeloos opnieuw te proberen.

Problemen oplossen

Authenticatie faalt

Controleer dat de volledige actuele sk_live-sleutel door het server-side proces wordt geladen en als Authorization: Bearer <key> wordt verzonden. Controleer op spaties, een verouderd deploymentgeheim, ingetrokken sleutel of een sleutel uit de verkeerde workspace. Plak de sleutel niet in logs tijdens het onderzoek.

Verzoeken slagen maar producten zijn onjuist

Onderzoek de koppeling tussen bronvelden en het API-schema. Controleer stabiele ID’s, prijseenheden, valuta, voorraadwaarden en canonieke URL’s. Test één product en vergelijk elk veld.

Dubbele producten verschijnen

Zorg dat retries dezelfde identifier behouden en dat het bronsysteem niet bij elke export een nieuw ID maakt. Controleer of meerdere jobs of omgevingen dezelfde catalogus als verschillende bronnen versturen.

Een batch faalt halverwege

Leg vast welke identifiers zijn gelukt, herstel ongeldige records en herhaal alleen het mislukte deel wanneer dit wordt ondersteund. Verstuur een onbekende batch niet blind opnieuw zonder te weten of de API-operatie idempotent is.

Beveiligingschecklist

• Bewaar sk_live uitsluitend in server-side secrets.
• Verstuur de sleutel alleen via een HTTPS Bearer-header.
• Maskeer autorisatiewaarden in logs en monitoring.
• Roteer direct bij een vermoeden van blootstelling.
• Gebruik least privilege rond het deploymentgeheim.
• Controleer integratiejobs na sleutelrotatie.

Samenvatting

Met de Catalog API sturen maatwerksystemen productkennis rechtstreeks naar Fynd. Authenticeer server-side verzoeken met Authorization: Bearer sk_live_..., gebruik stabiele identifiers en schone productdata, valideer eerst kleine batches en bescherm het live geheim gedurende de hele levenscyclus.