Kavels, items & afbeeldingen

Een item is het fysieke object: een vaas, een kast, een schilderij. Een kavel is dat item aangeboden in één sessie onder één nummer. Dat onderscheid telt: een onverkocht item kan later opnieuw als nieuwe kavel worden aangeboden, dus het item draagt de omschrijving, de taxatie en de foto’s, terwijl de kavel het nummer, het bieden en of hij verkocht is draagt.

Het kavelobject

{
  "id": "lot_b48e0a19-5c72-4d83-91af-3e6b2c07d514",
  "lot_number": 24,
  "active": true,
  "title": "Delfts blauwe tulpenvaas, 18e eeuw",
  "starting_bid": { "amount": 8000, "currency": "EUR" },
  "current_bid": { "amount": 9500, "currency": "EUR" },
  "sold": false,
  "closes_at": "2026-07-05T19:11:30Z",
  "timed": { "scheduled_closes_at": "2026-07-05T19:00:00Z" },
  "item": "itm_2d9f6b31-8e4a-4c05-b7d2-9a1e3f8c6047",
  "session": "ses_7c1d5e88-2a34-4f19-9b0c-6d2e8f4a1357",
  "created_at": "2026-05-20T14:02:00Z",
  "updated_at": "2026-07-05T19:08:11Z"
}

active is de actief-instelling van de kavel, met dezelfde betekenis als het lijstfilter. De waarde is altijd true of false; een oudere oningevulde waarde wordt false. Een actieve kavel kan nog bij een ongepubliceerde sessie of veiling horen, en bieden door klanten kan apart zijn uitgeschakeld. Dit veld garandeert dus niet dat de kavel op een bepaalde website zichtbaar is of nu biedingen accepteert.

Bedragen zijn Money-objecten: hele minor units plus een valuta, dus 9500 is hier € 95,00.

closes_at is wanneer deze kavel stopt met bieden aannemen. Bij een timed veiling geldt hij per kavel: het is niet de sluitingstijd van de sessie, en kavels binnen één sessie sluiten meestal op verschillende momenten (een minuut of twee uit elkaar) al laten sommige huizen een hele sessie in één keer sluiten. Bij een live veiling draagt elke kavel dezelfde waarde, het moment waarop het online bieden van de sessie sluit, want dan stopt het online bieden voor allemaal. Hij kan ook null zijn, als er geen sluitingstijd is ingesteld.

Wat hij betekent hangt af van de kind van de sessie.

Bij een timed veiling is het het eigen eind van de kavel, en schuift hij op: een bod binnen extension_threshold_seconds vóór de sluiting verzet die naar het bod plus extension_seconds, en een bod binnen het nieuwe venster verzet hem opnieuw. Een fel betwiste kavel kan dus ruim voorbij zijn geplande eind doorlopen. Beide getallen staan op de sessie (twee minuten elk, tenzij het huis anders heeft ingesteld). Behandel de waarde als geldig op het moment van deze response en lees hem opnieuw zolang de kavel loopt.

Bij een live veiling is het het moment waarop het online bieden voor de sessie sluit: de eigen eindtijd van de kavel is zijn plek in de volgorde, geen biedingsdeadline. Er verlengt niets en een live kavel heeft geen timed-object of scheduled_closes_at-veld.

timed.scheduled_closes_at is de tijd vóór enige verlenging, dus een verschil met closes_at betekent dat de kavel al een keer is opgeschoven en dat waarschijnlijk weer zal doen. Een live kavel heeft helemaal geen timed-helft. Er valt niets te verlengen, dus ook niets te vergelijken: voor een live kavel is closes_at de enige sluitingstijd die er is.

item en session zijn ID’s, of volledige objecten onder expand[].

Het itemobject

