Fahrzeugbilder für Auktionsangebote

Ein Auktionskatalog geht online, sobald die Einlieferungen vorliegen: eine VIN, eine Losnummer und ein Auktionsdatum für jedes Fahrzeug. Die Fotos kommen, wenn das Auto auf dem Gelände eintrifft und der Fotograf beim Auto ist – bei einem Teil der Auktion erst nach Beginn der Gebotsphase. Bis dahin ist jedes dieser Lose ein grauer Kasten neben einer Textzeile.

Ein Katalog-Rendering füllt die Fläche mit dem richtigen Modelljahr. Eine Auktion ist aber auch genau der Ort, an dem ein Rendering niemals als das Fahrzeug selbst durchgehen darf: Bieter bewerten den Zustand, und ein Rendering zeigt keinen, weil es kein bestimmtes physisches Fahrzeug darstellt. Alles Folgende ergibt sich daraus, beides gleichzeitig im Blick zu behalten.

• Ein Rendering pro Los anhand seiner VIN, nur angezeigt, bis die eigenen Fotos des Loses eintreffen.
• Eine Katalogauswahl für die Lose, deren VIN sich nicht decodieren lässt.
• Ein Hinweis auf dem Bild: „Katalog-Rendering, nicht dieses Los“.
• Eine URL pro Los, einmalig erzeugt unter einem Idempotency-Key, gültig für die gesamte Dauer der Auktion.

GET /api/v1/vin/{vin} ist kostenlos. Wenn der Katalog das Fahrzeug enthält, liefert die Antwort data.vehicle.id, die stabile ID, die Sie am Los speichern; die dekodierte Ausstattungsvariante, Karosserie und Motorisierung bleiben im Text des Loses. Der Katalog reicht von 1990 bis 2027, sodass ältere Fahrzeuge einer Auktion genauso gerendert werden wie die neuesten. Der Leitfaden für Versicherungen erklärt eine Dekodierung Feld für Feld, und die VIN-Dokumentation behandelt unvollständige VINs und Fehler.

Manche Lose kommen ohne dekodierbare VIN: ein Fahrzeug für einen anderen Markt, eine von der Quelle falsch eingegebene VIN, ein Einlieferungsblatt mit Baujahr, Marke und Modell und sonst nichts. Statten Sie das Einlieferungsformular mit drei Dropdowns aus, die von GET /api/v1/vehicles gespeist werden – kostenlos und öffentlich: ?year= listet die Marken mit einem Modell in diesem Jahr, und ?year=&makeId= listet die Modelle dieser Marke, jeweils mit der Fahrzeug-ID dieses Modelljahrs.

Derselbe Katalog ist als offenes Paket @meterapp/vehicle-db verfügbar, sodass die Dropdowns auch offline mit der identischen Liste arbeiten können. So oder so enthält das Los am Ende dieselbe Art von ID wie eine dekodierte VIN, und kein nachgelagertes System muss Fahrzeugnamen als Freitext verarbeiten.

Wenn eine ganze Einlieferungsliste auf einmal eintrifft, liest POST /api/v1/vehicles/check bis zu 2.000 Einträge pro Aufruf, jeden so geschrieben wie in der Liste und mit der Losnummer als ref, und beantwortet jeden einzelnen: ein Treffer mit der zu speichernden ID, Vorschläge, kein Treffer oder eine ungültige Zeile. Nichts wird gerendert und nichts berechnet; Details finden Sie in der Dokumentation zu vehicles.

Platzieren Sie den Hinweis auf dem Bild selbst, wo der Blick eines Bieters landet, und im Alt-Text, nicht nur in der Beschreibung darunter. Zustand, Kilometerstand, Schäden, Ausstattung und die Lackierung des Fahrzeugs gehören in den Lostext und, sobald vorhanden, in die Fotos. Wenn die Fotos eintreffen, verschwindet das Rendering.

Erzeugen Sie die URL des Loses bei der Erfassung mit POST /api/v1/image-urls und einem Idempotency-Key, der aus Auktion und Los gebildet wird, aus Buchstaben, Ziffern, ., _, : und -. Die URL wird bei der Erzeugung bezahlt (1 Credit), daher würde eine wiederholte Erfassung ohne Key zweimal erzeugen und bezahlen. Mit Key:

• Derselbe Schlüssel mit demselben Body innerhalb von 24 Stunden gibt die erste Antwort erneut zurück, einschließlich derselben URL, mit Idempotent-Replayed: true und ohne erneute Abbuchung.
• Derselbe Key mit einem anderen Body ergibt 422, und ein Retry, der die erste Anfrage überholt, ergibt 409 mit Retry-After. Legen Sie also beim Anlegen des Loses alles im Body fest, einschließlich der Lebensdauer, und speichern Sie es zusammen mit dem Los.
• Speichern Sie die URL auch am Los: Der Schlüssel schützt Wiederholungsversuche, und die gespeicherte URL ist das, was die Seiten für den Rest der Auktion auslesen.

Bei einem ganzen Katalog, der auf einmal importiert wird, lassen sich bis zu 50 Lose pro Aufruf erzeugen, mit einem Idempotency-Key pro Batch; jede URL in der Antwort gibt das Fahrzeug und die Optionen zurück, für die sie erzeugt wurde.

ttl_seconds reicht bis 604800 (7 Tage); ein größerer Wert wird darauf begrenzt. Bei einer Auktion, die innerhalb der Woche endet, setzen Sie ihn auf die verbleibende Zeit bis zum Ende. Der Platzhalter funktioniert dann nicht mehr, sobald die Gebotsphase endet, und danach antwortet die URL mit 403.

• Eine zeitlich begrenzte Auktion von mehr als 7 Tagen: Erzeugen Sie die URL mit renew: true, ttl_seconds auf dem Maximalwert und renew_days passend zur Auktionsdauer. Jede weitere Woche, in der das Los geöffnet wird, kostet 1 Credit, Wochen ohne Aufrufe kosten nichts, und die Verlängerung endet bei renews_until.
• Belassen Sie max_uses bei 0, dem Standardwert: Eine unbegrenzte URL ist während ihrer gesamten Gültigkeit öffentlich cachebar, eine begrenzte dagegen ist private, no-store und schickt jeden Aufruf an den Origin-Server.
• Beschränken Sie den erzeugenden Schlüssel im Dashboard auf die Domains Ihrer Auktion: Ein auf eine andere Website kopiertes Losbild antwortet mit 403.

Jedes Los ist ein eigenes Fahrzeug, es sei denn, zwei Lose haben dieselbe Marke, dasselbe Modell und dasselbe Jahr. Jeder Plan begrenzt die Zahl unterschiedlicher Fahrzeuge pro Monat: Free 100, Pro 2.500 und Business 15.000; Enterprise ohne Obergrenze. Ein Fahrzeug, das in diesem Monat bereits ausgeliefert wurde, ist immer erlaubt. Ein Batch, der das Limit überschreiten würde, wird vollständig abgelehnt, bevor etwas berechnet wird, und die Antwort nennt Plan und Limit. Wählen Sie den Plan nach den Losen, die Sie pro Monat einstellen, nicht nach den Credits. Die Marketplace-Story beschreibt, wie Sie einen großen Import innerhalb der Rate- und Render-Limits takten.