Obrazy samochodów do ofert aukcyjnych

Katalog aukcji trafia do sieci, gdy tylko spłyną zgłoszenia: dla każdego samochodu numer VIN, numer pozycji i data sprzedaży. Zdjęcia pojawiają się, gdy samochód dotrze na plac, a fotograf do samochodu, co w przypadku części aukcji następuje już po otwarciu licytacji. Do tego czasu każda z tych pozycji to szary prostokąt obok linijki tekstu.

Katalogowy render wypełnia to miejsce właściwym rocznikiem. Aukcja to jednak również miejsce, w którym render nigdy nie może uchodzić za dany samochód: licytujący wyceniają stan pojazdu, a render go nie pokazuje, ponieważ nie przedstawia żadnego konkretnego fizycznego pojazdu. Wszystko, co poniżej, wynika z jednoczesnego uwzględnienia obu tych faktów.

• Render dla każdego lotu na podstawie numeru VIN, wyświetlany tylko do czasu pojawienia się własnych zdjęć lotu.
• Wybór z katalogu dla lotów, których VIN się nie dekoduje.
• Oznaczenie na obrazie: „Render katalogowy, nie ta pozycja”.
• Jeden URL na pozycję aukcyjną, generowany raz z Idempotency-Key, ważny przez cały czas trwania sprzedaży.

GET /api/v1/vin/{vin} jest bezpłatny. Gdy katalog zawiera dany pojazd, odpowiedź zawiera data.vehicle.id – stały identyfikator do zapisania przy locie; zdekodowana wersja wyposażenia, nadwozie i silnik pozostają w tekście lotu. Katalog obejmuje lata od 1990 do 2027, więc starsze pojazdy na aukcji renderują się tak samo jak najnowsze. Przewodnik dla ubezpieczeń omawia dekodowanie pole po polu, a dokumentacja VIN opisuje częściowe numery VIN i błędy.

Niektóre pozycje aukcyjne trafiają bez numeru VIN, który da się zdekodować: pojazd wyprodukowany na inny rynek, VIN błędnie wpisany przez źródło, karta komisowa z rokiem, marką i modelem i niczym więcej. Wystarczy dodać do formularza komisowego trzy listy rozwijane zasilane przez GET /api/v1/vehicles, które jest bezpłatne i publiczne: ?year= zwraca marki mające model w danym roku, a ?year=&makeId= zwraca modele tej marki, każdy z identyfikatorem pojazdu dla danego rocznika.

Ten sam katalog jest dostępny jako otwarty pakiet @meterapp/vehicle-db, więc listy rozwijane mogą działać także offline na identycznej liście. Tak czy inaczej pozycja aukcyjna otrzymuje ten sam rodzaj id co zdekodowany VIN i na dalszych etapach nic nie zapisuje nazwy samochodu tekstem.

Gdy cała lista zgłoszonych pojazdów przychodzi naraz, POST /api/v1/vehicles/check przyjmuje do 2000 pozycji na wywołanie, każdą zapisaną tak jak na liście i z numerem lotu jako ref, i odpowiada na każdą z nich: dopasowaniem z id do zapisania, sugestiami, brakiem dopasowania lub informacją o nieprawidłowym wierszu. Nic nie jest renderowane ani naliczane; szczegóły znajdą Państwo w dokumentacji vehicles.

Oznaczenie należy umieścić na samym zdjęciu, tam, gdzie pada wzrok licytującego, oraz w tekście alternatywnym, a nie tylko w opisie pod spodem. Stan, przebieg, uszkodzenia, wyposażenie dodatkowe i lakier samochodu należą do opisu pozycji aukcyjnej oraz – gdy już powstaną – do zdjęć. Gdy pojawią się zdjęcia, render znika.

URL pozycji należy wygenerować przy jej przyjęciu za pomocą POST /api/v1/image-urls z nagłówkiem Idempotency-Key utworzonym z aukcji i pozycji, złożonym z liter, cyfr oraz znaków ., _, : i -. URL liczy swój obraz jako obraz pojazdu w danym miesiącu w chwili wygenerowania, więc bez klucza ponowione przyjęcie wygenerowałoby drugi URL. Z kluczem:

• Ten sam klucz z tą samą treścią w ciągu 24 godz. odtwarza pierwszą odpowiedź, łącznie z tym samym URL, z nagłówkiem Idempotent-Replayed: true i bez ponownego obciążenia.
• Ten sam klucz z inną treścią żądania daje 422, a ponowienie, które wyprzedzi pierwsze żądanie, daje 409 z nagłówkiem Retry-After. Dlatego całą treść żądania, łącznie z czasem ważności, należy ustalić przy tworzeniu pozycji aukcyjnej i zapisać razem z nią.
• Adres URL warto też zapisać przy pozycji: klucz chroni ponowienia, a zapisany URL jest tym, co strony odczytują do końca aukcji.

Przy imporcie całego katalogu naraz można wygenerować adresy dla maksymalnie 50 pozycji aukcyjnych na wywołanie, z jednym kluczem na partię; każdy URL w odpowiedzi zawiera pojazd i opcje, dla których został wygenerowany.

ttl_seconds może wynosić maksymalnie 604800 (7 dni); dłuższa wartość zostanie do niej obcięta. W przypadku sprzedaży kończącej się w ciągu tygodnia należy ustawić czas pozostały do jej zamknięcia. Obraz poglądowy przestaje wtedy działać razem z końcem licytacji, a potem URL zwraca 403.

• Aukcja czasowa dłuższa niż 7 dni: należy wygenerować URL z renew: true, ttl_seconds ustawionym na maksimum i renew_days obejmującym czas trwania aukcji. Odnowienie liczy obraz raz w miesiącu, w którym nastąpi, i nic więcej, jeśli obraz został już policzony w tym miesiącu; tygodnie, w których nikt nie otwiera pozycji, nic nie kosztują, a odnawianie kończy się na renews_until.
• Należy pozostawić max_uses na 0, czyli wartość domyślną: URL bez limitu może być publicznie buforowany przez cały okres ważności, a URL z limitem ma ustawienie private, no-store i kieruje każde wczytanie do serwera źródłowego.
• Klucz generujący należy ograniczyć do domen aukcji w panelu: obraz pozycji aukcyjnej skopiowany na inną stronę zwraca 403.

Każda pozycja aukcyjna to jeden obraz pojazdu — jej pojazd w jej lakierze i widoku — chyba że dwie pozycje mają wszystkie trzy cechy wspólne. Każdy plan obejmuje określoną liczbę obrazów pojazdów miesięcznie: Free 100, Pro 2500 i Business 10 000; Enterprise podlega negocjacjom. Obraz już policzony w tym miesiącu jest zawsze wyświetlany, a partia, która przekroczyłaby limit, jest w całości odrzucana, zanim cokolwiek zostanie policzone; odpowiedź zawiera plan i limit. Plan warto dobrać do liczby pozycji wystawianych w miesiącu. Studium przypadku platformy ogłoszeniowej opisuje, jak rozłożyć duży import w czasie w ramach limitów żądań i renderowania.