API aplikacji pracownika

API aplikacji pracownika (/api/employee-app/v1, wersja 1.4) obsługuje aplikację mobilną personelu. Pracownik loguje się swoim kontem z panelu i może tam sprawdzić grafik, oddać albo zamienić zmianę, wypełnić deklarację dostępności, a na kolektorze ze skanerem prowadzić dokumenty magazynowe i spis z natury. API woła te same usługi co panel, więc reguły, komunikaty i blokady (np. zamknięty okres magazynowy) są wspólne. Pola i przykłady każdej operacji są w dokumentacji referencyjnej employee-app.yaml, w panelu pod /help/api/employee-app (gdzie ją znaleźć). Ten przewodnik opisuje przebiegi; przykłady są skrócone.

Zanim zaczniesz#

• Pracownik potrzebuje aktywnego konta z dostępem do panelu. Konto bez dostępu (np. klient portalu albo pracownik po zakończeniu zatrudnienia bez grup uprawnień) dostaje 403 NO_PANEL_ACCESS, konto wyłączone - 403 USER_INACTIVE. Oba warunki API sprawdza przy każdym żądaniu, nie tylko przy logowaniu.
• Uprawnienia to te same kody co w panelu. Najważniejsze dla aplikacji:

• Szczegóły produktu products.show
• Szczegóły magazynu warehouses.show
• Tworzenie dokumentów magazynowych warehouse_documents.create
• Zatwierdzanie dokumentów magazynowych warehouse_documents.confirm
• Korekty dokumentów magazynowych warehouse_documents.correct
• Storno dokumentów magazynowych warehouse_documents.reverse
• Przesunięcia międzyoperatorskie warehouse_documents.inter_operator
• Liczenie inventory_counts.edit
• Zatwierdzanie spisu z natury inventory_counts.confirm
• Pełny grafik ze współpracownikami my_schedule.full_view

Logowanie i token#

POST /auth/login
{ "email": "jan.kowalski@example.com", "password": "...", "code": "123456", "device_name": "Zebra TC21 - magazyn 1" }

200 { "success": true, "data": { "token": "12|Xk3...", "token_type": "Bearer", "expires_at": "2026-12-01T10:00:00+01:00", "user": { ... } } }

Nieznany e-mail i złe hasło dają ten sam błąd 422 VALIDATION_ERROR na polu email, więc API nie zdradza, które konta istnieją. Status konta i weryfikację dwuetapową API sprawdza dopiero po poprawnym haśle.

Kod odzyskiwania działa raz. System wymienia zużyty kod na nowy, a nowy komplet pracownik widzi w panelu. 403 TWO_FACTOR_SETUP_REQUIRED dostaje też każde żądanie z tokenem wydanym wcześniej, gdy grupa uprawnień nałożyła wymóg 2FA później.

Token działa tylko w tym API (zdolność employee-app); token aplikacji klienta dostaje 403 INVALID_TOKEN_TYPE. Token wygasa po 30 dniach bez użycia (expires_at), a każde użycie przesuwa termin. Zmiana albo reset hasła w panelu unieważnia wszystkie tokeny konta. W obu przypadkach kolejne żądanie dostaje 401 UNAUTHENTICATED i pracownik loguje się ponownie.

Sekcje aplikacji i uprawnienia#

GET /me → features mówi, które sekcje pokazać. Uprawnienia przelicza się z aktywnych grup uprawnień (pamięć podręczna 5 minut).

Brak uprawnienia daje 403 FORBIDDEN z polem error.required_permission. Uprawnienie nadaje administrator w panelu, w grupach uprawnień. Dokumenty, stany i spisy obejmują magazyny wszystkich operatorów, tak jak panel.

Moja praca#

„Moja praca” pokazuje wyłącznie dane z aktywnych zatrudnień konta. Cudzy grafik, wpis, prośba albo deklaracja dają 404 NOT_FOUND, a localization_uuid spoza zatrudnień - 404 LOCALIZATION_NOT_FOUND.

Grafik i wezwania do pracy#

• GET /me/schedule - moje zmiany ze wszystkich aktywnych zatrudnień, po dniu i godzinie. Zakres date_from - date_to domyślnie dziś + 13 dni, najwyżej 62 dni (dłuższy daje 422). Filtry: source, localization_uuid.
• GET /me/schedules - opublikowane grafiki lokalizacji, w których pracuję, z liczbą moich wpisów i minut.
• GET /me/schedules/{uuid} - moje wpisy w jednym grafiku, podsumowanie i liczba oczekujących próśb do mnie.
• GET /me/schedules/{uuid}/full - pełny grafik: zmiany wszystkich pracowników, filtry employee_group_uuid i search. Wymaga my_schedule.full_view.

