Items aanmaken en bijwerken

POST /api/v2/items maakt een fysiek catalogusitem. PATCH /api/v2/items/{id} wijzigt de opgegeven velden. Deze verzoeken maken geen kavel, publiceren geen veiling, wijzigen geen biedingen en uploaden geen afbeeldingen. Bestaande kavels behouden hun historie en krijgen de normale verversing bij een itemwijziging.

Beide endpoints vereisen lots.write en lots.read. Een bestaande inbrenger koppelen vereist daarnaast seller_profiles.read; categorieën koppelen vereist categories.read. Bewaar de API-sleutel op een server, nooit in de JavaScript van een klantwebsite.

Aanmaken

curl https://app.bidvise.com/api/v2/items \
  -H "Authorization: Bearer $BIDVISE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"external_reference":"2026_9-1000","title":"Zilveren kan","translations":{"en":{"title":"Silver jug"}},"estimate":{"low":{"amount":10000,"currency":"EUR"},"high":{"amount":20000,"currency":"EUR"}}}'

POST geeft 201, { "data": { ...item... } } en een Location met het API-pad terug. PATCH geeft 200 met dezelfde itemstructuur. ?expand=images is beschikbaar; lijstfilters en pagineringsparameters niet.

Geef een niet-lege external_reference en een titel in de standaardtaal van het veilinghuis mee, als title of onder translations.<taal>.title. Platte velden en een expliciet opgegeven vertaling in de standaardtaal moeten overeenkomen. Beschikbare talen: nl, en, fr, de, es, zh, it, pl, hu.

Gedeeltelijk bijwerken

Alleen opgegeven velden veranderen. Tekstvelden zijn title, description, condition, dimensions en weight; binnen vertalingen gelden dezelfde namen. translations bevat uitsluitend werkelijk opgeslagen vertaalregels. De platte velden behouden de bestaande tekstcache in de standaardtaal.

• Laat een veld weg om het te behouden, ook binnen een opgegeven vertaling.
• Null wist optionele tekst, seller, delivery_class of de volledige estimate. De titel in de standaardtaal en external_reference mogen niet worden gewist.
• categories: [] wist de categorieën. Geef anders bestaande cat_…-ID’s van hetzelfde veilinghuis mee. seller verwijst naar een actieve inbrenger via sel_…. Kale UUID’s mogen ook; dubbele verwijzingen naar dezelfde categorie niet.
• Een schattingsgrens is afzonderlijk te wijzigen of te wissen. Laag mag na de wijziging niet hoger zijn dan hoog. Bedragen gebruiken de valuta van het veilinghuis en gehele, niet-negatieve minor units, in veelvouden van 100, maximaal 214748364700. De bestaande opslag gebruikt hele valuta-eenheden; fracties worden afgewezen en niet afgekapt.

Onbekende velden, verkeerde JSON-typen, NUL-tekens, onbekende talen en onbeschikbare verwijzingen geven een fout. Inbrenger en consignatie moeten bij elkaar blijven passen; zie de koppelregels hieronder.

Makers en leveringsklasse

makers vervangt de geordende maker-lijst. Stuur mkr_…-ID’s of kale UUID’s van dit huis in de gewenste volgorde; [] wist de lijst en weglaten behoudt hem. Ook inactieve makers mogen gekoppeld worden. Canonieke duplicaten en null worden geweigerd. delivery_class neemt één dlc_…-ID of kale UUID van dit huis; null wist de koppeling en weglaten behoudt hem. Zoek de referenties op via de referentielijsten.

Deze velden worden ook teruggegeven bij het lezen van items, inclusief uitgeklapte items bij kavels. Makerwijzigingen en een andere volgorde wijzigen updated_at en verversen de gebruikelijke kavelcache. Een identieke herhaling laat de tijdstempels en caches ongemoeid. Behouden koppelingen houden hun identiteit; verwijderen van een koppeling wijzigt de maker zelf niet. Maker- en leveringsklassereferenties vallen onder het al vereiste lots.read.

Fouten en opnieuw proberen

Validatie geeft 422 Problem Details, eventueel met errors: [{ "field": "estimate.low.amount", "code": "invalid", "message": "…" }]. Ongeldige JSON en onbekende queryparameters geven 400, ontbrekende rechten 403 en een onbekend of huisvreemd doelitem 404. Bij een mislukte transactie wordt niets gedeeltelijk opgeslagen.

Een externe referentie is uniek binnen het veilinghuis, ook voor gearchiveerde items. Een dubbele POST of conflicterende PATCH geeft 409 en overschrijft nooit stilzwijgend een item. Vraag na een time-out of 409 /items?external_reference=... op, volg paginering, vergelijk de gegevens en voer zo nodig bewust een PATCH uit. Zonder actieve match kan een gearchiveerd item de referentie reserveren; neem contact op in plaats van een nieuwe referentie te verzinnen.