{
  "id": "itm_2d9f6b31-8e4a-4c05-b7d2-9a1e3f8c6047",
  "title": "Delfts blauwe tulpenvaas, 18e eeuw",
  "description": "Peervormig, met floraal decor…",
  "condition": "Haarscheur aan de rand",
  "dimensions": "H 34 cm",
  "weight": "1,2 kg",
  "estimate": {
    "low":  { "amount": 8000,  "currency": "EUR" },
    "high": { "amount": 12000, "currency": "EUR" }
  },
  "images": ["img_c17a4e52-6b90-4f38-a2d5-0e8b1c4d7936", "img_e30b95a7-1f42-4c86-b9e0-5d7a2f13c804"],
  "created_at": "2026-05-18T09:12:00Z",
  "updated_at": "2026-05-19T16:40:00Z"
}

condition, dimensions en weight zijn vrije tekst zoals het huis die heeft geschreven, geen geparseerde maten. Elke grens van estimate mag ontbreken.

Het itemafbeeldingsobject

{
  "id": "img_c17a4e52-6b90-4f38-a2d5-0e8b1c4d7936",
  "url": "https://…/fitted/front.jpg",
  "preview_url": "https://…/fitted_thumbnail/front.jpg",
  "thumbnail_url": "https://…/thumbnail/front.jpg",
  "mini_url": "https://…/mini/front.jpg",
  "position": 0,
  "featured": true
}

Een itemafbeelding is twee dingen tegelijk, en het schema zegt dat ook: een Image (de weergaven, die elke afbeelding in de API heeft) plus de twee dingen die het veilinghuis over déze afbeelding in déze galerij bepaalt.

Er worden vier formaten gepubliceerd. Kies op wat er getoond wordt, niet op wat het grootst is:

Dat onderscheid telt in een catalogus: een vierkante uitsnede van een staande klok of een breed landschap snijdt de kavel af, dus gebruik de passende varianten overal waar het hele object zichtbaar moet zijn. De originele upload wordt niet gepubliceerd: die is onbegrensd in omvang, en elke gepubliceerde weergave heeft een bekend maximum.

position is de plek in de galerij, nulgebaseerd en nooit null. Hij is altijd gelijk aan de index in de images-array, zodat die twee elkaar niet kunnen tegenspreken.

featured zegt of het huis deze als hoofdfoto van het item heeft gekozen. Ga er niet van uit dat precies één afbeelding dat is: het weghalen van de hoofdfoto wijst geen vervanger aan, dus een item kan er ook geen hebben.

Alleen publiek zichtbare afbeeldingen worden teruggegeven, en ze komen altijd in galerijvolgorde.

Endpoints

Deze vier leesendpoints vereisen lots.read, dat ook items en hun afbeeldingen regelt. De PATCH voor kavelactivatie hieronder vereist daarnaast lots.write.

GET /lots
GET /lots/{id}
GET /items
GET /items/{id}

De publieke galerij komt mee met het item, als ID’s, of volledig met expand[]=images. De geneste endpoints voor afbeeldingsbeheer hieronder tonen ook privéafbeeldingen en afbeeldingen in verwerking voor importcontrole.

Lijsten nemen limit en cursor (paginering), plus:

Voorbeelden

De catalogus van een sessie, alles wat nodig is om hem te tonen, in één pagina aan verzoeken:

curl "https://app.bidvise.com/api/v2/lots?session=ses_7c1d5e88-2a34-4f19-9b0c-6d2e8f4a1357&limit=100&expand[]=item&expand[]=images" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Uitvouwen is hier het punt: zonder dat betekent 100 kavels tonen 100 vervolgverzoeken voor items en nog eens 100 voor afbeeldingen.

Eén kavel volledig:

curl "https://app.bidvise.com/api/v2/lots/lot_b48e0a19-5c72-4d83-91af-3e6b2c07d514?expand[]=item&expand[]=item.images&expand[]=session" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

De hele voorraad doorlopen, verkocht of niet:

curl "https://app.bidvise.com/api/v2/items?limit=100&expand[]=images" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Blijf next_cursor volgen tot has_more false is.

Kavels activeren voordat het bieden opent

PATCH /api/v2/lots/{id} wijzigt alleen de active-vlag van een bestaande kavel. De API-sleutel heeft zowel lots.write als lots.read nodig. Dit werkt ook voor kavels die via v1 zijn aangemaakt; het maakt, verplaatst of hernummert geen kavels.

