Je catalogus sturen met de Vinius-API

Kort antwoord

De Vinius-API zit in een testfase. Tot hij voor elke leverancier opengaat, staat op de kaart Volgt binnenkort, en beschrijven de stappen hieronder hoe hij dan werkt.
Open in Vinius Catalogus, ga naar Integraties en kies Koppelen op de kaart Vinius-API.
Maak een token met de naam van het systeem dat het gebruikt. Kopieer het meteen: Vinius toont het maar één keer.
Je systeem stuurt je catalogus naar POST /api/supplier/v1/catalog/items/batch, tot 500 producten per batch.
Voor je publiceert, is elke batch een test. Er komt niets bij kopers, en het antwoord zegt hoe Vinius elk product las.
Doe de steekproef en klik dan op Catalogus publiceren. Vanaf dan is elke batch een synchronisatie.

Wanneer gebruik je het

De API past bij leveranciers van wie het eigen systeem gegevens kan sturen: een ERP, een PIM, een andere webshop dan Odoo, of een tool die een bureau voor je bouwde. Je hebt er iemand voor nodig die kan programmeren. Zonder die persoon doet de Excel-import hetzelfde werk met de hand.

Tokens

Met een token kan je systeem je catalogus sturen. Het hoort bij deze integratie, niet bij een persoon, dus het blijft werken als iemand je team verlaat.

Eén keer getoond. Kopieer het wanneer je het maakt. Vinius bewaart alleen een vingerafdruk ervan en toont de eerste tekens (vns_ en nog vier) in de lijst.
Eén token per systeem. Geef elk token de naam van het systeem dat het gebruikt. Er kunnen er tot vijf tegelijk actief zijn.
Een jaar geldig. Een token vervalt na 12 maanden. Maak voor die tijd een nieuw en zet het in de plaats.
Meteen intrekken. Intrekken stopt een token onmiddellijk, bijvoorbeeld als het uitgelekt kan zijn.
Alleen voor je catalogus. Een token werkt alleen op de leveranciers-API. Het kan niets anders in Vinius lezen of wijzigen.

De lijst toont wanneer elk token het laatst gebruikt werd, en vanaf welk adres. Behandel een token als een wachtwoord: bewaar het in de instellingen van je systeem, nooit in een e-mail of een gedeeld document.

Je catalogus sturen

Stuur het token in de header Authorization als Bearer vns_…. Een batch is JSON:

{
  "scope": "full",
  "items": [
    {
      "sku": "RAL-PREST-75",
      "producer": "Robert-Allait",
      "name": "Cuvée Prestige Brut",
      "vintage": "NV",
      "sizeMl": 750,
      "style": "sparkling",
      "country": "FRA",
      "price": 22.13,
      "availability": "available"
    }
  ]
}

Elk product heeft de velden van het Excel-sjabloon: sku (verplicht), type, producer, name, vintage, sizeMl, unitsPerCase (een doos wordt opzijgezet tot dozen gepubliceerd kunnen worden), style, country, region, classification, gtin, price, currency, availability en imageUrl. De volledige lijst, met wat elk veld bevat, staat in de API-documentatie.

sku is je eigen productcode. Zo vindt de volgende batch het product terug.
price is je handelsprijs per fles of stuk, exclusief btw.
scope is full voor je hele catalogus: aanbiedingen die er niet in staan, worden onbeschikbaar. Met partial wijzig je alleen de producten die een batch noemt.

Meer dan 500 producten

Stuur de catalogus in delen van één lezing. Zet "more": true op elk deel behalve het laatste, en stuur de runId uit het eerste antwoord mee met elk volgend deel. Het laatste deel, zonder more, rondt de lezing af. Eén lezing bevat hoogstens 5.000 producten.

Wat het antwoord zegt

Elk antwoord somt elk product op met zijn uitkomst en zijn bevindingen: gekoppeld aan een wijn die Vinius kent, nieuw, aangehouden voor beoordeling, of weggelaten en waarom. Het zijn de bevindingen van de integriteitscontrole. Elke bevinding, met de oplossing.

Stappen

Open Catalogus, ga naar Integraties en klik op Koppelen op de kaart Vinius-API.
Typ onder Tokens een naam en klik op Token maken. Kopieer het token naar je systeem.
Stuur je hele catalogus met "scope": "full". Deze eerste lezing is de integriteitscontrole.
Lees het rapport op het tabblad Integraties, of het antwoord dat je systeem kreeg. Herstel aan de bron wat het vindt en stuur de catalogus opnieuw.
Doe de Steekproef: duid elke wijn in de steekproef aan als Juist of Fout en klik op Steekproef bevestigen.
Staat de integratie op Klaar, klik dan op Catalogus publiceren. De gecontroleerde lezing wordt meteen toegepast.

Vanaf dan is elke batch die je systeem stuurt een synchronisatie. Er is geen planning: je systeem beslist wanneer het stuurt.

Tussen twee batches

Nog twee oproepen helpen een systeem dat wijzigingen meteen doorstuurt:

PATCH /api/supplier/v1/catalog/items/{sku} wijzigt de beschikbaarheid of de prijs van één product, zodra de integratie gepubliceerd is. Een flesprijs buiten de grenzen van de integriteitscontrole wordt geweigerd.
GET /api/supplier/v1/catalog/items en GET /api/supplier/v1/catalog/items/{sku} tonen je aanbod zoals Vinius het heeft.

GET /api/supplier/v1/catalog/reviews somt de producten op die wachten op beoordeling, met de wijnen die Vinius voorstelt. Je beantwoordt ze op het tabblad Integraties, en het antwoord geldt vanaf de volgende batch.

Controles en limieten

Elke batch na het publiceren doorloopt dezelfde controles als de eerste lezing. Een batch die veel meer verandert dan gewoonlijk, wordt aangehouden: het antwoord is 409 met de runId van de lezing, en er verandert niets tot je in Vinius Toch toepassen of Verwerpen kiest. Hoe de bewaking werkt.

Limiet	Waarde
Oproepen per token	60 per minuut
Producten per token	10.000 per dag
Producten per batch	500
Grootte van een oproep	1 MB

Een oproep boven een limiet krijgt 429 en een header Retry-After met het aantal seconden dat je moet wachten. Een ontbrekend, onbekend, ingetrokken of vervallen token krijgt 401.