Een algemene Idempotency-Key is nog niet beschikbaar. Gelijktijdige PATCH-verzoeken vergrendelen het item en worden na elkaar toegepast; bij overlappende velden wint de laatste wijziging. Stem importprocessen dus af wanneer ze bestaande tekst overschrijven. Kavels aanmaken en andere importfuncties zitten nog niet in de API. De afbeeldingsendpoints staan hieronder.

Externe referenties mogen maximaal 1024 UTF-8-bytes bevatten (een teken kan meerdere bytes gebruiken). Ook wijzigingen aan alleen categorieën, makers (inclusief een andere volgorde) of vertalingen verhogen updated_at. Dubbele bestaande vertaalregels geven een 500-probleemantwoord; een mislukte schrijfactie wordt volledig teruggedraaid. Neem contact op om de bestaande gegevens te herstellen voordat het verzoek opnieuw wordt verstuurd.

Koppel een bestaande consignatie

Stuur consignment: "con_…" mee met de itemvelden. Naast lees- en schrijfrechten voor items is seller_profiles.read nodig. Zoek de echte ID via consignaties lezen. De koppeling volgt de bestaande backofficeregels voor inbrengers, vergrendeling en overerving van commissie; afspraken worden niet gewijzigd.

• Laat consignment weg om de koppeling te behouden. Null verwijdert de koppeling en behoudt de inbrenger, tenzij ook seller wordt meegestuurd.
• Een item zonder inbrenger neemt de inbrenger van de consignatie over als seller ontbreekt. Een bestaande inbrenger moet overeenkomen; de API wisselt deze niet stilzwijgend.
• Stuur een bij elkaar passende seller en consignment samen om beide te wijzigen. Expliciet seller: null met behoud van een consignatie wordt geweigerd.
• Nieuwe koppelingen aan een vergrendelde consignatie geven 422. Bestaande items blijven bewerkbaar en kunnen worden losgekoppeld, volgens de bestaande backofficeregels. Een identieke herhaling verandert de tijdstempel niet.
• Referenties moeten actieve records van hetzelfde huis zijn. Ongeldige referenties of een latere fout draaien de volledige itemwijziging terug, inclusief vertalingen en andere koppelingen. De doelconsignatie blijft tijdens de databasetransactie vergrendeld tegen gelijktijdige wijzigingen door medewerkers.

Het antwoord bevat de consignment-ID of null, zonder privéopmerkingen of commissiegegevens. Een itemverzoek maakt geen consignatie aan.

Status van de afbeeldingsverwerking

Het lezen van beheerde afbeeldingen (GET /items/{item}/images en de detailweergave) geeft processing_failure terug: null, of een object met code: "derivative_processing_failed" en een tijdstip at. Het legt een mislukte verwerkingspoging vast. Een automatische nieuwe poging kan nog lopen, en een geslaagde poging of een vervangen bron wist de melding. Een waarde null bewijst niet dat oudere afbeeldingen verwerkt zijn. Publieke galerijantwoorden bevatten dit veld niet.

Afgeleide afbeeldingen opnieuw maken

POST /items/{item}/images/{id}/reprocess met Content-Type: application/json en de body {} vraagt Bidvise de afgeleide versies opnieuw te maken vanuit de bestaande bron. Hiervoor zijn lots.write en lots.read nodig. Het antwoord is 202 met de afbeelding en processing: true. De bron, de afbeeldings-ID en de zichtbaarheid en positie in de galerij veranderen niet, dus een privéafbeelding blijft privé.

Wordt de afbeelding al verwerkt, dan is het antwoord 409 en wordt er niets nieuws ingepland. Lees na een time-out of een 503 de afbeelding opnieuw voordat het verzoek nog eens wordt verstuurd: deze opdracht heeft geen idempotentiesleutel. Niet-ondersteunde velden geven 422.

Een opgeslagen afbeelding verwijderen

DELETE /items/{item}/images/{id} zonder body verwijdert een afbeelding. Hiervoor zijn lots.read en lots.write nodig. Bij succes volgt 204 zonder body; een onbekende of al verwijderde afbeelding geeft 404. Ook privéafbeeldingen en afbeeldingen die nog verwerkt worden, kunnen worden verwijderd.

Na het verwijderen van de uitgelichte afbeelding wordt er geen nieuwe gekozen. Stel via het vervangen van de galerij een nieuwe uitgelichte afbeelding in. De overige afbeeldingen behouden hun zichtbaarheid en volgorde, en het item en de kavels blijven bestaan.

Opgeslagen bestanden worden verwijderd nadat de verwijdering is vastgelegd. Een 503 zegt niet of dat opruimen klaar is, dus lees de galerij terug vóór een nieuwe poging. Een vergrendelingsconflict geeft 409; lees ook dan de galerij terug vóór een nieuwe poging.