Zmiany w API

Każdy plik OpenAPI ma własny numer wersji w polu info.version. Wersja rośnie, gdy zmienia się kontrakt, który klient musi znać: nowe operacje, pola albo reguły. Adresy bazowe (/v1) się nie zmieniają - wszystkie zmiany poniżej są zgodne wstecz, chyba że opis mówi inaczej (zmiany niezgodne wstecz są oznaczone niezgodne wstecz).

Aplikacja mobilna klienta#

1.4 (2026-11-02)#

Wdrożenie ustaleń z zespołem aplikacji (A1-A6, Treści i cele przycisków):

• nowa operacja POST content/events - paczka do 100 pokazań i kliknięć, wynik dla każdego zdarzenia, okno occurred_at 24 h wstecz i 5 min w przód; zalecany sposób pomiaru zamiast pojedynczych content/{uuid}/impression i click, które zostają dla zgodności;
• nagłówek X-Device-Id - sesja pomiaru gościa, osobna od device_id logowania;
• link.url zawsze https; adres zewnętrzny bez https nie daje przycisku;
• ekran celu wybiera się wyłącznie po link.type + link.params, deep_link jest tylko informacyjny;
• opis oczekiwanego przebiegu trybu gościa i powrotu do celu po logowaniu.

W obrębie 1.4 dokumentacja została później uzupełniona do stanu kodu, bez zmian w API (kontrakt jest ten sam):

• treść żądań i odpowiedzi logowania (auth/verify-code, auth/register, auth/login, auth/refresh) z wartościami status (authenticated, registration_required, registered);
• opisane kody odmów logowania, konta i urządzeń: LOGIN_CHANNEL_DISABLED, AUTH_ERROR, INVALID_IDENTIFIER, CODE_VERIFICATION_FAILED, INVALID_VERIFICATION_TOKEN, REGISTRATION_FAILED, PASSWORD_LOGIN_DISABLED, LOGIN_FAILED, PASSWORD_ALREADY_SET, PASSWORD_NOT_SET, INVALID_PASSWORD, INVALID_CONFIRMATION_CODE, CANNOT_REVOKE_CURRENT, FORBIDDEN, METHOD_NOT_ALLOWED;
• odpowiedzi błędów z konkretnymi kodami dla każdego statusu HTTP zamiast jednego ogólnego przykładu;
• tabela limitów żądań wszystkich tras i limitów prób w operacjach;
• uwaga, że GET version zwracało na stałe api_version: 1.0.0; od 2026-11-02 api_version podaje wersję kontraktu, czyli info.version (1.4), a features - sekcje obsługiwane przez serwer (o sekcjach marki decyduje brand/config).

Zmiany działania z 2026-11-02 w tej samej wersji (bez podbicia numeru):

• konto pracownika (z dostępem do panelu) nie ustawia ani nie zmienia hasła i nie dezaktywuje konta w aplikacji - 403 STAFF_ACCOUNT_LOCKED w POST i PUT account/password oraz DELETE account; zmiana e-maila albo telefonu takiego konta daje 403 STAFF_ACCOUNT_CONTACT_LOCKED (imię i nazwisko zmienia normalnie);
• nieobsłużony błąd serwera przychodzi w kopercie z kodem 500 SERVER_ERROR zamiast { "message": "Server Error" };
• parametry ścieżki muszą mieć właściwą postać (uuid, a devices/{id} - liczba), inaczej 404 NOT_FOUND;
• auth/refresh waliduje device_name i device_id (napisy do 255 znaków, inaczej 422);
• lista devices i odłączanie urządzeń obejmują tylko tokeny aplikacji klienta;
• każda trasa logowania liczy żądania własnym licznikiem na adres IP.

1.3 (2026-11-02)#

• sklep w wielu lokalizacjach: GET shop/localizations, opcjonalny localization_uuid w katalogu, na karcie produktu i przy dodaniu do koszyka, fiscal_localization w koszyku i zamówieniu, nowe odmowy LOCALIZATION_NOT_AVAILABLE i SHOP_OTHER_OPERATOR, DELETE shop/cart;
• treści marketingowe w aplikacji: content, content/home, news, news/{uuid}, pokazania i kliknięcia, obiekt link celu przycisku; operacje treści działają także bez tokenu (gość).

1.2 (2026-11-01)#

• sklep marki: katalog, koszyk z kodami rabatowymi, GET/POST shop/checkout ze startem PayU i wymaganym Idempotency-Key, „Moje zakupy” z dokumentami, prośba o zwrot;
• „Moje bilety”: lista, karta z kodem QR, zmiana dnia wizyty, „Dodaj bilet kodem”.

1.1 (2026-11-01)#

