Systemen
Salsify koppeling met je webshop: productdata uit Salsify in je shop
Een Salsify koppeling zet producten, vertalingen en beelden uit Salsify in je webshop en houdt ze bij met webhooks. De API staat 10.000 verzoeken per uur toe per organisatie, gedeeld door alles wat op die organisatie draait, dus een volle catalogus gaat via een export en niet product voor product.
Wat is Salsify en wie gebruikt het?
Salsify is een cloudplatform voor productinformatie en digitale bestanden. Merken en fabrikanten gebruiken het om productdata centraal bij te houden en naar retailers, marktplaatsen en de eigen webshop te sturen. Elke klant heeft een eigen organisatie in Salsify, met een org_id dat in de URL van de applicatie staat, direct na /orgs/.
Het model bestaat uit producten, digitale bestanden (afbeeldingen, video's, documenten) en properties. Een property is een kenmerk met een datatype, zoals een tekst, een getal of een keuze uit vaste waarden. Welke properties er zijn en hoe ze heten, bepaalt de organisatie zelf. De namen zijn hoofdlettergevoelig: Product Name en product name zijn twee verschillende properties.
| Begrip in Salsify | Wat het is | Wat de webshop ermee doet |
|---|---|---|
salsify:id |
productcode, uit de property met de rol product-ID | koppelsleutel, meestal de SKU |
salsify:system_id |
vast intern id, verandert nooit | sleutel die blijft als de SKU wijzigt |
salsify:parent_id |
verwijzing naar het hoofdproduct | variant onder een product |
salsify:updated_at |
laatste wijziging, in UTC | controleronde |
salsify:version |
teller, +1 bij elke opgeslagen wijziging | vergelijken met de vorige ronde |
Wat je met Salsify koppelt
Salsify is leidend voor wat een product is: naam, omschrijving, kenmerken, vertalingen en beelden. Het ERP is leidend voor artikelnummer, prijs en voorraad.
| Stroom | Richting | Mechanisme in Salsify |
|---|---|---|
| Volledige catalogus | Salsify naar webshop | export run, als JSON, CSV of Excel |
| Wijzigingen per product | Salsify naar webshop | product change webhook |
| Eén product opvragen | Salsify naar koppeling | GET /api/v1/orgs/{org_id}/products/{id} |
| Afbeeldingen en documenten | Salsify naar webshop | digitale bestanden met een URL |
| Artikelnummers en basisgegevens | ERP naar Salsify | JSON-import, vanaf FTP of als upload |
Een export run levert de catalogus als bestand. Je kiest het type (product, digital_asset, attribute, attribute_value of all), het formaat en welke properties meegaan. Let op product_type: de standaard is leaves, alleen de producten op het laagste niveau. Wie de hoofdproducten ook nodig heeft om varianten te groeperen, vraagt all. Hoe productdata in het algemeen tussen systemen loopt, staat op productdata koppelen.
Hoe Salsify data vrijgeeft
REST API met een token
De API werkt met JSON en een token. Het token gaat als Authorization: Bearer in de header of als queryparameter access_token. Salsify raadt de header aan, omdat een URL met het token in logs terechtkomt; wij gebruiken alleen de header. OAuth 2.0 is de tweede mogelijkheid. Elk pad bevat het org_id. Hoort de gebruiker bij meer dan één organisatie en ontbreekt het, dan geeft de API een 400 met de lijst van organisaties.
10.000 verzoeken per uur, per organisatie
Salsify staat 10.000 API-verzoeken per uur toe per organisatie, ongeacht welke gebruiker ze doet. Verzoeken uit de applicatie zelf tellen niet mee. Elk antwoord draagt x-ratelimit-limit, x-ratelimit-remaining en x-ratelimit-reset, het aantal seconden tot het hele uur. Daarboven komt een 429 Too Many Requests, tot het volgende hele uur. De volledige regeling staat in de documentatie van Salsify over rate limiting.
De rekensom voor een eerste vulling van 25.000 producten:
| Aanpak | Rekensom | Verzoeken en tijd |
|---|---|---|
| Elk product apart opvragen | 25.000 x 1 | 25.000 verzoeken, 2,5 uurbudget |
| Export run | 1 start + statusvragen + 1 download | enkele verzoeken |
| Wijzigingen via webhooks | het product zit in het bericht | 0 verzoeken per wijziging |
Bij het eerste aantal staat de organisatie ruim twee uur op slot voor elke andere koppeling. Daarom gaat de vulling via een export en lopen wijzigingen via webhooks.
Webhooks bij productwijzigingen
In Salsify stel je een melding in op een lijst producten: bij toevoegen, bij elke wijziging, bij een wijziging van gekozen properties, of bij verwijderen uit de lijst. Het bericht bevat het product in het exportformaat, de hoofdproducten in parent_products en een trigger_type: add, change of remove. Een verwijderd product heeft salsify:destroyed_at. Berichten zijn ondertekend met een X.509-certificaat en SHA-256; de koppeling controleert de handtekening en weigert wat niet klopt.
Drie eigenschappen van de aflevering bepalen het ontwerp:
- Een bericht dat niet aankomt, probeert Salsify 15 keer opnieuw binnen 48 uur, met een groeiende pauze.
- Wijzigingen kort na elkaar kunnen samen in één bericht komen. Een wijziging die het product terugzet naar de oude stand, levert soms geen bericht op.
- Een filter op een slimme lijst aanpassen, waardoor producten erbij komen of afvallen, stuurt geen berichten.
Voor hetzelfde product komen berichten in volgorde. Tussen verschillende producten is de volgorde niet gegarandeerd. Meer over die werking staat in wat is een webhook.
Waar het bij Salsify op vastloopt
| Wat er misgaat | Oorzaak in Salsify | Wat de koppeling doet |
|---|---|---|
| Variant niet bijgewerkt | salsify:version van de variant stijgt niet als een geërfde waarde op het hoofdproduct wijzigt |
Bij een gewijzigd hoofdproduct alle varianten opnieuw lezen |
| Veld blijft oud in de webshop | Een lege property ontbreekt in het product; geen sleutel betekent geen waarde | Ontbrekende property lezen als leeg |
| Assortiment in de shop loopt achter op de lijst | Filter van een slimme lijst aangepast; geen webhook | Controleronde op lijstlidmaatschap |
| Hoofdproducten ontbreken in de export | product_type staat standaard op leaves |
all in de exportconfiguratie |
| Andere koppelingen krijgen 429 | Uurbudget gedeeld per organisatie | Bulkwerk via exports, budget per verzoek bijhouden |
Varianten en overerving
Een variant heeft een salsify:parent_id en erft standaard de waarden van het hoofdproduct. Salsify verhoogt salsify:version van de variant niet als een geërfde waarde op het hoofdproduct wijzigt. Een koppeling die per variant op versie of wijzigingsdatum vergelijkt, mist zo een nieuwe omschrijving of een nieuw materiaal. Wij houden per hoofdproduct bij welke varianten eronder hangen en lezen ze opnieuw als het hoofdproduct wijzigt. Hoe varianten in de webshop landen staat op varianten.
Lege properties en talen
Salsify bewaart alleen properties met een waarde. Wordt een property leeggemaakt, dan ontbreekt de sleutel in het volgende antwoord. Een koppeling die alleen meegestuurde velden bijwerkt, laat de oude waarde in de webshop staan. De koppeling vergelijkt daarom met de lijst properties die ze verwacht en maakt een ontbrekende property leeg in de shop.
Een property per taal heeft een waarde per locale, bijvoorbeeld en-US en nl-NL. De webshop gebruikt vaak andere codes, zoals nl of nl_NL. De koppeling legt per shop vast welke locale bij welke taal hoort, en wat er gebeurt als een vertaling ontbreekt. Meer over dit soort mismatches staat in wat is veldmapping.
Platformen die we aan Salsify koppelen
De koppeling wordt gebouwd op jouw properties en jouw webshop. Wat het platform aan de ontvangende kant vraagt, staat op de pagina van dat platform:
Werk je met een ander PIM, zie dan Akeneo koppeling, Pimcore koppeling of inRiver koppeling. Het overzicht van alle stromen staat op koppelingen.
Wij bouwen de koppeling voor een vaste prijs, en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor de livegang draait hij als dry run: je ziet per product welke velden en beelden er in de webshop zouden komen, zonder dat er iets wijzigt. Vertel welke properties en welke webshop je hebt, dan hoor je welke exports en meldingen de koppeling gebruikt en wat dat van je uurbudget vraagt.
Veelgestelde vragen
Zit API-toegang in elk Salsify-abonnement?
Nee. Salsify schrijft dat API-toegang niet in elke organisatie zit en afhangt van het licentietype. Vraag het na bij je accountmanager voordat de bouw begint. Zonder API kan een koppeling werken met geplande exports naar FTP, maar dan zonder webhooks en met de vertraging van het schema.
Gaan we het API-budget delen met andere koppelingen?
Ja. De limiet van 10.000 verzoeken per uur geldt per organisatie, ongeacht welke gebruiker ze doet. Draaien er al koppelingen met een marktplaats of een retailer op dezelfde organisatie, dan halen die van hetzelfde budget. De koppeling leest bij elk antwoord x-ratelimit-remaining en schuift bulkwerk door als het budget krap wordt.
Hoe snel staat een wijziging uit Salsify in de webshop?
Met een product change webhook zodra Salsify het bericht verstuurt. Het bericht bevat het product zelf, dus de koppeling hoeft het niet eerst op te vragen. Twee wijzigingen kort na elkaar kunnen samen in één bericht komen, met de laatste waarde. Een wijziging die het product terugzet naar hoe het was, levert soms geen bericht op. Daarom draait er daarnaast een controleronde op salsify:updated_at.
Kunnen prijzen en voorraad uit Salsify komen?
Een property kan elke waarde bevatten, ook een prijs of een voorraadgetal. In de meeste landschappen is het ERP leidend voor prijs en voorraad en gaan die rechtstreeks naar de webshop, en levert Salsify de productinformatie. Zie voorraad en beschikbaarheid.
Hoe komen artikelnummers uit ons ERP in Salsify?
Via een import. Salsify raadt imports aan zodra het om honderden entiteiten of meer gaat. Een JSON-import kan producten, properties, waarden en relaties in één keer aanmaken of bijwerken, vanaf FTP of als upload, en op een schema draaien. De koppeling zet de ERP-gegevens in dat formaat en start de import.
Vertel wat je nodig hebt
Vertel welke systemen je gebruikt en wat je wilt verbeteren. Je krijgt binnen één werkdag een persoonlijk antwoord. We helpen je de werkzaamheden helder te krijgen en spreken de prijs en planning af voordat je iets toezegt.
- Je weet de prijs en de doorlooptijd voordat je iets toezegt
- Wij zoeken uit welke koppeling het werk uit handen neemt
- Wij verzorgen de bouw, hosting, bewaking en het onderhoud
- Je team krijgt minder overtypwerk en minder uitzoekwerk