Pracownicy i uprawnienia

Konto pracownicze to osobna tożsamość logowania (własny email i hasło), która pracuje na danych konta głównego. Właściciel nadaje pracownikowi uprawnienia z zamkniętego rejestru, np. tylko podgląd dokumentów albo pełne wystawianie faktur. Przez API możesz zautomatyzować zakładanie takich kont, np. przy wdrażaniu nowego pracownika w systemie HR.

Zakresy uprawnień API: employees:browse, employees:create, employees:update, employees:delete.

Jedno rozróżnienie jest ważne: uprawnienia pracowników to nie to samo co scope'y API. Scope'y ograniczają, co może zrobić Twój token API. Uprawnienia pracownika ograniczają, co dana osoba może zrobić po zalogowaniu w aplikacji Fakturnia. Token API zawsze działa w imieniu konta głównego.

Rejestr uprawnień#

Lista dostępnych uprawnień z etykietami i opisami (do wyświetlenia w Twoim UI). Wymaga jedynie ważnego tokenu, bez dodatkowego scope'a:

curl -s https://prod.api.fakturnia.pl/external/v1/employees/permissions \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "permissions": [
      { "key": "documents:read", "label": "Podgląd dokumentów", "description": "Przeglądanie faktur…" },
      { "key": "documents:write", "label": "Wystawianie dokumentów", "description": "Tworzenie, edycja…" }
    ]
  }
}

Traktuj rejestr jak słownik: pobieraj go zamiast wpisywać klucze na sztywno. Nieznane klucze przesłane przy tworzeniu lub edycji konta są po prostu ignorowane.

Tworzenie konta pracowniczego#

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/employees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jan",
    "lastName": "Kowalski",
    "emailAddress": "jan@firma.pl",
    "password": "bezpieczne-haslo",
    "permissions": ["documents:read", "documents:write"]
  }'

Zasady:

• email jest globalnie unikalny w całej Fakturni; kolizja zwraca 409 z kodem EMAIL_TAKEN,
• hasło ma minimum 8 znaków (422 przy krótszym),
• konto główne może mieć maksymalnie 20 kont pracowniczych (409 EMPLOYEE_LIMIT_REACHED),
• odpowiedź nigdy nie zawiera hasła.

Lista, edycja i usuwanie#

# Lista
curl -s https://prod.api.fakturnia.pl/external/v1/employees \
  -H "Authorization: Bearer $TOKEN"

# Edycja: zmiana uprawnień i dezaktywacja
curl -s -X PUT https://prod.api.fakturnia.pl/external/v1/employees/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "permissions": ["documents:read"], "isActive": false }'

# Usunięcie
curl -s -X DELETE https://prod.api.fakturnia.pl/external/v1/employees/{id} \
  -H "Authorization: Bearer $TOKEN"

W edycji wszystkie pola są opcjonalne: przesyłasz tylko to, co się zmienia. permissions zastępuje całą listę. Nowe hasło ustawisz polem password.

Dezaktywacja a usunięcie. isActive: false blokuje konto natychmiast (aktywne sesje pracownika są kończone), ale zachowuje email na koncie. Usunięcie kasuje konto trwale, a email wraca do puli i może zostać użyty ponownie. Zmiany uprawnień też działają natychmiast, bez ponownego logowania pracownika.

Jedno konto i jego aktywność#

GET /employees/{id} zwraca jedno konto (bez hasła), 404 dla cudzego. GET /employees/{id}/activity to dziennik pracownika: logowania z urządzeniem i adresem IP, zmiany konta, akcje na dokumentach i operacje magazynowe, od najnowszego, z kursorem before / nextBefore i filtrem scope. Kształt wpisów opisuje Historia i aktywność.

Dobre praktyki#

• Nadawaj minimalne uprawnienia i rozszerzaj w miarę potrzeb. Zacznij od documents:read; uprawnienia implikowane są dopinane automatycznie (np. documents:write dokłada documents:read), więc nie musisz budować pełnych zestawów samodzielnie.
• Pobieraj rejestr uprawnień przy każdej synchronizacji. GET /employees/permissions to słownik: nowe uprawnienia pojawiają się w nim bez zmiany wersji API, a nieznane klucze w zapisie są po cichu ignorowane. Hardkodowana lista w Twoim UI będzie kłamać.
• Offboarding rób dwuetapowo. Najpierw isActive: false (natychmiast kończy sesje, zachowuje email i historię), a dopiero po okresie przejściowym DELETE, jeśli konto ma zniknąć na stałe.
• Obsłuż 409 EMAIL_TAKEN jawnie. Email jest unikalny globalnie w całej Fakturni, nie tylko na Twoim koncie, więc kolizja może dotyczyć zupełnie obcego konta. Pokaż użytkownikowi komunikat zamiast ponawiać.
• Rotuj hasła przez PUT z polem password. Nie ma osobnego endpointu resetu; zmiana hasła nie kończy aktywnych sesji, w razie potrzeby połącz ją z chwilową dezaktywacją.