Allegro odrzuca zdjęcia z BaseLinkera: format AVIF w REST API WooCommerce

Allegro odrzuca zdjęcia z BaseLinkera, gdy sklep WooCommerce oddaje przez REST API pliki AVIF, których nie ma na liście obsługiwanych formatów. Problem pojawia się „czasem”, bo wtyczka do kompresji obrazów nazywa pliki niekonsekwentnie, a kod podmieniający format szuka zamiennika po złej nazwie. Poniżej opisujemy, jak znaleźliśmy przyczynę przy katalogu z ponad 26 tysiącami plików AVIF, jak wygląda naprawa i dlaczego sama konwersja plików nie wystarczyła.

Dlaczego Allegro odrzuca zdjęcia z WooCommerce przez BaseLinkera?

Allegro w dokumentacji zdjęć wymienia formaty jpg, jpeg i png, a webp dopuszcza tylko przy wystawianiu przez API lub z pliku. AVIF na tej liście nie ma. BaseLinker pobiera adresy zdjęć z REST API sklepu, więc jeśli WooCommerce zwróci .avif, oferta trafia do Allegro z plikiem, którego platforma nie zaakceptowała, a zdjęcie jest odrzucane.

Zgłoszenie brzmiało: „BaseLinker dostaje AVIF”. Kluczowe było jedno słowo, które padło przy opisie: czasem. Część zdjęć tych samych produktów przechodziła bez problemu, a część nie. To zwykle oznacza, że błąd nie leży w konfiguracji, tylko w warunku, który spełnia tylko część plików.

Dlaczego problem pojawia się tylko czasem?

Wtyczka Imagify zapisuje skonwertowany plik pod nazwą z sufiksem, a oryginał zostaje bez niego. Funkcja w motywie podmieniała adres AVIF na JPEG, ale zmieniała wyłącznie rozszerzenie i zostawiała nazwę bazową. W praktyce wyglądało to tak:

na dysku:         X-1-compressed.avif  +  X-1.webp
funkcja szukała:  X-1-compressed.webp  ->  nie istnieje  ->  fallback zwracał AVIF

Pliki bez sufiksu (X-8.avif obok X-8.jpg) działały poprawnie. Stąd „czasem”. Skala: w katalogu leżało 26 280 oryginałów w AVIF, a do API w tej postaci trafiały 527 zdjęć. Dla pozostałych funkcja trafiała w JPEG obok pliku.

Jak dobrać zamiennik dla AVIF w odpowiedzi API?

Zamiast jednej podmiany rozszerzenia funkcja próbuje kolejno kilku źródeł i zatrzymuje się na pierwszym, które istnieje:

1. JPEG lub PNG obok pliku,
2. JPEG lub PNG w kopii zapasowej Imagify,
3. to samo po obcięciu sufiksów -compressed i -scaled,
4. największa miniatura w bezpiecznym formacie z metadanych (zwykle 768×768),
5. WebP, jako ostatnia deska (Allegro dopuszcza go tylko przy wystawianiu przez API),
6. adres wejściowy bez zmian.

WebP stoi po miniaturach celowo. JPEG 768×768 to format z podstawowej listy Allegro, więc jest bezpieczniejszy niż WebP w pełnym rozmiarze. Funkcja dostaje też opcjonalnie identyfikator załącznika, który REST API i tak ma w odpowiedzi, więc nie trzeba przy każdym zdjęciu wywoływać attachment_url_to_postid().

Front sklepu zostaje bez zmian. Podmiana działa tylko w filtrach woocommerce_rest_prepare_product_object i wariantu, z priorytetem 30. Odwiedzający sklep dalej dostają AVIF i WebP, a integracje bezpieczny JPEG.

Masz ten sam problem? Allegro odrzuca zdjęcia, a sklep ma tysiące plików? Znajdziemy, gdzie trafia zły format, i naprawimy to bez ruszania frontu. Opisz sytuację →

Co zrobić z plikami, które nie mają żadnego zamiennika?