curl -X PATCH "https://app.bidvise.com/api/v2/lots/lot_b48e0a19-5c72-4d83-91af-3e6b2c07d514" \
  -H "Authorization: Bearer $BIDVISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

Gebruik false om te deactiveren. De body mag alleen active bevatten, als JSON-boolean en niet als tekst. Bij succes volgt 200 met de huidige kavel onder data. Een waarde die al overeenkomt doet niets: geen opslag of nieuwe planningstaak, ook niet nadat het bieden is geopend. false omvat ook een oudere oningevulde vlag.

Een wijziging vereist een niet-afgeronde sessie met opens_at minstens vijf minuten in de toekomst en zonder biedingen op enige kavel, ook niet op gearchiveerde kavels. Timed sessies hebben daarnaast een eerste sluiting na opening, een positieve groepsgrootte en een positief interval nodig. De marge van vijf minuten wordt na het opbouwen van het antwoord nogmaals gecontroleerd, vóór het vastleggen. Anders volgt 409 zonder wijziging. Ongeldige invoer geeft 422; PUT wordt niet ondersteund. Publicatie van veiling/sessie en de instellingen voor bieden door klanten blijven ongewijzigd.

Een wijziging van de actief-vlag van een timed kavel zet een herberekening van de sluitingstijden van de sessie klaar. Deactiveren kan de overgebleven kavels eerder laten sluiten. Het 200-antwoord bevestigt de opgeslagen vlag, niet de voltooiing van die taak. Lees alle kavels van de sessie opnieuw en controleer timed.scheduled_closes_at voordat het bieden opent. Dezelfde PATCH herhalen herstart geen mislukte taak; blijvende verwerkingsproblemen vereisen aandacht van een medewerker. Dit endpoint is voor catalogusvoorbereiding, niet voor wijzigingen tijdens een veiling.

Items aanmaken en bijwerken

Gebruik items schrijven voor atomische POST/PATCH, vertalingen en inbrenger/categorieën. Leesverzoeken geven ook seller, categories en opgeslagen translations terug; de bestaande platte tekstvelden blijven in de standaardtaal.

Alle afbeeldingen terugvinden tijdens een import

GET /api/v2/items/{item_id}/images en GET /api/v2/items/{item_id}/images/{id} vereisen lots.read. Deze beheeracties tonen ook privéafbeeldingen en afbeeldingen in verwerking. expand=images blijft alleen de publieke galerij tonen. Gebruik de img_…-ID voor een afbeelding en de itm_…-ID voor het item; losse UUIDs werken ook. Een afbeelding van een ander item of huis geeft 404.

De lijst accepteert een exact, hoofdlettergevoelig filter external_reference en de gebruikelijke limit/cursor. De volgorde is aanmaaktijd met UUID als tweede sorteersleutel. Zo kan een onderbroken import een upload terugvinden zonder aantallen te raden. Onbekende parameters en lege referenties geven 400; dubbelzinnige oude identiteiten geven 500 in plaats van een willekeurig resultaat.

Het antwoord bevat de item-ID, uploadreferentie, public, featured, processing, tijdstempels, de vier bestaande afbeeldings-URLs en original_url. Het origineel kan groot zijn en wordt niet aan de normale publieke galerij toegevoegd. Een ontbrekend bestand kan een null-URL geven; een gegenereerde URL bewijst niet dat het bestand op de opslag bestaat.

gallery_position is de aaneengesloten positie vanaf nul in de volledige huidige publieke galerij, of null voor een privéafbeelding. Filteren op één upload of pagineren verandert die positie niet. De beheerlijst heeft een eigen paginavolgorde, los van de galerijvolgorde.

processing is de bestaande vlag voor nog te verwerken werk. False bewijst niet dat verwerking geslaagd is. Deze acties verzinnen geen gereed-/foutstatus. Uploaden en galerijvervanging staan in de OpenAPI-specificatie. Duurzame verwerkingsstatus volgt apart.