• dokumentacja zgodna z kodem w jednym pliku public/api-docs/mobile-app.yaml;
• do dokumentacji doszły profile osób (account/profiles), dane do faktury (account/contractors), klucz kodu klienta offline (customer-code/offline-key), nagrody, zamówienia z dokumentami PDF i stan płatności online;
• w tej wersji doszły też e-paragony (account/e-receipts) i sprzeciw wobec profilowania (account/profiling-objection).

1.0.0#

Pierwsza wersja: marka, logowanie, konto i zgody, kod klienta, urządzenia, punkty lojalnościowe.

Synchronizacja#

1.2 (2026-11-02)#

Numer obejmuje zmiany, które w 1.1 doszły bez podbicia wersji, i uzupełnienia dokumentacji:

• bilety do wykorzystania: GET ticket-entitlements/{code}, POST ticket-entitlements/redeem, POST ticket-entitlements/release, GET sales/{uuid}/ticket-entitlements;
• nowe zasoby wypychania: ticket_entitlements, ticket_entitlement_redemptions, marketing_pos_counters, marketing_receipt_prints, marketing_screen_counters; pola e-paragonu w sales;
• pobieranie pliku z wznowieniem (Range, odpowiedzi 206 i 416);
• pełna lista powodów skipped w schemacie PushResourceResult, w tym TOTAL_MISMATCH i RETURN_EXCEEDS_SALE dla zwrotów z kasy;
• poprawiony opis uwierzytelniania: lokalizacja wyłączona daje 403 LOCALIZATION_INACTIVE, a nie 401; opisany kod 401 LOCALIZATION_NOT_AUTHENTICATED;
• tabela limitów własnych operacji;
• uwaga, że meta.api_version kontrahentów i użytkowników zwraca na stałe 1.0.

Uzupełnienia z 2026-11-02 w tej samej wersji (zgodne wstecz, ale kasa wymaga aktualizacji, żeby z nich korzystać):

• daty w rekordach pull w czasie ściennym strefy aplikacji (2026-11-05, 2026-11-05 10:00:00) zamiast UTC;
• zakres operatora w pull: operators, localizations i files innych operatorów przychodzą jako _op: delete, a odsyłacze do nich jako null - kasa po aktualizacji raz pobiera wszystko od nowa;
• lista warnings w wyniku push z nowym powodem SALE_PROCESSED_LOCKED (pola fields i message) - zmiany przetworzonej sprzedaży pominięte przez chmurę;
• nowy powód skipped: SYNC_ERROR (rekord do ponowienia);
• coupon_redemptions ponad limit użyć przyjmowane z alarmem operatora PROMOTION_USAGE_OVER_LIMIT;
• każdy limit własny operacji liczy żądania osobnym licznikiem;
• meta.api_version kontrahentów i użytkowników podaje wersję kontraktu (1.2), a nie stałe 1.0;
• nieobsłużony błąd serwera poza pull i push przychodzi w kopercie z kodem 500 SERVER_ERROR;
• nagrobki także dla employees (pracownik przeniesiony do innej lokalizacji) i invoices (faktura usunięta trwale).

Opis: API synchronizacji.

1.1 (2026-11-01)#

• pełna dokumentacja wszystkich operacji api/sync/v1, zgodna z kodem; do dokumentacji doszły m.in. pliki i raporty kasy, kody rabatowe, faktury i należności, paragony z chmury, rachunki z chmury, identyfikatory, zamówienia i wypłaty zwrotów;
• niezgodne wstecz: usunięta operacja POST users/{id}/reset-password - hasła nie ustawia się przez API synchronizacji (PASSWORD_NOT_ALLOWED);
• kody rabatowe na kasie wymagają uprawnienia bills.create pracownika z X-User-Uuid;
• localization_uuid porównywany bez rozróżniania wielkości liter;
• token lokalizacji wyłączonej daje 403 LOCALIZATION_INACTIVE (nieznany token nadal 401 INVALID_SYNC_TOKEN);
• kody błędów PDF faktury (INVOICE_NOT_FOUND, PDF_NOT_AVAILABLE).

W obrębie wersji 1.1 doszły później, bez zmiany numeru, operacje i zasoby opisane w wersji 1.2.

1.0.0#

Pierwsza wersja: ping, pobieranie, wypychanie, rozpoznanie klienta, kontrahenci i użytkownicy.

Aplikacja pracownika#

Opis przebiegów: API aplikacji pracownika.

1.4 (2026-11-02)#