Wpis grafiku (source: schedule) widać tylko z grafiku opublikowanego i w oknie widoczności: od daty „Widoczny od” (bez niej - od razu) do daty „Widoczny do”. Wezwanie do pracy spod rezerwacji (source: reservation) widać zawsze, póki wiąże - także poza grafikiem (schedule: null) i w grafiku jeszcze nieopublikowanym. Wezwanie spod zamówienia wstępnego ma valid_until i is_preliminary: true; znika po upływie ważności albo od razu po anulowaniu zamówienia. Pole work_call niesie okno pracy, nazwę pozycji i numer zamówienia, bez danych klienta.

W pełnym grafiku dane współpracowników są minimalne: nazwa, grupy pracownicze i godziny zmian, bez kontaktów, kart i PIN-ów. Pole is_me oznacza wiersz zalogowanego pracownika.

Prośba o zamianę albo przejęcie zmiany#

Po akceptacji zamiana wykonuje się od razu, bez zgody kierownika, a inne oczekujące prośby dotyczące tych zmian system anuluje. Prośba wygasa z końcem dnia przed zmianą. Odmowa reguł zamiany (zmiana przeszła, grafik nieopublikowany, kolizja godzin, inna oczekująca prośba) daje 409 SWAP_NOT_ALLOWED z powodami w error.errors. Prośba, która nie jest już oczekująca albo wygasła, daje 409 SWAP_NOT_PENDING. Wysyłanie próśb ma limit 30 żądań na minutę.

Deklaracja dostępności#

PUT /me/availability-declarations/{uuid}/days/2026-12-01
{ "type": "available", "preferred_group_uuid": "1b2c...", "time_slots": [ { "start_time": "08:00", "end_time": "12:00" }, { "start_time": "14:00", "end_time": "20:00" } ] }

• type: available (Dostępny), vacation albo off. Przy vacation i off API pomija przedziały.
• available bez time_slots znaczy „dostępny cały dzień” - tak samo czyta go przydział pracowników do rezerwacji i sprawdzanie kolizji z grafikiem.
• Przedziały (do 10) muszą kończyć się po początku i nie mogą na siebie nachodzić - inaczej 422 na polu time_slots. Dzień spoza okresu deklaracji daje 422 na polu date.
• preferred_group_uuid przyjmuje tylko jedną z aktywnych grup pracownika (lista employee_groups na karcie deklaracji). Inna grupa daje 422 na polu preferred_group_uuid, nieznany uuid - 404.
• Poza terminem wypełniania (przed fill_from albo po fill_until) zapis daje 409 DECLARATION_CLOSED.
• W dniu ze zmianą w opublikowanym grafiku vacation, off albo przedziały nieobejmujące zmiany dają 409 SCHEDULE_CONFLICT z listą kolizji w error.errors. Deklaracja nie może odebrać godzin z grafiku.

Każda zmiana trafia do historii deklaracji, tak jak zapis w panelu.

Skanowanie kodu i produkty#

GET barcode/{code} to główne wejście skanera. Szuka aktywnego produktu po kolei: po kodzie kreskowym artykułu albo SKU, po kodzie kreskowym opakowania zbiorczego, na końcu po kodzie produktu. Zwraca produkt, stany we wszystkich magazynach i cenę z cenników lokalizacji. Produkt ma is_stock_item, is_package, allows_fractional_quantity i units (jednostki dodatkowe z kodami EAN).

Cenę API liczy dla lokalizacji z parametru localization_uuid, a bez niego - dla domyślnej lokalizacji użytkownika. Brak lokalizacji daje price: null, a nieznany localization_uuid - 404 LOCALIZATION_NOT_FOUND.

Dokument magazynowy krok po kroku#

Reguła operatora obowiązuje już przy wystawieniu i przy zmianie nagłówka: MM tylko między magazynami tego samego operatora, PMO tylko do magazynu innego operatora. Naruszenie daje 422 na polu target_warehouse_uuid. Pozostałe warunki (pozycje, data, okres zamknięty, stan) sprawdza zatwierdzenie.

