Veilingen & sessies

Een veiling is het verkoopevenement: wat op de poster staat. Een sessie is een zitting binnen dat evenement met een eigen opening en sluiting: een timed sessie die zondag online sluit, een live sessie die dinsdag in de zaal wordt afgeslagen. Eén veiling, elke mix van sessies.

Het veilingobject

{
  "id": "auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482",
  "title": "Voorjaarsveiling 2026",
  "description": "Meubelen, kunst en curiosa.",
  "slug": "voorjaarsveiling-2026",
  "published": true,
  "opens_at": "2026-07-01T10:00:00Z",
  "sessions": ["ses_7c1d5e88-2a34-4f19-9b0c-6d2e8f4a1357", "ses_a5b30f27-6d18-4e92-8c47-2f9a1b6e3d08"],
  "created_at": "2026-05-12T09:30:00Z",
  "updated_at": "2026-05-30T11:02:00Z"
}

published zegt of de veiling op de eigen website van het huis staat. Bij een sessie betekent het écht zichtbaar voor een bezoeker: een sessie die gepubliceerd maar verborgen is, meldt false, en het published-filter doet hetzelfde. opens_at is de vroegste opening van al zijn sessies: een gemak, zodat een lijst veilingen te sorteren is op wanneer het bieden begint zonder ze allemaal uit te vouwen.

sessions is een lijst ID’s in verkoopvolgorde, of volledige objecten met expand[]=sessions.

Het sessieobject

{
  "id": "ses_7c1d5e88-2a34-4f19-9b0c-6d2e8f4a1357",
  "title": "Dag 1 - Kunst",
  "kind": "timed",
  "opens_at": "2026-06-20T10:00:00Z",
  "timed": {
    "first_lot_closes_at": "2026-07-05T19:00:00Z",
    "group_size": 5,
    "interval_seconds": 30,
    "extension_threshold_seconds": 120,
    "extension_seconds": 120
  },
  "live": null,
  "published": true,
  "finished": false,
  "auction": "auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482",
  "created_at": "2026-05-12T09:31:00Z",
  "updated_at": "2026-06-20T10:00:03Z"
}

kind is timed of live, en bepaalt welke van de twee schema’s aanwezig is: een timed sessie draagt timed en een lege live, een live sessie andersom. Een schema dat niet van toepassing is, ontbreekt: het wordt niet geleend van de andere regel.

timed.first_lot_closes_at is wanneer de sluitingsreeks begint, niet wanneer de sessie eindigt: kavels sluiten in groepen van group_size, met interval_seconds ertussen, en de sessie is voorbij zodra de laatste kavel dat is. extension_threshold_seconds en extension_seconds zijn het verlengingsvenster: een bod zó dicht bij het eind van een kavel verlengt die met zoveel. Ze zijn wat een bod daadwerkelijk doet, met standaardwaarden toegepast: nooit null. live.online_bidding_closes_at is wanneer het online bieden voor de zaalveiling sluit.

finished zegt dat de sessie is uitgelopen, wat iets anders is dan dat een van die tijden gepasseerd is, want verlenging verschuift het echte eind.

auction is een ID, of het volledige object met expand[]=auction.

Endpoints

Alle vier vereisen het recht auctions.read. Een sessie is een zitting van een veiling en valt dus onder hetzelfde recht als de veiling zelf.

GET /auctions
GET /auctions/{id}
GET /sessions
GET /sessions/{id}

Lijsten nemen limit en cursor (paginering), plus:

Voorbeelden

Alles wat op dit moment is aangekondigd:

curl "https://app.bidvise.com/api/v2/auctions?published=true" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Eén veiling met zijn zittingen inline, in één verzoek:

curl "https://app.bidvise.com/api/v2/auctions/auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482?expand[]=sessions" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

De sessies van één veiling als eigen gepagineerde lijst: de betere keuze als een veiling er veel heeft:

curl "https://app.bidvise.com/api/v2/sessions?auction=auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Vanaf hier zijn kavels & items wat een sessie daadwerkelijk aanbiedt.

Een leeg concept aanpassen

PATCH /sessions/{id} vereist auctions.write en auctions.read. Stuur title, settings of beide. De sessie moet ongepubliceerd en onafgerond zijn, zonder huidige of verwijderde kavels; anders geeft de API 409. Een gepubliceerde maar verborgen sessie voldoet niet.

{
  "title": "Sessie I: zilver",
  "settings": {
    "buyer_premium_percentage": "28.50",
    "allow_proxy_bidding": false,
    "show_lot_numbers": true,
    "live_written_bids_compete": true
  }
}

Alleen meegestuurde velden veranderen. De titel gebruikt de standaardtaal van het huis; andere vertalingen blijven behouden. Het opgeld accepteert 0–100 met maximaal twee decimalen, als JSON-getal of decimale tekst met een punt. Booleaanse instellingen vereisen echte JSON-booleans. Onbekende velden en ongeldige waarden geven 422 zonder iets op te slaan. Dezelfde waarden opnieuw sturen of { "settings": {} } verandert niets.

Sessietype, bovenliggende veiling, importreferentie, publicatie en de schakelaar voor klantbieden kunnen hier niet veranderen. Bij timed sessies concurreren schriftelijke biedingen altijd; live_written_bids_compete geldt voor live sessies. Controleer de instellingen voordat er kavels worden toegevoegd. Dezelfde instellingen zijn toegestaan bij het aanmaken met POST /sessions.

Concepttijden vervangen

Voordat er kavels zijn toegevoegd, kan dezelfde PATCH het tijdschema vervangen. Stuur opens_at en het volledige blok voor het bestaande sessietype, eventueel samen met titel en instellingen:

{
  "opens_at": "2026-09-20T09:00:00+02:00",
  "timed": {
    "first_lot_closes_at": "2026-09-21T19:00:00+02:00",
    "group_size": 2,
    "interval_seconds": 30
  }
}

Gebruik bij een live sessie live in plaats van timed, met zowel online_bidding_closes_at als live_bidding_starts_at. Alle datums vereisen een expliciete tijdzone-offset. Sluiten en live starten moeten na de opening liggen; online sluiten mag niet na live starten liggen. Groepsgrootte en interval zijn positieve gehele getallen. De optionele extension_threshold_seconds en extension_seconds zijn niet-negatieve gehele getallen; weglaten behoudt de huidige effectieve waarden.

Stuur het volledige tijdschema. Alleen een openingsdatum of één tijd binnen het blok geeft 422. Het verkeerde sessietypeblok, beide blokken of null geeft ook 422. Zonder tijdvelden blijven de datums behouden. Dezelfde tijden opnieuw sturen verandert niets. Een sessie met huidige of verwijderde kavels geeft 409; deze bewerking kan geen sluitingstijden van een gevulde sessie verplaatsen.