Sending your catalogue with the Vinius API

Quick answer

The Vinius API is in a test phase. Until it opens to every supplier, its card shows Coming next, and the steps below describe it as it will work.
In Vinius, open Catalogue, go to Integrations and choose Connect on the Vinius API card.
Create a token, named after the system that uses it. Copy it at once: Vinius shows it only once.
Your system sends your catalogue to POST /api/supplier/v1/catalog/items/batch, up to 500 products a batch.
Before you publish, every batch is a test. Nothing reaches buyers, and the answer says how Vinius read each product.
Do the spot check, then click Publish the catalogue. From then on, every batch is a sync.

When to use it

The API suits suppliers whose own system can send data: an ERP, a PIM, a webshop other than Odoo, or a tool an agency built for you. It takes someone who can program. Without that person, the Excel import does the same job by hand.

Tokens

A token lets your system send your catalogue. It belongs to this integration, not to a person, so it keeps working when someone leaves your team.

Shown once. Copy it when you create it. Vinius keeps only a fingerprint of it and shows its first characters (vns_ and four more) in the list.
One token per system. Name each one after the system that uses it. Up to five can be active at once.
Valid for a year. A token expires after 12 months. Create a new one before then and swap it in.
Revoke at once. Revoke stops a token straight away, for example when it may have leaked.
Only for your catalogue. A token works on the supplier API alone. It cannot read or change anything else in Vinius.

The list shows when each token was last used, and from which address. Treat a token like a password: keep it in your system's settings, never in an email or a shared document.

Sending your catalogue

Send the token in the Authorization header as Bearer vns_…. A 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"
    }
  ]
}

Each product takes the fields of the Excel template: sku (required), type, producer, name, vintage, sizeMl, unitsPerCase (a case is set aside until packs can be published), style, country, region, classification, gtin, price, currency, availability and imageUrl. The full list, with what each field takes, is in the API documentation.

sku is your own product code. It is how the next batch finds the product again.
price is your trade price per bottle or piece, excluding VAT.
scope is full for your whole catalogue: offers it leaves out become unavailable. Use partial to change only the products a batch names.

More than 500 products

Send the catalogue in parts of one reading. Set "more": true on every part but the last, and send the runId from the first answer with every next part. The last part, without more, completes the reading. One reading holds at most 5,000 products.

What the answer says

Every answer lists each product with its outcome and its findings: linked to a wine Vinius knows, new, held for review, or left out and why. The findings are the ones the integrity check uses. Every finding, with its fix.

Steps

Open Catalogue, go to Integrations and click Connect on the Vinius API card.
Under Tokens, type a name and click Create token. Copy the token into your system.
Send your whole catalogue with "scope": "full". This first reading is the integrity check.
Read the report on the Integrations tab, or the answer your system got. Fix what it finds at the source and send the catalogue again.
Do the Spot check: mark each wine in the sample Right or Wrong, then click Confirm spot check.
Once the integration shows Ready, click Publish the catalogue. The checked reading is applied straight away.

From then on, every batch your system sends is a sync. There is no schedule: your system decides when to send.

Between batches

Two more calls help a system that pushes changes as they happen:

PATCH /api/supplier/v1/catalog/items/{sku} changes the availability or the price of one product, once the integration is published. A bottle price outside the integrity check's bounds is refused.
GET /api/supplier/v1/catalog/items and GET /api/supplier/v1/catalog/items/{sku} show your offers as Vinius holds them.

GET /api/supplier/v1/catalog/reviews lists the products held for review, with the wines Vinius proposes. You answer them on the Integrations tab, and the answer holds from the next batch on.

Checks and limits

Every batch after publishing runs the same checks as the first reading. A batch that changes much more than usual is held: the answer is 409 with the reading's runId, and nothing changes until you choose Apply anyway or Discard in Vinius. How the change guards work.

Limit	Value
Requests per token	60 a minute
Products per token	10,000 a day
Products per batch	500
Size of a request	1 MB

A request over a limit gets 429 and a Retry-After header with the seconds to wait. A missing, unknown, revoked or expired token gets 401.