API-overzicht

De Bidvise Catalogus-API leest de catalogus via HTTP: de lopende veilingen, de sessies daarbinnen, de kavels die worden aangeboden, de items achter die kavels, en hun afbeeldingen.

Het is een kleine, voorspelbare REST-API (meervoudige zelfstandige naamwoorden, JSON eruit, standaard HTTP-semantiek) met cataloguslezingen en atomisch items aanmaken en bijwerken.

https://app.bidvise.com/api/v2

Alle verzoeken worden geauthenticeerd met een API-sleutel; de sleutel bepaalt welk veilinghuis wordt gelezen. GET /api/v2 met een sleutel geeft terug wat er is en waar de documentatie staat; alles onder /api/v2 dat niet bestaat, antwoordt met een problem-document, nooit met een webpagina.

Het model

Vijf resources, één hiërarchie:

Resource	Wat het is
`auctions`	Het veilingevenement dat een huis aankondigt: “Voorjaarsveiling 2026”
`sessions`	Een zitting binnen een veiling, met eigen opening en sluiting: timed of live
`lots`	Een item aangeboden in een sessie, met kavelnummer, taxatie en resultaat
`items`	Het fysieke object: titel, omschrijving, staat, afmetingen
`images`	De foto’s van een item

Een veiling bevat sessies; een sessie bevat kavels; een kavel biedt een item aan; een item heeft afbeeldingen. Dat is het kernmodel. Inbrengers, consignaties en de referentielijsten staan bij de andere resources.

Het onderscheid tussen kavel en item is het stuk om goed vast te pakken: het item is het object zelf en overleeft elke verkoop, terwijl de kavel dat object is zoals het in één sessie onder één nummer wordt aangeboden. Hetzelfde item kan opnieuw worden aangeboden als een nieuwe kavel.

Snel starten

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

{
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Relaties komen terug als ID’s. Vraag ze inline op wanneer ze nodig zijn:

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

Uitgangspunten

ID’s met prefix (auc_, ses_, lot_, itm_, img_): elk ID zegt wat het is, en het verkeerde soort wordt geweigerd in plaats van stilletjes verkeerd behandeld.
Geld is exact: hele minor units plus een ISO 4217-valuta, nooit floats.
Diepte is een parameter: expand[], geen aparte set “gedetailleerde” endpoints.
Eén envelope, één paginering, één foutvorm: overal cursorpaginering, RFC 9457-problem-documenten voor elke fout.
Niets wordt impliciet geserialiseerd: elk veld staat met naam in een serializer, dus ons databaseschema is nooit het contract.
Vastgelegd in een spec: het OpenAPI 3.1-document wordt in onze testsuite tegen echte responses gecontroleerd, dus het kan niet afdrijven van de code.

Alles hierboven staat uitgeschreven in conventies.

Wat er nog niet is

Deze versie dekt de catalogus: veilingen, sessies, kavels, items en afbeeldingen, plus inbrengers, consignaties en de referentielijsten. Biedingen, kopers, facturen, betalingen, registraties, afrekeningen, directe verkoop en webhooks zijn niet via de API beschikbaar.