• nowa operacja GET me/schedules/{uuid}/full - pełny grafik ze współpracownikami (nazwa, grupy, godziny zmian) za nowym uprawnieniem my_schedule.full_view; to samo uprawnienie chroni ekran Moja rola › Pełny grafik w panelu; GET me → features.full_schedule;
• spis z natury na ślepo: POST inventory-counts przyjmuje is_blind; lista i karta spisu zwracają is_blind, karta - book_revealed; w spisie na ślepo w toku konto bez inventory_counts.confirm dostaje book_quantity i difference = null, podsumowanie bez różnic, a filter=differences daje 409 BLIND_COUNT;
• niezgodne wstecz: preferowana grupa w deklaracji dostępności (preferred_group_uuid) tylko spośród aktywnych grup pracownika - inna daje 422; employee_groups karty deklaracji zawiera już tylko te grupy;
• dzień „Dostępny” bez godzin znaczy „cały dzień” także przy sprawdzaniu kolizji z grafikiem - w dniu ze zmianą nie daje już 409 SCHEDULE_CONFLICT.

1.3 (2026-11-02)#

• dokumenty magazynowe w nowej formule: POST warehouse-documents/{uuid}/correction (szkic korekty PZK, WZK, RWK, MMK), reverse (storno), duplicate (kopia), GET .../pdf (wydruk, 30 na minutę);
• spis z natury inventory-counts: otwarcie, pozycje, skan, ilość wprost, zatwierdzenie z dokumentem INW i zasadą dla niepoliczonych (uncounted_policy), anulowanie;
• „Moja praca” bez uprawnień panelu, tylko dla własnych aktywnych zatrudnień: GET me/schedule, me/schedules, me/schedules/{uuid}, zamiany zmian (me/schedule-entries/{entry}/swap-targets..., me/swap-requests...), deklaracje dostępności (me/availability-declarations...); GET me → features;
• nowe kody DOCUMENT_NOT_CORRECTABLE, DOCUMENT_NOT_DUPLICABLE, DOCUMENT_NOT_REVERSIBLE, INVENTORY_COUNT_REFUSED, SWAP_NOT_ALLOWED, SWAP_NOT_PENDING, DECLARATION_CLOSED, SCHEDULE_CONFLICT;
• nowe pola dokumentu: operator, total_deposit, reversed_at, reversal_reason, is_correction, accepts_price, can_delete, can_correct, can_duplicate, corrected_document, source_document, linked_document, inventory_count, na karcie can_reverse; pozycji - is_correction_line; produktu - is_stock_item, is_package, allows_fractional_quantity, units;
• filtry listy dokumentów operator_uuid i contractor_uuid; zmiana magazynu w nagłówku (warehouse_uuid); zmiana artykułu i jednostki pozycji (product_uuid, unit_uuid);
• niezgodne wstecz: POST warehouse-documents wymaga contractor_uuid dla PZ i WZ oraz target_warehouse_uuid dla MM i PMO i sprawdza regułę operatora (MM - ten sam, PMO - inny) już przy wystawieniu (422); powód anulowania 5-500 znaków; cena towaru na dokumentach rozchodowych jest pomijana (0, wartość z FIFO); nieznany warehouse_uuid albo product_uuid w filtrach listy dokumentów i księgi ruchów daje 404 zamiast pustej listy; search najwyżej 100 znaków; parametry ścieżki muszą być uuid.

1.2 (2026-11-02)#

• logowanie z weryfikacją dwuetapową jak w panelu: konto z 2FA podaje code albo recovery_code w POST auth/login; nowe kody TWO_FACTOR_CODE_REQUIRED, INVALID_TWO_FACTOR_CODE, TOO_MANY_ATTEMPTS;
• konto, któremu grupa uprawnień nakłada 2FA, a które go nie skonfigurowało, nie dostaje tokenu, a token wydany wcześniej przestaje działać (403 TWO_FACTOR_SETUP_REQUIRED);
• zmiana albo reset hasła konta w panelu unieważnia wszystkie jego tokeny aplikacji pracownika (kolejne żądanie: 401 UNAUTHENTICATED);
• całe API ma limit 120 żądań na minutę z własnym licznikiem;
• w tej samej wersji (2026-11-02): nieobsłużony błąd serwera przychodzi w kopercie z kodem 500 SERVER_ERROR.

1.1 (2026-11-01)#

• pełna dokumentacja wszystkich operacji api/employee-app/v1, zgodna z kodem;
• podgląd stanów i ostrzeżenia STOCK_WARNINGS wskazują pozycję i produkt przez item_uuid / product_uuid; item_id i product_id są przestarzałe;
• nieznany localization_uuid daje 404 LOCALIZATION_NOT_FOUND zamiast pustej ceny;
• lista magazynów jest stronicowana;
• token wygasa po 30 dniach bez użycia.

1.0.0#

Pierwsza wersja: logowanie, dane konta, skan, produkty, stany i dokumenty magazynowe.

Jak śledzić zmiany#

Porównaj info.version pliku OpenAPI z wersją, dla której pisałeś klienta. Pliki są publiczne pod adresem https://<adres panelu>/api-docs/<plik>.yaml, więc możesz je sprawdzać automatycznie, np. w testach kontraktowych. Gdy numer wzrósł, przeczytaj ten artykuł i opis zmienionych operacji w dokumentacji referencyjnej.