Dwanaście plików AVIF nie miało żadnego JPEG ani PNG: wszystkie pochodziły z kreatora produktów, który zapisywał obrazy od razu w nowoczesnym formacie. Zamienniki wygenerowaliśmy jednorazowym skryptem na serwerze (avifdec, potem convert -quality 88) i zapisaliśmy obok pliku AVIF pod tą samą nazwą bazową, żeby trafiały w pierwszy krok łańcucha. Całą partię konwersji AVIF do JPEG (1 515 plików) skończyliśmy bez pominięć i bez błędów, a skan API pokazał zero AVIF.

Dlaczego zamieniliśmy też WebP i co poszło nie tak z bramką?

Po AVIF zostało 1 511 zdjęć w WebP, wgranych przez kreator produktów bez oryginału i bez kopii w Imagify. Allegro dopuszcza WebP przy wystawianiu przez API, a zgłoszenie dotyczyło AVIF, ale za zgodą klienta ujednoliciliśmy format, żeby żadna ścieżka wystawiania nie zależała od tego wyjątku. Skrypt wsadowy przeszedł po 1 508 plikach z listy (-quality 88 -strip), zostawiając pliki WebP na miejscu. Zakończenie wyglądało dobrze: 692 pliki przekonwertowane, 816 pominiętych, bo JPEG już leżał obok, zero błędów.

API mimo to dalej zwracało WebP, czyli nie to, czego chcieliśmy. Funkcja nazywała się „podmień AVIF” i na samym początku miała warunek:

$ext = strtolower( pathinfo( $url, PATHINFO_EXTENSION ) );
if ( $ext !== 'avif' ) {
    return $url;   // WebP wychodził tutaj i nigdy nie szukał JPEG-a
}

Cały sześciostopniowy łańcuch był dla WebP nieosiągalny. Poprawka polegała na przepuszczeniu przez bramkę obu rozszerzeń, a resztę zostawiliśmy bez zmian. Test logiki objął siedem przypadków: WebP z JPEG obok, WebP bez JPEG, regresja AVIF, AVIF z sufiksem, JPEG nietknięty, WebP z backupu Imagify i WebP z miniatury.

Jak potwierdzić, że wszystkie zdjęcia są bezpieczne dla Allegro?

Wynik sprawdzamy pełnym skanem. Skrypt przeszedł po 18 233 załącznikach produktowych (miniatury i galerie), wywołał tę samą funkcję co REST API i policzył rozszerzenia:

Sprawdziliśmy też front: plik -550x550.avif dalej odpowiadał 200 z nagłówkiem image/avif, a plik .webp z image/webp.

Dlaczego deploy na produkcję cicho się nie powiódł?

Przy wdrożeniu poprawki git pull na serwerze zatrzymał się z komunikatem, że lokalne zmiany w pliku z funkcją zostałyby nadpisane. Plik został wcześniej wgrany ręcznie przy pierwszym hotfiksie i nigdy nie trafił do repozytorium. Zanim go odrzuciliśmy, porównaliśmy git diff z gałęzią docelową: wersja na dysku okazała się starsza od docelowej i zawierała tylko nasze własne zmiany. Dopiero wtedy zrobiliśmy kopię i nadpisaliśmy ją.

Reguła jest prosta. Ręcznie wgrany plik blokuje każdy kolejny deploy, a przy złym odruchu można nadpisać cudzy hotfix. Przed odrzuceniem zmiany obejrzyj diff.

Kiedy zlecić to specjalistom?

Gdy oferty na Allegro wychodzą bez zdjęć, a w sklepie jest tysiące plików w różnych formatach i nie wiadomo, które z nich dotyczy problem. W ASAPDevs naprawiamy łańcuch od strony sklepu w ramach integracji z BaseLinkerem, a jeśli chcesz zrezygnować z pośrednika, zobacz alternatywę dla BaseLinkera. Jak opisywać oferty w API, piszemy w artykule o Allegro API w praktyce.

Źródła: pomoc Allegro, zasady dla zdjęć (formaty jpg, jpeg, png; webp przy wystawianiu przez API); dokumentacja WooCommerce REST API (odpowiedź produktu z polem images); dokumentacja Imagify (konwersja do WebP i AVIF).