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": "sprzedaz@firma.pl",
    "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

Źródła