Działy konta

Tworzenie, aktualizacja, usuwanie i pobieranie działów konta przez API.

Autoryzacja: Authorization: Bearer TOKEN Content-Type: application/json; charset=utf-8

API Endpoints

Metoda	Ścieżka	Opis
GET	/account/departments.json	Lista działów
GET	/account/departments/:id.json	Pojedynczy dział
POST	/account/departments.json	Utworzenie działu
PATCH	/account/departments/:id.json	Aktualizacja działu
PATCH	/account/departments/:id/set_as_main.json	Ustawienie jako dział główny
DELETE	/account/departments/:id.json	Usunięcie działu

Pola działu

Pole	Typ	Wymagane	Opis
name	string	tak	Nazwa działu (unikalna w ramach konta)
shortcut	string	nie	Krótki kod działu (np. “SPR” dla Sprzedaży)
description	string	nie	Opis działu
phone	string	nie	Numer kontaktowy działu (trafia do stopki maila)
email	string	nie	Adres e-mail działu (trafia do stopki maila)
user_setting_ids	array	nie	ID użytkowników przypisanych do działu
mailbox_ids	array	nie	ID skrzynek pocztowych przypisanych do działu
company_name	string	nie	Nazwa firmy dla działu (dla stopki maila / faktur)
company_tax_no	string	nie	NIP
company_street	string	nie	Ulica
company_street_number	string	nie	Numer budynku
company_post_code	string	nie	Kod pocztowy
company_city	string	nie	Miasto
company_country	string	nie	Kraj
company_email	string	nie	Email firmowy
company_phone	string	nie	Telefon firmowy
company_website	string	nie	Strona WWW
company_bank	string	nie	Nazwa banku
company_bank_account	string	nie	Numer konta bankowego
company_logo	string	nie	Adres URL logo (używany, gdy nie wgrano pliku)
logo	plik	nie	Logo wgrane plikiem - tylko multipart/form-data, nie JSON. Ma pierwszeństwo nad company_logo
logo_remove	“1”	nie	Usuwa wgrane logo (multipart, jak wyżej)

Odpowiedź zawiera dodatkowo logo_url - trwały adres wgranego logo albo null, gdy dział nie ma logo z pliku. Plik idzie do maila w rozmiarze, w jakim go wgrano - rozmiarem obrazka steruje atrybut width przy <img> w stopce.

Tworzenie działu

POST /account/departments.json
Authorization: Bearer TOKEN
Content-Type: application/json; charset=utf-8

{
  "department": {
    "name": "Sprzedaż",
    "shortcut": "SPR",
    "description": "Dział sprzedaży B2B",
    "phone": "+48 22 123 45 67",
    "email": "[email protected]",
    "user_setting_ids": [1, 2, 3]
  }
}

Aktualizacja działu

PATCH /account/departments/:id.json

Wysyłasz tylko zmieniane pola.

{
  "department": {
    "name": "Dział sprzedaży",
    "mailbox_ids": [5, 6]
  }
}

Ustawienie jako dział główny

PATCH /account/departments/:id/set_as_main.json

Bez body - akcja przełącza main_department_id na koncie.

Błędy (422)

{"name": ["nie może być puste"]}

Wskazówki

• Nazwa unikalna - walidacja sprawdza unikalność w ramach account_id
• Pierwszy utworzony dział automatycznie staje się main_department konta
• Drugi dział automatycznie włącza tryb account.departments.mode = "restricted" (chyba że admin ustawił go wcześniej ręcznie)
• Usunięcie działu głównego - kolejny dział (najstarszy) zostaje główny
• Logo - plik wgrywasz wyłącznie żądaniem multipart/form-data (pole department[logo]), nie w JSON. Logo trafia do stopek maili, mailingów i PDF-ów faktur, więc jego adres jest trwały - nie wygasa

Dostęp do rekordów BEZ działu (flaga użytkownika)

Przypisanie do działów to jedno, a dostęp do rekordów z pustym działem (department_id IS NULL) - drugie. Steruje nim flaga without_department na użytkowniku (domyślnie true):

PATCH /account/user_settings/:id.json
{ "user_setting": { "without_department": false } }

Flaga działa tylko przy włączonym ograniczeniu widoczności po działach. Kto ją ma, widać na liście użytkowników (Ustawienia konta → Użytkownicy): w kolumnie „Działy” przed nazwami działów stoi kursywą znacznik „bez działu”. Na karcie użytkownika ta sama informacja jest ikoną z opisem.

Powiązane

• common_api - wspólne zasady API