Dokumentacja API

Dokumentacja REST API

Interaktywna dokumentacja REST API aplikacji obejmująca moduł uwierzytelniania, zarządzanie działami organizacyjnymi, stanowiskami, profile użytkowników oraz portal pracowniczy.

Informacje podstawowe

Base URL https://api.matmartech.com
Wersja API v1
Format danych application/json
Autoryzacja Bearer Token w nagłówku Authorization

Zakres dokumentacji

Moduł Opis
Auth API Obsługa rejestracji, logowania, pobrania danych aktualnie zalogowanego użytkownika oraz wylogowania.
Departments API Zarządzanie działami organizacyjnymi, w tym strukturą hierarchiczną opartą o relację dział nadrzędny – dział podrzędny.
User Profiles API Zarządzanie profilami użytkowników oraz przypisywaniem użytkowników do wybranych działów i stanowisk.
Positions API Zarządzanie słownikiem stanowisk oraz przypisywanie pojedynczego stanowiska do konkretnego użytkownika.
Employee Portal API CRUD pracowników, miejsc pracy, grafików, wniosków, urlopów, czasu pracy, zwrotów kosztów, list płac i powiadomień.

Domyślne nagłówki

Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}

Nagłówek Authorization jest wymagany dla wszystkich endpointów chronionych, czyli modułów działów, profili oraz części endpointów uwierzytelniania, takich jak pobranie danych użytkownika i wylogowanie.

Dostępne grupy endpointów

Grupa Przykładowe endpointy Opis
Auth /api/v1/auth/register
/api/v1/auth/login
/api/v1/auth/me 		Rejestracja, logowanie, pobieranie danych zalogowanego użytkownika oraz zarządzanie tokenami dostępu.
Departments /api/v1/departments
/api/v1/departments/tree 		Tworzenie, odczyt, aktualizacja i soft delete działów oraz pobieranie ich struktury w formie drzewa.
User Profiles /api/v1/user-profiles
/api/v1/users/{user}/profile
/api/v1/users/{user}/department 		Tworzenie i aktualizacja profili użytkowników oraz zmiana działu użytkownika.
Positions /api/v1/positions
/api/v1/users/{user}/position 		CRUD stanowisk i zmiana przypisania użytkownika do stanowiska.
Employee Portal /api/v1/employees
/api/v1/requests
/api/v1/leave-balances
/api/v1/payrolls 		Pełne zasoby REST dla modułów pracowniczych. Każda grupa obsługuje listę, dodawanie, szczegóły, aktualizację i usuwanie.

Endpointy portalu pracowniczego

Zasób Endpoint Dokumentacja
Miejsca pracy /api/v1/workplaces Otwórz
Pracownicy /api/v1/employees Otwórz
Grafiki działów /api/v1/department-work-schedules Otwórz
Zastępstwa managerów /api/v1/manager-substitutions Otwórz
Typy wniosków /api/v1/request-types Otwórz
Pola typów wniosków /api/v1/request-type-fields Otwórz
Opcje pól wniosków /api/v1/request-field-options Otwórz
Wnioski pracownicze /api/v1/requests Otwórz
Wartości pól wniosków /api/v1/request-field-values Otwórz
Decyzje wniosków /api/v1/request-decisions Otwórz
Załączniki wniosków /api/v1/request-attachments Otwórz
Typy urlopów /api/v1/leave-types Otwórz
Salda urlopowe /api/v1/leave-balances Otwórz
Zdarzenia czasu pracy /api/v1/work-time-events Otwórz
Korekty czasu pracy /api/v1/work-time-adjustments Otwórz
Ręczne nieobecności /api/v1/manual-absences Otwórz
Zwroty kosztów /api/v1/reimbursements Otwórz
Listy płac /api/v1/payrolls Otwórz
Składniki wynagrodzeń /api/v1/payroll-earnings Otwórz
Potrącenia wynagrodzeń /api/v1/payroll-deductions Otwórz
Powiadomienia /api/v1/notifications Otwórz

Standard odpowiedzi

Przykład odpowiedzi sukcesu

{
  "success": true,
  "message": "Operacja zakończona sukcesem.",
  "data": {}
}

Przykład błędu walidacji

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}

Kody statusów HTTP

Kod Nazwa Znaczenie
200 OK Operacja zakończona poprawnie.
201 Created Zasób został utworzony, np. użytkownik, dział lub profil.
401 Unauthorized Brak autoryzacji lub nieprawidłowy token dostępu.
422 Unprocessable Entity Błąd walidacji danych wejściowych.
500 Internal Server Error Nieobsłużony błąd po stronie serwera.

Przepływ autoryzacji

  1. Użytkownik wykonuje rejestrację albo logowanie.
  2. API zwraca token dostępu.
  3. Klient zapisuje token po stronie aplikacji.
  4. Każdy kolejny request do chronionego endpointu wysyła nagłówek Authorization: Bearer {token}.
  5. Przy wylogowaniu bieżący token albo wszystkie tokeny są usuwane.

Założenia modułów biznesowych

  • Działy mogą być organizowane hierarchicznie poprzez pole parent_id.
  • Usuwanie działów realizowane jest jako soft delete.
  • Stanowiska przechowywane są jako osobny słownik i również obsługują soft delete.
  • Profil użytkownika przechowuje rozszerzone dane użytkownika niezależnie od tabeli users.
  • Przypisanie użytkownika do działu odbywa się przez pole department_id w profilu użytkownika.
  • Użytkownik może mieć przypisane maksymalnie jedno stanowisko przez pole position_id.
  • Zasoby portalu pracowniczego są chronione tokenem Sanctum i dostępne pod prefiksem /api/v1.
  • Standardowe listy obsługują opcjonalny parametr per_page oraz filtry opisane przy konkretnym zasobie.