• Skan kodu opakowania zbiorczego ustawia jednostkę wprowadzenia (np. zgrzewka); unit_uuid wskazuje ją wprost.
• accepts_price: false (WZ, RW, MM, INW i ich korekty): API pomija cenę towaru i zapisuje 0. Wartość rozchodu liczy wycena FIFO przy zatwierdzeniu. Opakowanie zwrotne ma zawsze cenę równą kaucji.
• PZ, WZ, MM i PMO same dokładają podpozycje opakowań przypisanych do artykułu (line_kind: package, parent_item_uuid).
• Flagi can_edit, can_delete, can_confirm, can_cancel, can_correct, can_duplicate (oraz can_reverse na karcie dokumentu) opisują stan dokumentu. Uprawnienia serwer sprawdza dopiero przy operacji - zestaw je z GET /me → permissions.
• Anulować można tylko szkic (POST .../cancel, powód 5-500 znaków). Zatwierdzony dokument cofa storno.

stock-preview i error.warnings wskazują pozycję i produkt przez item_uuid i product_uuid. Pola item_id i product_id zostały tylko dla zgodności i są przestarzałe.

Korekta, storno, kopia i wydruk#

Korektę prowadzi się tak: utwórz szkic korekty, zmień stan „po korekcie” każdej pozycji przez PUT .../items/{item} (quantity = ilość po korekcie w jednostce ewidencyjnej, może być 0; price_net = cena po korekcie), potem zatwierdź POST .../confirm. Do korekty nie dodaje się pozycji. Gdy z tego samego stanu powstały dwa szkice korekty, drugi przy zatwierdzeniu dostaje DOCUMENT_VALIDATION_FAILED.

Nie koryguje się szkiców, dokumentów anulowanych i wystornowanych, INW ani PMO i dokumentów z PMO. PMO stornuje się w całości - razem z WZ i PZ, które z niego powstały. Korekty stornuje się od najnowszej. Storno nie wyprowadzi stanu poniżej zera w magazynie, który na to nie pozwala. Zasady opisują artykuły Dokumenty magazynowe i Korekty i storno.

Spis z natury#

Stan księgowy to suma ruchów do chwili odcięcia snapshot_at (domyślnie teraz), więc sprzedaż w trakcie liczenia nie wpływa na wynik. Zatwierdzenie zapisuje stany i różnice, a różnice księguje dokumentem INW z chwilą odcięcia (warehouse_document w odpowiedzi; bez różnic dokument nie powstaje). Bez uncounted_policy przy pozycjach niepoliczonych zatwierdzenie daje 422. Spis w toku można anulować (POST .../cancel, powód 5-500 znaków) - bez skutków w ewidencji.

Spis na ślepo (is_blind: true): do zatwierdzenia osoby liczące bez inventory_counts.confirm nie widzą stanu księgowego ani różnic. Wtedy book_quantity i difference = null, w podsumowaniu differences, shortage i surplus = null, a filter=differences daje 409 BLIND_COUNT. Karta spisu ma book_revealed

• czy to konto widzi stan księgowy. Po zatwierdzeniu wszystko jest jawne.

Odmowa usługi spisu daje 409 INVENTORY_COUNT_REFUSED: chwila odcięcia z przyszłości albo w zamkniętym okresie magazynowym, nieznany kod, produkt spoza ewidencji magazynowej, ilość ułamkowa artykułu niepodzielnego, spis już zamknięty. Wartości różnic (FIFO) API nie zwraca. Zasady spisu: Inwentaryzacja.

Listy, limity i parametry#

Listy są stronicowane: page i per_page (1-100, domyślnie 25; GET /me/schedule - domyślnie 50), wynik w data.items i data.pagination. Zasoby wskazuje się przez uuid. Parametr ścieżki, który nie jest uuid, daje 404 przed wykonaniem operacji. search ma najwyżej 100 znaków. Nieznany warehouse_uuid, operator_uuid, contractor_uuid albo product_uuid w filtrach list daje 404 NOT_FOUND, a nie pustą listę.

Całe API ma limit 120 żądań na minutę, z własnym licznikiem, niezależnym od pozostałych interfejsów. Osobne limity mają logowanie (5 na minutę na parę e-mail + IP), prośby o zamianę i wydruki PDF (po 30 na minutę). Przekroczenie daje 429 HTTP_ERROR z nagłówkiem Retry-After. Nieoczekiwany błąd serwera daje 500 SERVER_ERROR w tej samej kopercie. Pełna lista kodów: Kody błędów.

Zmiany niezgodne wstecz w 1.3 i 1.4#

Aplikacja napisana dla wersji 1.1 albo 1.2 wymaga przeglądu w tych miejscach:

W 1.4 zmieniło się też znaczenie dnia „Dostępny” bez godzin: to cały dzień także przy kolizjach z grafikiem, więc taki zapis nie daje już 409 SCHEDULE_CONFLICT. Historia wszystkich wersji: Zmiany w API.