Serwer MCP
Połącz narzędzia AI z Flowtly poprzez Model Context Protocol na mcp.flowtly.eu.
Ta dokumentacja jest generowana ze schematu API. Opisy pól oraz wszelkie teksty, które nie zostały jeszcze przetłumaczone, są wyświetlane po angielsku.
Połącz
claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp
Na tej stronie
Umowy
Narzędzia
| Narzędzie | Opis |
|---|---|
| agreements_get | Pobierz jedną umowę o pracę po id — type, variant, okres dateFrom/dateTo, hoursPerWeek oraz wyliczone `calculable`, `active` i `status`. agreements_list dostarcza id. Wymaga ROLE_AGREEMENTS_MANAGER lub ROLE_MEETING_MANAGER. Tylko do odczytu. |
| agreements_list | Lista umów o pracę — filtruj po employee (IRI), isActive, type lub variant. TO jest sposób na odpowiedź na pytanie "dlaczego people_list pokazuje tę osobę jako nieaktywną": każdy wiersz zawiera `calculable` i `active`, a osoba jest aktywna dokładnie wtedy, gdy posiada umowę, w której oba te pola są prawdziwe. To też miejsce, w którym można sprawdzić kody `type` umów rzeczywiście używane w tej organizacji przed wywołaniem agreements_create, ponieważ organizacja może dodawać własne. Wymaga ROLE_AGREEMENTS_MANAGER lub ROLE_MEETING_MANAGER. Tylko do odczytu. |
| agreements_create | Utwórz umowę o pracę dla osoby. TO JEST KROK, KTÓRY CZYNI KOGOŚ AKTYWNYM: people_create tworzy jedynie rekord, a osoba bez umowy będzie zgłaszać isActive false na zawsze — import masowy ląduje więc w 100% nieaktywny, dopóki nie zostanie to uruchomione dla każdej osoby z osobna. DWIE RZECZY MUSZĄ BYĆ PRAWDZIWE JEDNOCZEŚNIE, inaczej osoba pozostanie nieaktywna bez żadnego błędu: `type` musi być KALKULOWALNY (wbudowane "agreement", "annex", "termination" są; "list-of-intent" i "work-experience" nie są), a okres dateFrom/dateTo musi obejmować dzisiaj (przekaż dateTo jako null dla trwającej umowy, zamiast odległej daty w przyszłości). `employee` to IRI — /people/<id> z people_list. Typy są rozszerzalne przez organizację, więc uruchom agreements_list na kimś już aktywnym, by zobaczyć kody rzeczywiście używane w tej organizacji. Wymaga ROLE_AGREEMENTS_MANAGER. Zapis. |
| agreements_update | Zmień istniejącą umowę o pracę — to sposób, w jaki umowa jest ZAKOŃCZONA, ponieważ backend nie udostępnia usuwania dla tego zasobu: ustaw `dateTo` na ostatni dzień, który obejmuje, a osoba przestaje być aktywna od tego momentu, przy zachowanym rekordzie i jego historii. To właściwe posunięcie dla wiersza powiązanego z płacami; nie ma sposobu, by sprawić, że zniknie, i nie powinno go być. To też sposób na poprawienie błędnego `type`, `variant` lub `positionName` w miejscu, zamiast dokładania drugiej umowy tej samej osobie — DWIE umowy się nie znoszą, ta kalkulowalna utrzymuje aktywność, więc "dodaj poprawną obok" po cichu pozostawia błędną w mocy. `amount`, `amountType` i `billingType` są akceptowane, ale API nigdy ich nie zwraca, więc nie da się odczytać tego, co zostało zapisane. Wymaga ROLE_AGREEMENTS_MANAGER. Zapis. |
Typy umów
Narzędzia
| Narzędzie | Opis |
|---|---|
| agreementTypes_get | Pobierz jeden typ umowy po id — jego name lub translationKey, `calculable`, `isActive`, `position` i `builtIn`. id JEST kodem, więc odczytujesz typ za pomocą tego samego ciągu, jaki umowa przechowuje w `type`. Użyj tego, by potwierdzić, że typ utrwalił się po agreementTypes_create, i sprawdzić `calculable` przed przypisaniem go komukolwiek. Wymaga ROLE_USER. Tylko do odczytu. |
| agreementTypes_list | Lista typów umów, jakie TA organizacja może przypisać do umowy — wartości stojące za `Ludzie > <person> > Umowy > Edytuj umowę`. Odczytaj to przed agreements_create lub agreements_import, ponieważ lista jest per-tenant: fabrycznie dostępnych jest pięć wbudowanych typów ("agreement", "annex", "termination", "list-of-intent", "work-experience"), a organizacja może dodawać własne, więc `type` prawidłowy w jednej organizacji zwróci 422 w innej. ID JEST KODEM — `id` w każdym wierszu to dokładnie ten ciąg, którego `agreements_create` oczekuje w `type`, a nie numeryczny klucz do wyszukania. `calculable` to pole, które decyduje, czy posiadanie tego typu czyni kogoś AKTYWNYM i wlicza go do puli zasobów (resourcing bench), naliczania urlopu i bazy kosztowej; typ niekalkulowalny pozostawia osobę nieaktywną bez żadnego błędu — co jest zamierzone dla typu takiego jak "list-of-intent", a cichym błędem, jeśli wybrano go przez pomyłkę. Wiersze `builtIn` mają translationKey i puste (null) name; wiersze niestandardowe mają name renderowane dosłownie i puste (null) translationKey. Wymaga ROLE_USER. Tylko do odczytu. |
| agreementTypes_create | Dodaj typ umowy do listy TEJ organizacji, aby umowa mogła zostać zapisana wobec czegoś, czego nie obejmuje pięć wbudowanych typów — "Umowa zlecenie", "Kontrakt B2B", "Użytkownik funkcyjny". To jest konfiguracja, nie zmiana kodu: lista jest tabelą per-tenant, a typ niestandardowy nie wymaga wpisu tłumaczenia, ponieważ jego `name` renderuje się dosłownie we wszystkich siedmiu lokalizacjach. NIE WYSYŁAJ `id`: kod jest tworzony po stronie serwera ze slugowanej nazwy ze zwiniętymi znakami diakrytycznymi ("Użytkownik funkcyjny" staje się "uzytkownik-funkcyjny"), a przekazanie id jest odrzucane z kodem 422 "Update is not allowed for this operation". Wyślij name i odczytaj przypisany kod z odpowiedzi. `calculable` DOMYŚLNIE JEST FALSE I DZIEJE SIĘ TO CICHO: decyduje o tym, kto liczy się jako zatrudniony — pula zasobów (resourcing bench), naliczanie urlopu, baza kosztowa i budżetowa — więc typ przeznaczony dla osób, które NIE powinny naliczać urlopu ani zajmować etatu (FTE), jest poprawny przy wartości false, a typ przeznaczony dla rzeczywistego zatrudnienia MUSI mieć ją ustawioną na true, inaczej każdy na tym typie będzie zgłaszany jako nieaktywny bez żadnego błędu. Nic nie powie ci, którą wartość faktycznie ustawiono. `position` porządkuje listę rozwijaną; `isActive` domyślnie jest true. Celowo nie ma aktualizacji ani usuwania przez MCP — `agreement.type` przechowuje id tego wiersza jako goły ciąg znaków bez klucza obcego, więc zmiana nazwy lub usunięcie typu osieroca każdą umowę, która na niego wskazuje. Wymaga ROLE_AGREEMENTS_MANAGER. Zapis. |
Alokacje
Narzędzia
| Narzędzie | Opis |
|---|---|
| allocations_get | Jedna alokacja po id — rezerwacja jednej osoby na projekcie, wraz z datami i procentem. allocations_list znajduje id; ten endpoint odczytuje pełny rekord. Alokacja bez pracownika to rola OTWARTA (niezaspokojone zapotrzebowanie), a nie rezerwacja. Wymaga modułu resourcing. Tylko do odczytu. |
| allocations_list | Listuje alokacje zasobowe — przypisania stanowiska na projekcie do pracownika (lub jeszcze do nikogo, rola otwarta) w danym zakresie dat. Brak filtrów; stronicowanie kursorem. Każdy element zawiera już rozwiązane employeeId/employeeName oraz projectId/projectName (null w employeeId oznacza rolę otwartą); positionId jest surowe — jego nazwę rozwiązuje się przez positions_list. source rozróżnia wiersze zaimportowane z arkusza od utworzonych bezpośrednio w Flowtly. Użyj tego, aby uzgodnić import arkusza zasobowego: odczytaj, co faktycznie trafiło do systemu, i porównaj z tym, co zostało przesłane. |
Rezerwacje zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| assetBookings_get | Pobierz jedną rezerwację zasobu po id — zasób, jej posiadacza, daty oraz to, czy została anulowana. Tylko do odczytu. |
| assetBookings_list | Lista rezerwacji zasobów — kto lub co aktualnie posiada dany zasób; to właśnie to przypisanie pokazuje ekran Assets i jedyne miejsce, w którym faktycznie istnieje powiązanie zasobu z osobą. Każdy wiersz zawiera zasób, posiadacza (`relationName` employee | project plus `relationId`), daty start/end oraz — po zwolnieniu — `cancelReason` i `cancelledAt`. Filtruj po `property`, by zobaczyć historię jednego zasobu, lub po `employee`, by zobaczyć wszystko, co posiada dana osoba — to drugie warto uruchomić przed odejściem pracownika. Zwróć uwagę, że `employee` jest tu NUMERYCZNYM id, a nie IRI /people, którego oczekuje assetBookings_create. Dodaj `exists.cancelledAt: false`, by zobaczyć tylko to, co wciąż jest zajęte; bez tego lista zawiera też zwolnione rezerwacje. Tylko do odczytu. |
| assetBookings_create | Przypisz zasób do osoby lub projektu. `property` to IRI zasobu (/assets/{id}) i jest wymagane. Podaj posiadacza JEDNYM z trzech sposobów: `relation` z pojedynczym IRI (/people/{id} dla osoby, /projects/{id} dla projektu), lub `relationName` (employee | project) plus `relationId`, lub bezpośrednio polem IRI `employee` / `project`. Musi rozwiązać się dokładnie jeden posiadacz — brak obu jest odrzucany z komunikatem "Employee or Project must be set.", a podanie obu z "Employee and Project cannot be set at the same time." DWIE RZECZY, KTÓRYCH NIE MA W SCHEMACIE, A KTÓRE DADZĄ CI 422: zasób musi być już rezerwowalny (`bookingAllowed: true` — ustaw to przez assets_update), reguła biznesowa egzekwowana wobec KAŻDEGO wywołującego, łącznie z managerem, odrzucana komunikatem "This asset is not reservable."; oraz własne `bookingType` zasobu (minutes | days | single-days | permanently), które nadaje sens `duration` / `endDate` — miejsce przypisane jednej osobie na czas nieokreślony to `permanently` ze `startDate` i bez końca. Równoczesne rezerwacje na jednym zasobie są serializowane po stronie serwera, więc nakładanie się jest odrzucane, a nie prowadzi do podwójnej rezerwacji. Wymaga ROLE_PROPERTY_BOOKINGS_MANAGER, by rezerwować w imieniu kogoś innego. Zapis. |
| assetBookings_update | Zaktualizuj istniejącą rezerwację zasobu — jej daty, duration, kwotę/walutę rozliczeniową lub udział w zużyciu licznikowym. `relationName` i `relationId` są wymagane przez payload, więc wyślij posiadacza, którego rezerwacja już ma, chyba że celowo ją przenosisz. Aby zakończyć przypisanie, użyj assetBookings_cancel, a nie endDate w przeszłości. Wymaga ROLE_PROPERTY_BOOKINGS_MANAGER. Zapis. |
| assetBookings_cancel | Zwolnij zasób — sposób, w jaki kończy się przypisanie, i najbliższy odpowiednik usuwania, jaki ma ten zasób (nie ma operacji usuwania). Przyjmuje id rezerwacji i `cancelReason` o długości 3–255 znaków; rezerwacja jest zachowana i oznaczona `cancelledAt`, dzięki czemu historia przetrwa, a zasób staje się wolny dla następnego posiadacza. To wywołanie, które trzeba wykonać, gdy pracownik odchodzi: assetBookings_list przefiltrowane po `employee` znajduje to, co posiada, a to narzędzie zwalnia każdą pozycję. Wymaga ROLE_PROPERTY_BOOKINGS_MANAGER. Zapis. |
Odczyty liczników zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| assetMeterReadings_get | Pobierz jeden odczyt licznika po id — jego meter, date i value. Tylko do odczytu. |
| assetMeterReadings_list | Lista odczytów liczników — datowane wartości zarejestrowane dla licznika zasobu, surowe dane, z których korzysta podział rozliczenia za media. Każdy wiersz zawiera meter, date i value. Użyj tego, by odczytać historię licznika: wartość, która nigdy się nie zmienia między okresami (licznik zablokowany lub współdzielony), rozlicza się na zero, a licznik bez ostatnich wpisów to taki, którego nikt nie odczytuje. Tylko do odczytu. |
Liczniki zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| assetMeters_get | Pobierz jeden licznik zasobu po id — zasób, na którym się znajduje, rodzaj medium, jednostkę oraz identyfikator zewnętrzny/QR, wraz z jego odczytami. Tylko do odczytu. |
| assetMeters_list | Lista liczników zasobów organizacji — liczniki mediów przypisane do zasobów (prąd, woda, gaz, ciepło). Każdy zawiera zasób, na którym się znajduje, rodzaj medium i jednostkę oraz swoje odczyty. Filtruj po `property` (zasobie, do którego należy) i `utilityType`. Użyj tego, by ustalić id licznika wymagane przez odczyty oraz wychwycić liczniki, które pokazują zero, utknęły na jednej wartości lub są licznikiem współdzielonym/zbiorczym. Tylko do odczytu. |
| assetMeters_update | Zaktualizuj licznik zasobu — jego label, rodzaj medium, jednostkę lub stan aktywności. Użyj tego, by wycofać licznik z pomiaru (np. medium rozliczane teraz bezpośrednio z faktury) bez usuwania historii jego odczytów. Wymaga ROLE_PROPERTIES_MANAGER. Zapis. |
Zasoby
Narzędzia
| Narzędzie | Opis |
|---|---|
| assets_get | Pobierz jeden zasób po id — name, status, kategorię (attributeSet), parent, assetCode, numer seryjny, daty zakupu i gwarancji, lokalizację oraz ustawienia rezerwacji. Tylko do odczytu. |
| assets_list | Lista zasobów organizacji — rejestr rzeczy fizycznych, które posiada lub sprzedaje, od laptopów i biurek po mieszkania, miejsca parkingowe i komórki lokatorskie. Filtruj po status (in-stock | damaged | sold), attributeSet (kategorii, wg której grupuje lista Assets), bookingAllowed lub częściowym name albo serialNumber; sortuj po name, status, serialNumber, boughtAt lub warrantyTo. BEZ PAGINACJI — cały zbiór wraca w jednej odpowiedzi, więc duży rejestr to jeden duży payload, a nie pierwsza strona. Użyj tego, by ustalić id zasobu wymagane przez rezerwacje zasobów i dokumenty zasobów. Tylko do odczytu. |
| assets_import | Wczytaj WIELE zasobów w jednym wywołaniu, kluczowanych po `assetCode` — narzędzie do przenoszenia inwentarza z innego systemu, gdzie assets_create wymagałoby jednego zapytania na rekord. Wiersze są uzgadniane wobec organizacji: nieznany assetCode tworzy, znany aktualizuje w miejscu, identyczny wiersz jest pomijany, więc ponowne uruchomienie niczego nie zmienia, a przerwane w połowie uruchomienie da się bezpiecznie powtórzyć. `parentAssetCode` zagnieżdża wiersz pod innym PO JEGO KODZIE, rozwiązywanym wobec organizacji oraz wobec wcześniejszych wierszy tej samej partii; rodzic, który się nie rozwiąże, powoduje odrzucenie tego wiersza, a nie ciche osierocenie. TRZY POLA CZYNIĄ REKORD CZYTELNYM, a nie tylko goła nazwa: `attributeSetName` to kategoria, którą UI pokazuje jako Typ zasobu i wg której grupuje lista, `locationName` to miejsce, w którym rzecz fizycznie się znajduje, a `attributes` to mapa {name: value} dla powierzchni, piętra, ceny i wszystkiego innego, co niesie źródło. Wszystkie trzy są rozwiązywane PO NAZWIE — kategoria, lokalizacja, definicje atrybutów i ich powiązania są dla ciebie odnajdywane lub tworzone, więc wywołujący nigdy nie obsługuje żadnego z tych IRI, a nazwy są dopasowywane bez rozróżniania wielkości liter, więc "Mieszkanie" i "mieszkanie " nie mogą podzielić listy na dwie. `attributes` potrzebuje kategorii, do której się przypisze, a wartość, która parsuje się jako liczba, tworzy atrybut liczbowy — rozstrzygane przy pierwszym pojawieniu się danej nazwy. Atrybut, którego nie udało się zapisać, NIE powoduje niepowodzenia swojego zasobu. PRZEKAŻ NAJPIERW dryRun:true przy wczytywaniu prawdziwego inwentarza — raportuje would-create / would-update / would-skip dla każdego wiersza i nie tworzy absolutnie niczego, łącznie z kategoriami i lokalizacjami. Maks. 1000 wierszy. Wymaga ROLE_PROPERTIES_MANAGER. Zapis. |
| assets_create | Utwórz zasób (wymagane name + status + bookingType; status = in-stock | damaged | sold, bookingType = minutes | days | single-days | permanently). bookingType jest wymagane nawet wtedy, gdy zasób nigdy nie jest rezerwowany — przekaż "permanently" dla czegoś, co nie jest wypożyczane, i pozostaw bookingAllowed jako false. Dwa pola niosą strukturę: `parent` zagnieżdża zasób pod innym (lokal pod budynkiem, monitor pod biurkiem), a `attributeSet` ustawia kategorię, wg której grupuje lista Assets — tam też znajdują się atrybuty niestandardowe, takie jak powierzchnia czy piętro. `assetCode` to UNIKALNY uchwyt międzysystemowy — użyj go, by przechowywać id, jakie ten zasób ma w systemie źródłowym, z którego został zaimportowany, tak by ponowny import aktualizował, a nie duplikował. Wymaga ROLE_PROPERTIES_MANAGER. Zapis. |
| assets_update | Zaktualizuj zasób po id — name, status, kategorię, parent, assetCode, numer seryjny, daty, lokalizację lub ustawienia rezerwacji. Tak właśnie zasób przechodzi ze stanu in-stock na sold. Zwróć uwagę, że słownik status to in-stock | damaged | sold i NIE MA stanu zarezerwowany, więc blokadę trzeba modelować w inny sposób. Wymaga ROLE_PROPERTIES_MANAGER. Zapis. |
Wartości atrybutów encji
Narzędzia
| Narzędzie | Opis |
|---|---|
| attributeEntityValues_list | Lista WARTOŚCI atrybutów — co konkretny zasób, projekt, budżet lub klient faktycznie ma ustawione dla powiązanego atrybutu. Każdy wiersz zawiera atrybut, wartość oraz `relationId` wskazujący encję, do której należy. Tylko do odczytu. |
| attributeEntityValues_create | Ustaw wartość atrybutu dla jednej encji (wymagane attribute + value). `relation` JEST IRI — "/properties/7", nie słowem "property": backend je rozwiązuje i wyprowadza nazwę relacji z klasy zasobu, więc przekazanie gołej nazwy rzuca błąd. (`relationId` przyjmuje zwykłe id i wciąż działa, ale jest przestarzałe na rzecz IRI.) Atrybut musi być już POWIĄZANY z kategorią tej encji, w przeciwnym razie wartość zostanie zapisana, ale nigdy nie będzie wyświetlana. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
| attributeEntityValues_update | Zmień jedną wartość atrybutu w miejscu, po jej id. Użyj tego zamiast tworzyć drugą wartość dla tej samej pary (entity, attribute) — nic nie wymusza unikalności, więc duplikat zostanie zaakceptowany, a UI pokaże tylko jedną z nich. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
| attributeEntityValues_delete | Usuń wartość atrybutu z encji. Definicja i powiązanie przetrwają; usuwana jest tylko wartość dla tej encji. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
Atrybuty
Narzędzia
| Narzędzie | Opis |
|---|---|
| attributes_get | Pobierz jedną definicję atrybutu po id — name, type, informację, czy jest required lub multiple, wartość domyślną i wzorzec formatu. Tylko do odczytu. |
| attributes_list | Lista DEFINICJI atrybutów — nazwane pola (powierzchnia, piętro, cena), które kategorie wiążą, a zasoby mają dla nich wartości. Każda ma type: number | string | date | state | period. Tylko do odczytu. |
| attributes_create | Utwórz definicję atrybutu (wymagane name + type; type to number | string | date | state | period). TYPE TO KLUCZOWA DECYZJA: jest współdzielony przez każdą encję niosącą ten atrybut, więc pole utworzone jako `string` nie może później sumować się ani sortować jak liczba bez przepisania każdej istniejącej wartości. Zdecyduj o nim na podstawie wartości, które faktycznie masz, a nie pierwszej, którą zobaczysz. Sama definicja nic nie robi — powiąż ją z kategorią za pomocą attributeSetAttributes_create, inaczej nigdzie się nie pojawi. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
| attributes_update | Zaktualizuj definicję atrybutu — name, type, required, multiple, default lub format. Zmiana `type` na definicji, która ma już wartości, jest ryzykowna: istniejące wartości nie są konwertowane. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
Atrybuty zestawów atrybutów
Narzędzia
| Narzędzie | Opis |
|---|---|
| attributeSetAttributes_list | Lista powiązań między kategoriami a definicjami atrybutów — które pola pojawiają się przy której kategorii. Tylko do odczytu. |
| attributeSetAttributes_create | Powiąż definicję atrybutu z kategorią (attributeSet + attribute, oba jako IRI). TO WŁAŚNIE SPRAWIA, ŻE ATRYBUT SIĘ POJAWIA: bez tego powiązania wartość może zostać poprawnie zapisana dla encji, ale nigdy nie pokaże się w UI — awaria bez żadnego objawu. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
| attributeSetAttributes_delete | Odepnij atrybut od kategorii. Definicja i wszelkie wartości przetrwają; po prostu przestają być pokazywane dla tej kategorii, co sprawia wrażenie utraty danych, choć nią nie jest. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
Zestawy atrybutów
Narzędzia
| Narzędzie | Opis |
|---|---|
| attributeSets_get | Pobierz jeden zestaw atrybutów po id — jego name, relationName, icon oraz powiązane z nim atrybuty. Tylko do odczytu. |
| attributeSets_list | Lista zestawów atrybutów organizacji — KATEGORIE, pod którymi zarchiwizowany jest zasób, projekt, budżet lub klient. Filtruj po relationName: "property" dla kategorii zasobów (to, co w UI nazywa się Typ zasobu i wg czego grupuje lista Assets), a także "project", "budget" i "client". Sięgnij po to przed utworzeniem nowej kategorii: kategoria zduplikowana przez błąd pisowni lub wielkość liter po cichu dzieli listę, którą grupuje, a nic w UI tego nie wyjaśnia. Tylko do odczytu. |
| attributeSets_create | Utwórz kategorię (wymagane name + relationName; relationName to jedno z property | project | budget | client, a dla kategorii zasobu jest to zwykły ciąg "property" — NIE IRI). Opcjonalna icon z ustalonej listy (room, parking, building, office, local, desk, monitor i tak dalej), którą UI pokazuje obok kategorii. NAJPIERW LISTA: nazwy nie są unikalne, więc drugie "Mieszkanie" zostanie zaakceptowane i po cichu podzieli listę Assets na dwie. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
| attributeSets_update | Zmień nazwę kategorii, jej icon lub przenieś ją do innego relationName. Tak właśnie naprawia się kategorię utworzoną z literówką, zamiast ją duplikować. Wymaga ROLE_ATTRIBUTES_MANAGER. Zapis. |
Konta bankowe
Narzędzia
| Narzędzie | Opis |
|---|---|
| bankAccounts_get | Pobierz jedno konto bankowe po id — nazwa, waluta, bank oraz format, w jakim importowane są jego wyciągi. |
| bankAccounts_list | Listuje konta bankowe organizacji. Filtruj po banku lub ustaw hidden, aby uwzględnić zarchiwizowane. Użyj tego, aby rozwiązać id bankAccount, po którym filtruje transactions_list. |
| bankAccounts_create | Utwórz konto bankowe (wymagane type, name, currency, defaultImportFormat). Zapis. |
| bankAccounts_update | Zaktualizuj konto bankowe po id. Zapis. |
Banki
Narzędzia
| Narzędzie | Opis |
|---|---|
| banks_get | Pobierz jeden bank po id — instytucję, nie rachunek w niej prowadzony. Użyj bankAccounts_get dla rachunku. |
| banks_list | Lista banków, w których organizacja prowadzi rachunki. Banki ukryte są DOMYŚLNIE UWZGLĘDNIONE — przekaż hidden=false, by uzyskać widok jak w selektorach, lub hidden=true, by znaleźć te wycofane. Użyj tego, by ustalić id banku, po którym filtruje bankAccounts_list i którego potrzebuje bankAccounts_create. |
| banks_create | Utwórz bank — instytucję, do której należy rachunek bankowy, a nie sam rachunek (to bankAccounts_create). Zapis. |
| banks_update | Zaktualizuj bank po id. To też sposób, w jaki bank jest ukrywany i odkrywany: ustaw `hidden` na true, by wycofać go z selektorów bez usuwania, false, by go przywrócić. Nie ma osobnego narzędzia do archiwizacji, ponieważ API nie ma akcji archiwizacji dla banku — ta flaga jest tym mechanizmem. Zapis. |
Budżety
Narzędzia
| Narzędzie | Opis |
|---|---|
| budgets_employeePnl | Rachunek zysków i strat (P&L) per pracownik dla budżetu — ile zarobił czas danej osoby w zestawieniu z tym, ile kosztowała. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
| budgets_get | Pobierz jeden budżet po id — jego okres, zakres i ustawienia. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
| budgets_list | Lista budżetów organizacji — okresy, wobec których planowany i porównywany jest przychód i koszt. Użyj tego, by ustalić id budżetu wymagane przez każde narzędzie pnl. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
| budgets_pnlByTags | Rachunek zysków i strat (P&L) dla budżetu, w podziale WEDŁUG TAGA — income, costsByTag, costsByProject i netByTag dla okresów budżetu. To właśnie oś tagów sprawia, że jest to czytelne dla biznesu, którego koszty nie dzielą się naturalnie per projekt: otaguj dokumenty, a podział pojawi się sam. Zawiera displayPricePerSqm, gdy organizacja włączyła cenę za m² i nazwała atrybut powierzchni — to właśnie zamienia to w widok na metr kwadratowy dla dewelopera. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
| budgets_pnlByTagsDrilldown | Dokumenty stojące za jedną komórką budgets_pnlByTags. Sięgnij po to, gdy suma dla taga wygląda podejrzanie — wskazuje transakcje składające się na tę liczbę zamiast zostawiać cię z domysłami. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
Klienci
Narzędzia
| Narzędzie | Opis |
|---|---|
| clients_get | Pobierz jednego klienta po id — nazwa, kraj, waluta, identyfikator podatkowy i status. |
| clients_list | Listuje klientów (klientów organizacji). Filtruj po status lub po externalPaymentCustomerId, aby znaleźć klienta stojącego za id dostawcy płatności. Użyj tego, aby rozwiązać id client, po którym filtrują invoices_list, deals_list, projects_list i contracts_list. |
| clients_import | Wczytaj WIELU klientów w jednym wywołaniu, kluczowanych po `externalRef` — narzędzie do przenoszenia listy klientów lub kupujących z innego systemu, gdzie clients_create wymagałoby jednego zapytania na osobę. Wiersze są uzgadniane wobec organizacji: nieznany externalRef tworzy, znany aktualizuje w miejscu, identyczny wiersz jest pomijany, więc ponowne uruchomienie niczego nie zmienia. Referencja jest przechowywana jako `externalPaymentCustomerId`, jedyna kolumna referencji zewnętrznej, jaką ma klient, a `clients_list` po niej filtruje. NIE dopasowuj klientów po nazwisku — lista kupujących jest pełna wspólnych nazwisk i zakupów wspólnych. Każdy wynik zawiera `counterpartyId`, którego potrzebują contracts_import i contracts_create. Dwie pułapki, których schemat nie wyraża: `tin` jest ODRZUCANY bez `tinCountry`, a wiersz kontaktu wymaga e-maila, więc sam numer telefonu nie wystarczy do jego utworzenia. PRZEKAŻ NAJPIERW dryRun:true przy prawdziwym wczytywaniu onboardingowym. Maksymalnie 500 wierszy. Wymaga ROLE_CLIENTS_MANAGER. Zapis. |
| clients_create | Utwórz nowy rekord klienta (wymagane name, country, currency, status, tinType). Zapis. |
| clients_update | Zaktualizuj rekord klienta po id. Zapis. |
Klucze konfiguracji
Narzędzia
| Narzędzie | Opis |
|---|---|
| configKeys_catalog | Listuje każdy klucz konfiguracji organizacji rozpoznawany przez backend, wraz z jego typem i dozwolonymi wartościami. To katalog tego, co jest konfigurowalne — odczytaj go przed configs_get lub configs_update, zamiast zgadywać nazwę klucza. Uprawnienia są egzekwowane przez backend per klucz, więc obecność klucza tutaj nie gwarantuje, że połączony użytkownik może go zapisać. |
Konfiguracje
Narzędzia
| Narzędzie | Opis |
|---|---|
| configs_get | Odczytuje jedną wartość konfiguracji organizacji po id, gdzie id jest kluczem z configKeys_catalog (np. organization-logo-url, organization-icon-url). |
| configs_update | Zaktualizuj wartość konfiguracji organizacji po id (wymagane type + name; uprawnienia są egzekwowane przez backend dla każdego klucza konfiguracji osobno). Zapis. |
Umowy
Narzędzia
| Narzędzie | Opis |
|---|---|
| contracts_get | Pobierz jedną umowę po id — strony, kierunek, wartość, warunki cykliczności i daty. |
| contracts_list | Lista umów (kontraktów). Filtruj po direction — przechowywane wartości to "out" (sprzedajemy / wystawiamy) i "in" (kupujemy / otrzymujemy), a także "unknown" — realny, filtrowalny stan, a nie błąd. Kontrakt utworzony przez wgranie dokumentu zaczyna jako "unknown" i pozostaje tak, dopóki ekstrakcja lub człowiek go nie rozstrzygnie, więc pomiń filtr, by uzyskać wszystkie trzy: zapytania o "in" i "out" osobno NIE sumują się do całego zbioru. NIE "outgoing"/"incoming": te nie dopasowują niczego i wracają jako pusta lista zamiast błędu. Filtruje też po counterparty, project, cyclic, name lub tags. Użyj tego, by ustalić id kontraktu odczytywane przez contracts_paymentScheduleLines i to, z którym deals_win może powiązać wygraną transakcję. |
| contracts_paymentScheduleLines | Lista harmonogramu płatności kontraktu — rat, w jakich ma zostać zafakturowany lub opłacony. Przekaż contractId z contracts_list. To PLAN, nie rzeczywistość: porównaj z transactions_list, by zobaczyć, co naprawdę zostało zapłacone. Kwota każdej pozycji jest w JEDNOSTKACH POMOCNICZYCH — w groszach, nie w złotych: "530000" to 5 300,00, więc podziel przez 100, zanim podasz komuś liczbę. |
| contracts_import | Wczytaj WIELE kontraktów w jednym wywołaniu, kluczowanych po `name` — numerze umowy. W przeciwieństwie do klienta czy zasobu, kontrakt NIE MA kolumny referencji zewnętrznej, więc name JEST kluczem idempotencji; partia zawierająca tę samą name dwukrotnie jest ODRZUCANA W CAŁOŚCI, zamiast dwukrotnie zaktualizować jeden kontrakt, ponieważ zduplikowany numer oznacza, że źródło jest błędne. `counterpartyExternalRef` rozwiązuje kupującego przez tę samą referencję, jaką otrzymał clients_import, więc te dwa narzędzia się łączą: zaimportuj klientów, potem kontrakty, nigdy nie obsługując numerycznego id kontrahenta — referencja niedopasowana do żadnego klienta powoduje odrzucenie tego wiersza, a nie utworzenie kontraktu bez strony. `direction` to "out" (sprzedajemy) lub "in" (kupujemy); kolumna nie ma ograniczenia po stronie serwera, więc błędne słowo zostanie zapisane, a kontrakt nie będzie pasował do żadnego filtra nigdzie. PRZEKAŻ NAJPIERW dryRun:true. Maksymalnie 500 wierszy. Wymaga ROLE_CONTRACTS_MANAGER. Zapis. |
| contracts_create | Utwórz umowę. Zapis. |
| contracts_update | Zaktualizuj umowę po id. Zapis. |
| contracts_delete | Usuń umowę po id. Zapis. |
Grupy kosztowe
Narzędzia
| Narzędzie | Opis |
|---|---|
| costGroups_list | Listuje grupy kosztów / centra kosztów — kategorie, pod którymi ewidencjonowane są koszty, dostawcy i faktury przychodzące. Użyj tego, aby rozwiązać id costGroup, wymagane przez suppliers_create i proponowane przez sugestie faktur przychodzących. |
| costGroups_create | Utwórz grupę kosztową / centrum kosztów (wymagane name + type). Zapis. |
| costGroups_update | Zaktualizuj nazwę lub typ grupy kosztowej / centrum kosztów po id. Zapis. |
Kontrahenci
Narzędzia
| Narzędzie | Opis |
|---|---|
| counterparties_get | Pobierz jednego kontrahenta po id. |
| counterparties_list | Wylistuj kontrahentów — każdą stronę, z którą organizacja zawiera transakcje. Flagi supplier i client określają, jaką rolę(-e) pełni kontrahent, a jeden rekord może pełnić obie naraz. To strona widoczna na transakcji bankowej, więc to właśnie z nią dopasowywane są faktury przychodzące i transakcje. Filtruj po type, supplier, client, cyclic lub budgetNeutral. |
Notatki CRM
Narzędzia
| Narzędzie | Opis |
|---|---|
| crmNotes_get | Pobierz jedną notatkę CRM po id. |
| crmNotes_list | Wylistuj notatki zapisane na leadach i szansach sprzedaży. Filtruj po lead lub deal, aby odczytać bieżący komentarz do jednego rekordu. |
| crmNotes_create | Dodaj notatkę do leada lub szansy sprzedaży (body + dokładnie jedno z lead/deal). Autorem jest połączony użytkownik. Zapis. |
| crmNotes_update | Zaktualizuj treść notatki CRM po id. Zapis. |
| crmNotes_delete | Usuń notatkę CRM po id. Zapis. |
Powody utraty szans sprzedaży
Narzędzia
| Narzędzie | Opis |
|---|---|
| dealLostReasons_get | Pobierz jeden powód utraty szansy sprzedaży po id. |
| dealLostReasons_list | Listuje w kolejności powody, dla których szansa sprzedaży może zostać oznaczona jako przegrana. deals_lose wymaga lostReasonId stąd. |
Szanse sprzedaży
Narzędzia
| Narzędzie | Opis |
|---|---|
| deals_get | Pobierz jedną szansę sprzedaży po id — tytuł, klient, etap, kwota, właściciel, kontakt, spodziewana i faktyczna data zamknięcia. |
| deals_list | Wylistuj szanse sprzedaży/okazje — pipeline sprzedaży. Filtruj po status (open / won / lost), etapie, właścicielu, kliencie, leadzie lub po zakresach expectedCloseDate / closedAt. Kwoty podane są w jednostkach pomocniczych z jawną walutą; nie zakładaj domyślnej waluty organizacji. |
| deals_create | Utwórz szansę sprzedaży (deal/opportunity). Wymagane: title, stage (z stages_list) oraz KOTWICA — co najmniej jedno z client lub lead. Szansa bez żadnego z nich jest odrzucana z kodem 422 "A deal must reference a client or a lead.", więc dla prospekta, dla którego nie masz jeszcze rekordu klienta, zakotwicz go do jego leada (`/leads/<id>` z leads_list), zamiast wymyślać klienta; przekaż client (`/clients/<id>` z clients_list), gdy już taki istnieje. Ustawienie obu jest dozwolone. Opcjonalnie: amountMinor, currency, expectedCloseDate, owner, contact. Utworzenie od razu w stage wygranej dodatkowo wymaga client — szansa powiązana tylko z leadem nie może zostać wygrana. Zapis. |
| deals_update | Zaktualizuj szansę sprzedaży po id (title, stage, amountMinor, currency, expectedCloseDate, owner, contact, client, lead). Przesunięcie stage jest logowane automatycznie. Reguła kotwicy z deals_create wciąż obowiązuje dla wyniku, więc nie można wyczyścić jedynego client lub lead, jakie ma szansa — najpierw podstaw inny. Przesunięcie szansy do stage wygranej wymaga client: przypisz tu klienta (lub uruchom leads_convert), zanim wygrasz szansę powiązaną tylko z leadem. Zapis. |
| deals_delete | Usuń szansę sprzedaży po id (miękkie usunięcie). Zapis. |
| deals_win | Oznacz szansę jako wygraną — przenosi ją do stage wygranej i oznacza jako zamkniętą; opcjonalne contractId łączy z istniejącym kontraktem. UZUPEŁNIANIE HISTORYCZNEJ WYGRANEJ: przekaż opcjonalne closedAt (ISO-8601, np. "2026-05-07" lub pełny znacznik czasu), by zapisać datę, kiedy FAKTYCZNIE się zamknęła. Pomiń je, a serwer oznaczy bieżący moment, co umieści starą szansę w tegomiesięcznym wskaźniku "wygrane w tym miesiącu" — ustaw je więc zawsze, gdy wprowadzasz szansę, która zamknęła się przed dzisiaj. Nie może być w przyszłości (422) i MOŻE być wcześniejsze niż własne createdAt szansy: szansa utworzona dziś, a zamknięta w maju, to normalny kształt poprawnego uzupełnienia historii, nie błąd. Szansa musi JUŻ mieć powiązanego client: wygranie szansy powiązanej tylko z leadem jest odrzucane z kodem 422 "Attach a customer before marking this deal Won.", ponieważ nie ma kogo obciążyć fakturą. Zamień leada w klienta przez leads_convert lub ustaw client przez deals_update, a potem oznacz jako wygraną. Zapis. |
| deals_lose | Oznacz szansę jako przegraną — wymaga lostReasonId (z dealLostReasons_list); opcjonalnie lostReasonNote. UZUPEŁNIANIE HISTORYCZNEJ PRZEGRANEJ: przekaż opcjonalne closedAt (ISO-8601), by zapisać datę, kiedy FAKTYCZNIE się zamknęła, dokładnie tak jak robi to deals_win. Pomiń je, a serwer oznaczy bieżący moment. Nie może być w przyszłości (422) i może być wcześniejsze niż createdAt szansy. Zapis. |
| deals_reopen | Otwórz ponownie wygraną/utraconą szansę sprzedaży. Zapis. |
Historie etapów szans sprzedaży
Narzędzia
| Narzędzie | Opis |
|---|---|
| dealStageHistories_get | Pobierz jeden rekord zmiany etapu szansy sprzedaży po id. |
| dealStageHistories_list | Listuje przejścia etapów szansy sprzedaży, od najnowszych. Filtruj po deal. Każde deals_update, które zmienia etap, jest tu automatycznie logowane, więc w ten sposób odtwarzasz, ile czasu szansa spędziła na każdym etapie — sama szansa przechowuje tylko etap bieżący. |
Departamenty
Narzędzia
| Narzędzie | Opis |
|---|---|
| departments_list | Działy organizacji wraz z numerycznym id, po którym każdy z nich jest referencjonowany. PRZECZYTAJ TO PRZED people_create LUB people_update: obydwa akceptują IRI `department`, a nie ma innego sposobu, by znaleźć prawidłowe. Kolekcja jest bez paginacji i posortowana wg name, więc jedno wywołanie zwraca każdy dział, jaki ma organizacja. Filtruj po `name` (dopasowanie częściowe) lub `code` (dokładne). Wiersze zawierają id, name i code; `manager` jest relacją i nie jest zawarty w wierszach listy — odczytaj go z people_list z drugiej strony, jeśli potrzebujesz. Wymaga ROLE_EMPLOYEES_VIEWER. Tylko do odczytu. |
| departments_create | Dodaj dział, aby można było przypisywać do niego osoby. `name` jest wymagane (do 128 znaków) i UNIKALNE w organizacji; `code` jest opcjonalne (do 64) i RÓWNIEŻ unikalne — skrócona forma, jakiej organizacja już używa we własnych arkuszach (CEO, TECH, PROC). `manager` to opcjonalne IRI pracownika z people_list. NAJPIERW LISTA, SPODZIEWAJ SIĘ KOLIZJI: ponieważ zarówno name, jak i code są unikalne, ponowne wysłanie działu, który już istnieje, KOŃCZY SIĘ BŁĘDEM zamiast być idempotentne, więc import zakładający tworzenie wiersz-po-wierszu zatrzyma się przy pierwszym dziale, który organizacja już ma — zwykle pozostałości po wersji próbnej. Ujednolić taki wiersz przez departments_update zamiast tworzyć obok niego kolejny. NIE MA USUWANIA: backend nie udostępnia usuwania działu, więc błędną name lub code poprawia się w miejscu przez departments_update, nigdy się ich nie usuwa. Wymaga ROLE_EMPLOYEES_MANAGER. Zapis. |
| departments_update | Zmień nazwę działu, nadaj mu code lub ustaw jego manager. To narzędzie, które czyni import działów możliwym, a nie tylko wygodnym: zarówno `name`, jak i `code` są unikalne, więc dział, który organizacja już ma — pojedynczy wiersz "HR" pozostawiony zwykle po proof-of-concept — nie może zostać utworzony ponownie, a do właściwej listy dochodzi się POPRAWIAJĄC ten wiersz, zamiast się z nim zderzać. Zmieniają się tylko przesłane pola, więc przekazanie samego `code` pozostawia name nietkniętą. `id` to numeryczne id z departments_list; `manager` to IRI pracownika z people_list. NIE MA USUWANIA, co czyni to narzędzie całą historią naprawy: dział utworzony z literówką jest tu poprawiany, a ten, który nie powinien istnieć, można jedynie zmienić nazwę, nie usunąć. Wymaga ROLE_EMPLOYEES_MANAGER. Zapis. |
Limity dni urlopowych
Narzędzia
| Narzędzie | Opis |
|---|---|
| holidayDaysLimits_get | Jeden wiersz uprawnienia urlopowego po id — amount, type, wariant umowy oraz datę, od której obowiązuje. holidayDaysLimits_list pozwala znaleźć id. Kwoty są w SEKUNDACH. Tylko do odczytu. |
| holidayDaysLimits_list | Ile urlopu KAŻDEJ osobie PRZYSŁUGUJE, wg typu — nie ile już wykorzystała, bo to holidays_list. Filtruj po employee. Jedna osoba może w czasie mieć kilka wierszy dla jednego typu, ponieważ saldo bywa doładowywane lub korygowane: wiersz OBOWIĄZUJĄCY to ten z najpóźniejszym dateFrom, które już nadeszło, a wiersze z datą w przyszłości są celowo ignorowane aż do tego czasu. Kwoty są w SEKUNDACH — dzień urlopu 8h to 28800. Wymaga ROLE_HOLIDAYS_MANAGER. Tylko do odczytu. |
| holidayDaysLimits_create | Przyznaj osobie limit jednego typu urlopu, obowiązujący od daty. `seconds`, NIE dni: dzień 8h to 28800, więc 21 dni to 604800, a saldo nadgodzin 2h30 to 9000 — liczba, która nie miała gdzie się zmieścić, dopóki było to przechowywane w pełnych dniach. `employee` i `holidayType` to IRI (dostarczają je people_list i holidayTypes_list); `variant` to typ umowy, do którego należy limit (uop, b2b, uz, uod). Aby SKORYGOWAĆ istniejące saldo, dodaj wiersz z późniejszym dateFrom, zamiast edytować stary — obowiązującym wierszem jest ten najpóźniejszy, którego dateFrom już nadeszło, więc historia pozostaje nienaruszona, a korekta może zostać wprowadzona, zanim zacznie obowiązywać. (employee, holidayType, variant, dateFrom) jest unikalne, więc ponowne wysłanie tego samego dnia niczego nie zastępuje i kończy się błędem. Wymaga ROLE_HOLIDAYS_MANAGER. Zapis. |
| holidayDaysLimits_update | Popraw wiersz wprowadzony błędnie — literówkę w amount, zły variant. Kwoty są w SEKUNDACH. TO NIE JEST sposób na zarejestrowanie ZMIANY salda w czasie: do tego stwórz przez holidayDaysLimits_create nowy wiersz z późniejszym dateFrom, co zachowuje informację o tym, jakie było poprzednie saldo i kiedy. Edycja w miejscu nadpisuje historię i sprawia, że starej liczby nie da się odzyskać. holidayDaysLimits_list pozwala znaleźć id. Wymaga ROLE_HOLIDAYS_MANAGER. Zapis. |
Wnioski urlopowe
Narzędzia
| Narzędzie | Opis |
|---|---|
| holidayRequests_list | WNIOSKI urlopowe i ich status — oczekujący, zatwierdzony, odrzucony. Odróżnij od holidays_list, które przedstawia zarezerwowany urlop: wniosek oczekujący na decyzję nie jest jeszcze nieobecnością, więc planuj na podstawie holidays_list, a tego endpointu użyj, aby zobaczyć, co czeka na czyjąś decyzję. Dostarcza holidayRequestId przyjmowane przez holidays_approve i holidays_bulkApprove. Tylko do odczytu. |
| holidayRequests_cancel | Anuluj wniosek urlopowy — użyj tego, by usunąć wniosek, na którym nigdy nie powinno się działać, np. wiersz pozostawiony po wersji próbnej, teście lub osobie, która odeszła. DWIE RZECZY, KTÓRE ZASKAKUJĄ. (1) NIE USUWA WIERSZA: backend ustawia status na `canceled`, zamiast usuwać wiersz. ALE ANULOWANY WNIOSEK ZNIKA Z holidayRequests_list — zweryfikowano na produkcji: potem ani lista bez filtra, ani status=canceled go nie zwraca. Nie da się więc odczytać z powrotem tego, co zostało anulowane, i nie ma cofnięcia przez MCP; upewnij się co do id przed wywołaniem. (2) TO NIE JEST TO SAMO, CO ODRZUCENIE. Odrzucenie rejestruje decyzję — zapisuje wpis w dzienniku zatwierdzeń wskazujący ciebie i WYSYŁA PRACOWNIKOWI E-MAIL, że jego urlop został odrzucony — podczas gdy anulowanie powiadamia wyłącznie HR, i tylko gdy `notify-hr-managers-of-leave-activity` jest włączone dla organizacji. Dla wiersza, który nigdy nie był prawdziwym wnioskiem, anulowanie jest uczciwsze i cichsze. DZIAŁA WYŁĄCZNIE NA OCZEKUJĄCYM (`requested`) wniosku, gdy nie jesteś jego właścicielem: zaakceptowany wniosek wygenerował już Holiday, którego to narzędzie nie usuwa, więc anulowanie go pozostawiłoby zarezerwowaną nieobecność za wnioskiem oznaczonym jako `canceled`. Wymaga ROLE_HOLIDAYS_MANAGER dla wniosku innej osoby; wnioskujący zawsze może anulować własny. holidayRequests_list dostarcza id. Zapis. |
Urlopy
Narzędzia
| Narzędzie | Opis |
|---|---|
| holidays_active | Kto jest nieobecny WŁAŚNIE TERAZ — każdy aktualnie trwający urlop, w całej organizacji, dla wszystkich. To narzędzie do pytania „kto jest dziś nieobecny” i to, które warto sprawdzić krzyżowo, zanim freePercent z resourcingBench_get zostanie potraktowane jako dostępność, ponieważ bench nie odejmuje urlopów. W przeciwieństwie do holidays_list nie stosuje żadnego zawężenia do projektu i nie wymaga uprawnień poza zalogowaniem, więc jego odpowiedź obejmuje całą organizację. Zwraca każdą nieobecność wraz z typem i datami. Tylko do odczytu. |
| holidays_get | Jeden rekord urlopu po id, z typem, datami i czasem trwania. Pobierz id z holidays_list lub holidays_active. Tylko do odczytu. |
| holidays_list | Zarezerwowany urlop w danym okresie — widok planistyczny, podczas gdy holidays_active odpowiada wyłącznie na pytanie o dziś. Filtruj po employee, zakresie dat lub project. TO, CO WIDZISZ, ZALEŻY OD TWOICH UPRAWNIEŃ, a krótka lista nie jest dowodem, że nikt nie jest nieobecny: menedżer urlopów lub przeglądający dział księgowości widzi całą organizację, natomiast lider projektu lub przeglądający MUSI przekazać filtr project (lub zapytać o siebie) i bez niego zostaje wprost odrzucony — ta odmowa to granica uprawnień, a nie pusty kalendarz. Tylko do odczytu. |
| holidays_create | Zarejestruj urlop, który dana osoba faktycznie wykorzystuje — samą zarezerwowaną nieobecność, a nie uprawnienie (holidayDaysLimits_create) ani oczekujący wniosek (wnioski urlopowe, które wciąż wymagają zatwierdzenia). To, co tu jest zapisywane, to już uzgodniony czas wolny, więc pojawia się od razu w holidays_list i nie wymaga kroku zatwierdzenia. `employee` to IRI z people_list; `type` to id z holidayTypes_list. `dateFrom`/`dateTo` włącznie, a jedno wywołanie obejmuje cały zakres, a nie wiersz na dzień. Dwie rzeczy gryzą: typ, którego `descriptionRequired` jest true (odczytaj najpierw holidayTypes_list — `vacations` zwykle taki jest) ODRZUCA utworzenie bez `description`; a `pick-up-day` to czas już należny, więc NIE zużywa rocznego limitu tak, jak robi to `vacations` — zapisanie dnia oddanego za sobotnie święto państwowe jako `vacations` po cichu zjada dzień czyjegoś uprawnienia. Sprawdź holidays_list dla tej samej osoby i dat przed utworzeniem, ponieważ nakładanie się jest ODRZUCANE, a nie duplikowane: backend zgłasza `validation_holiday_dates_overlap` jako 422 na `dateTo`, gdy zakres dotyka dowolnego dnia już pokrytego inną nieobecnością tej osoby. Jedyny wyjątek jest wąski — dwie JEDNODNIOWE nieobecności na część dnia w tej samej dacie, RÓŻNYCH typów, każda `vacations` lub `pick-up-day`, których godziny łącznie mieszczą się w dniu pracy. Wszystko inne, co się nakłada, kończy się niepowodzeniem. ISTNIEJE holidays_update, więc zmiana typu nieobecności nie wymaga już usunięcia i ponownego utworzenia. KAŻDE UTWORZENIE WYSYŁA PRACOWNIKOWI E-MAIL, na jego własny adres firmowy, informujący, że nieobecność została dodana — więc wczytanie roku historii, którą ktoś już przeżył, trafia do jego skrzynki wiersz po wierszu, a dla pracowników, którzy nie zostali jeszcze zaproszeni, jest to w ogóle pierwsza wiadomość o Flowtly. WCZYTUJESZ ROK HISTORII? Istnieje forma zbiorcza — holidays_import uzgadnia do 500 nieobecności w jednym wywołaniu, pomija te, które już są zapisane, więc można go bezpiecznie uruchomić ponownie, i domyślnie ma wyłączony e-mail — ale NIE JEST DOSTĘPNY NA TYM POŁĄCZENIU: jest udostępniany wyłącznie w zakresie internal, więc nie możesz go tu wywołać, a szukanie go nic nie da. Wywołuj to narzędzie w pętli albo poproś swojego operatora Flowtly o przeprowadzenie zbiorczego wczytania. Przekaż `notify: false` przy UZUPEŁNIANIU WSTECZNYM nieobecności, które już się odbyły; nie ruszaj go przy rejestrowaniu czegoś nowego, bo wtedy e-mail jest właśnie celem. Wyłącza to tylko wiadomość — wiersz, jego `createdAt` i jego fakt płacowy są zapisywane tak czy inaczej. Wymaga ROLE_HOLIDAYS_MANAGER. Zapis. |
| holidays_delete | Usuń zarezerwowaną nieobecność bezpowrotnie — wiersz zostaje skasowany, w przeciwieństwie do holidayRequests_cancel, który jedynie zmienia status wniosku. Użyj tego, by usunąć nieobecności, które nigdy nie powinny się liczyć: wiersze demo lub testowe pozostawione po wersji próbnej, albo osierocone po usunięciu pracownika (people_delete odłącza nieobecności, zamiast je usuwać, więc przetrwają z pustą nazwą pracownika). TO PORUSZA PRAWDZIWE LICZBY: zarezerwowana nieobecność ma `payrollEligible` i zużywa uprawnienie osoby, więc usunięcie jej zmienia jej saldo urlopowe — to jest cel przy czyszczeniu danych testowych, a błąd utraty danych, gdy wiersz był prawdziwy. Brak cofnięcia, brak powiadomienia. Odczytaj najpierw holidays_list i upewnij się, że wiersz nie jest prawdziwą historią: opis w języku własnym organizacji lub daty pasujące do faktycznej nieobecności zwykle oznaczają, że jest. Wymaga ROLE_HOLIDAYS_MANAGER. Zapis. |
Rodzaje urlopów
Narzędzia
| Narzędzie | Opis |
|---|---|
| holidayTypes_list | Typy urlopów używane przez tę organizację wraz z id, po którym każdy jest referencjonowany. Odczytaj to przed holidayDaysLimits_create/update, które potrzebują IRI holidayType i w przeciwnym razie zostanie ono zgadnięte. Tym, który nie jest urlopem w zwykłym sensie, jest `pick-up-day` — czas wolny należny za już przepracowane nadgodziny (polski *odbiór nadgodzin*), czyli saldo PRZYZNANE, a nie roczne uprawnienie. Tylko do odczytu. |
| holidayTypes_create | Dodaj typ urlopu, którego organizacja jeszcze nie oferuje — urlop naukowy, nieodpłatną opiekę nad dzieckiem, dzień szkoleniowy — aby nieobecności można było rejestrować wobec niego przez holidays_create, a limit przyznawać przez holidayDaysLimits_create. `name` (3–64 znaki) to to, spośród czego ludzie wybierają przy rezerwacji; `color` i `icon` decydują o tym, jak wygląda w kalendarzu; `reducesWorkingTime` ustawione na false oznacza czas wolny, który NIE obniża oczekiwanych godzin w miesiącu; a `descriptionRequired` ustawione na true wymaga od typu podania powodu, co następnie egzekwuje holidays_create — zobacz to narzędzie, by dowiedzieć się, co odrzuca. `status` domyślnie to `active`, więc typ utworzony bez zastanowienia jest natychmiast dostępny dla wszystkich. NAJPIERW ODCZYTAJ holidayTypes_list: typy obowiązują w całej organizacji, i NIE MA USUWANIA — duplikat lub błędnie napisaną nazwę można jedynie ponownie ukryć, ustawiając status na inactive przez holidayTypes_update, a to zachowuje w międzyczasie każdą nieobecność zarejestrowaną wobec tego typu. Wymaga ROLE_HOLIDAYS_MANAGER. Zapis. |
| holidayTypes_update | Zmień typ urlopu, a przede wszystkim WŁĄCZ GO Z POWROTEM. `status` przełącza się między `active` i `inactive`, a nieaktywny typ jest odrzucany przez holidays_create — więc rejestrowanie historycznego urlopu wobec typu, który organizacja od tego czasu wycofała, zaczyna się właśnie tutaj, i to właśnie odblokowuje import historii urlopów, zamiast wysyłać kogoś do UI aplikacji. DEZAKTYWACJA TO NIE USUWANIE, a usuwania nie ma: nieobecności już zarezerwowane zachowują nieaktywny typ i wciąż są z nim odczytywane w holidays_list, więc inactive oznacza jedynie "niedostępny dla nowych rezerwacji". PUŁAPKA, KTÓRA Z TEGO WYNIKA: reaktywuj `vacations`, by wczytać zeszłoroczne nieobecności, zapomnij ustawić go z powrotem na `inactive`, a nie tylko skończysz import — zmienisz to, co organizacja oferuje dziś, ponieważ każdy pracownik rezerwujący urlop znów widzi ten typ na liście. Ustaw go z powrotem w tej samej sesji, w której importowałeś. `descriptionRequired` sięga też do holidays_create, które po włączeniu odrzuca rezerwację bez opisu; włączenie tego pozostawia w spokoju nieobecności już zarejestrowane. `id` to id-ciąg znaków z holidayTypes_list (`vacations`, `not-paid`), a zmieniają się tylko przesłane pola. Wymaga ROLE_HOLIDAYS_MANAGER. Zapis. |
Faktury przychodzące
Narzędzia
| Narzędzie | Opis |
|---|---|
| incomingInvoices_get | Pobierz jedną fakturę przychodzącą (od dostawcy) lub dokument uzupełniający po id, wraz z polami odczytanymi przez OCR i aktualnym stanem dopasowania. |
| incomingInvoices_list | Listuje faktury przychodzące (od dostawców) i dokumenty towarzyszące — skrzynkę księgowości. Faktura przychodząca JEST dokumentem dołączonym do transakcji bankowej, więc exists.transaction=false to sposób na znalezienie dokumentów jeszcze niedopasowanych do płatności. Filtruj też po status, relatedMonth, counterparty, project, tags lub hasDetectedProblems. Każdy dokument ma odcisk palca jako externalId 'upload_sha256:<sha256 bajtów>' — zahaszuj plik i sprawdź tu ten externalId PRZED incomingInvoices_create, inaczej zarejestrujesz duplikat. |
| incomingInvoices_matchCandidates | Wylistuj transakcje bankowe, które mogą być płatnością za tę fakturę przychodzącą, uszeregowane przez wbudowany matcher backendu. Sięgnij po to, gdy dokument nie ma dołączonej transakcji i musisz ją wybrać; wybieraj spośród tych kandydatów zamiast zgadywać samodzielnie na podstawie kwot. |
| incomingInvoices_suggestions | Odczytuje własne propozycje Flowtly dla faktury przychodzącej — dopasowanie dostawcy, grupę kosztów, pasującą transakcję bankową, ostrzeżenie o duplikacie. To dokładnie te same propozycje, które widzi człowiek w aplikacji. Odczytaj je najpierw, a następnie zastosuj jedną po id za pomocą incomingInvoices_applySuggestion, albo przyjmij wszystkie za pomocą acceptAllSuggestions. Przekaż refresh, aby przeliczyć na nowo zamiast zwrócić buforowany zestaw. |
| incomingInvoices_suggestionsDebug | Wyjaśnia, DLACZEGO sugestie dla faktury przychodzącej wyszły takie, jakie wyszły — punktację mechanizmu dopasowującego, do diagnozowania brakującej lub błędnej sugestii. Wyłącznie do diagnostyki; do normalnej pracy używaj incomingInvoices_suggestions. |
| incomingInvoices_create | Rejestruje fakturę przychodzącą (od dostawcy) lub dokument towarzyszący w księgowości — przekaż bajty jako base64 wraz z fileName i receivedAt. Flowtly wykonuje na nim OCR i sugeruje dostawcę oraz pasującą transakcję bankową. Plik ma odcisk palca jako externalId 'upload_sha256:<sha256 bajtów>': aby uniknąć duplikatu, zahaszuj bajty i sprawdź incomingInvoices_list pod kątem tego externalId PRZED przesłaniem. Zapis. |
| incomingInvoices_applySuggestion | Przyjmuje jedną z własnych sugestii Flowtly dla faktury przychodzącej — te same propozycje, które widzi człowiek w aplikacji (dopasowanie dostawcy, grupa kosztów, pasująca transakcja bankowa, ostrzeżenie o duplikacie). Najpierw odczytaj je za pomocą incomingInvoices_suggestions, a następnie zastosuj jedną po jej id. Preferuj to zamiast zgadywania: to mechanizm dopasowujący Flowtly, a nie agent, decyduje, co jest wiarygodne. Zapis. |
| incomingInvoices_acceptAllSuggestions | Zaakceptuj wszystkie oczekujące sugestie dla faktury przychodzącej jednym wywołaniem — to, co robi człowiek przyciskiem „accept all” w aplikacji. Serwer stosuje, przebudowuje i ponownie stosuje sugestie, aż nic nowego się nie pojawi: dopasowanie transakcji NIE istnieje, dopóki nie zostaną zastosowane dostawca i kwota, więc pojedynczy przebieg zostawiłby dokument bez powiązania. Zwraca raport (co zostało zastosowane, co zostało odrzucone i dlaczego oraz transakcję, do której dokument ostatecznie trafił). Przekaż dryRun, aby zobaczyć podgląd bez zapisu. Nigdy nie akceptuje supplier_create ani ostrzeżenia o duplikacie. Zapis. |
| incomingInvoices_checkEInvoices | Pobiera do organizacji nowe e-faktury z KSeF — to samo, co robi przycisk „Sprawdź e-faktury” w aplikacji. Wywołaj to, zanim uznasz, że brakuje faktury od dostawcy: bez tego nie da się odróżnić „dostawca nigdy jej nie wysłał” od „nasza synchronizacja jeszcze się nie odbyła”. Zwraca odpowiedź, gdy pobieranie zostanie skolejkowane; odczytaj potem incomingInvoices_list, aby zobaczyć, co dotarło. Zapis. |
Pozycje budżetu początkowego
Narzędzia
| Narzędzie | Opis |
|---|---|
| initialBudgetItems_list | Lista pozycji budżetu początkowego — planowane kwoty, wg taga, wobec których zwraca wynik contractComparison. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
Budżety początkowe
Narzędzia
| Narzędzie | Opis |
|---|---|
| initialBudgets_contractComparison | PLANOWANE kontra ZAKONTRAKTOWANE, wg taga — planowane kwoty budżetu początkowego zestawione z sumą wartości umów faktycznie podpisanych dla tego projektu. To odpowiedź na pytanie "czy zobowiązaliśmy się do więcej, niż zaplanowaliśmy w budżecie, i gdzie", odczytywana bezpośrednio z kontraktów już obecnych w organizacji, więc zaimportowanie kontraktów daje odpowiedź bez dodatkowej pracy. Kwoty są w groszach; projekt z mieszanymi walutami generuje ostrzeżenie zamiast po cichu błędnej sumy. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
| initialBudgets_get | Pobierz jeden budżet początkowy po id, wraz z jego pozycjami. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
| initialBudgets_list | Lista budżetów początkowych — PIERWOTNY plan dla projektu lub inwestycji, w przeciwieństwie do bieżącego budżetu, wobec którego jest mierzony. Wymaga ROLE_BUDGETS_VIEWER. Tylko do odczytu. |
Faktury
Narzędzia
| Narzędzie | Opis |
|---|---|
| invoices_get | Pobierz jedną fakturę wychodzącą (sprzedażową) po id — klient, pozycje, sumy, daty sprzedaży i wystawienia, status. |
| invoices_list | Listuje faktury wychodzące (sprzedażowe). Filtruj po client, tags, search lub zakresie saleDate. Zauważ, że saleDate — a nie data wystawienia ani data utworzenia — to pole, po którym filtruje invoices_export, więc użyj tego samego pola tutaj przy uzgadnianiu eksportu. |
| invoices_export | Uruchamia eksport zip WYSTAWIONYCH faktur za okres (from/to, oba w formacie YYYY-MM-DD, włącznie), filtrowany po DACIE SPRZEDAŻY — nie dacie wystawienia ani utworzenia. Uwzględniane są tylko faktury WYSTAWIONE; wersje robocze i niewysłane faktury są wykluczone, ale korekty SĄ uwzględniane. Opcjonalne client ogranicza do jednego klienta (id lub IRI z clients_list). Maksymalnie 200 faktur na eksport — jeśli okres zawiera więcej, zawęź go (np. eksportuj po jednym miesiącu); okres z 0 wystawionymi fakturami również jest odrzucany. To wywołanie tylko dodaje zadanie do kolejki (renderowanie miesiąca może zająć minuty) — NIE zwraca linku do pobrania. Odpytuj invoices_exportStatus zwróconym exportId, aż zgłosi "ready". Zapis. |
| invoices_exportStatus | Odpytuje status eksportu zip uruchomionego przez invoices_export, po exportId. Gdy status to "ready", odpowiedź zawiera downloadUrl (krótkotrwały podpisany link — wygasa po 1 godzinie, zobacz expiresAt), filename i byteSize; bajty pliku nigdy nie są zwracane przez to narzędzie. Jeśli status to "failed", failureReason wyjaśnia dlaczego. |
| invoices_import | Zaimportuj do organizacji JUŻ WYSTAWIONĄ fakturę sprzedażową (wychodzącą) — do wczytywania historii faktur przy onboardingu. Przekazany zewnętrzny numer faktury jest zachowywany dosłownie, kupujący jest rozwiązywany po numerze podatkowym (tworzony, jeśli nie istnieje), a faktura ląduje jako wystawiona BEZ renderowania PDF-a, wysyłania e-maila do klienta czy zgłaszania do KSeF. Import numeru, który już istnieje, jest operacją bezoperacyjną (no-op), która zgłasza istniejącą fakturę, więc import masowy jest bezpieczny do ponownego uruchomienia — ale ta gwarancja obowiązuje tylko dla wywołań sekwencyjnych; dwa faktycznie równoczesne importy tego samego numeru mogą się oba zapisać. Przekaż expectedGrossTotal (kwotę brutto wydrukowaną na dokumencie źródłowym), a import zostanie odrzucony, jeśli nie zgadza się z sumą wyliczoną z pozycji. buyer.tin jest wymagane — kupujący nigdy nie jest dopasowywany po nazwie. Użyj invoices_create, nie tego narzędzia, by wystawić rzeczywiście nową fakturę. Zapis. Przekaż dryRun:true, by PODEJRZEĆ bez zapisu — raportuje would-create / would-skip i nie tworzy ani faktury, ani klienta; przy uzupełnianiu historii najpierw uruchom w trybie dry i sprawdź liczby, zanim uruchomisz naprawdę. |
| invoices_create | Wystaw NOWĄ fakturę sprzedażową (wychodzącą) — narzędzie do wystawienia klientowi pierwszego rachunku. Nie myl go z dwoma sąsiadami: invoices_import wprowadza historycznie fakturę, która była JUŻ wystawiona gdzie indziej (historia onboardingu), a incomingInvoices_create rejestruje dokument kosztowy dostawcy. Faktura ląduje jako NIEWYSŁANA: status jest wyprowadzany z wierszy dziennika faktury, a świeżo utworzona faktura nie ma żadnych, więc to wywołanie nic nie renderuje, nie wysyła e-mailem ani nie zgłasza do KSeF — traktuj wynik jako szkic do przejrzenia przed wystawieniem. `name` to numer faktury i wybierasz go samodzielnie (maks. 32 znaki) — odczytaj najpierw invoices_list i podążaj za istniejącą serią numeracji organizacji, zamiast wymyślać własną, ponieważ nic tutaj nie przydziela za ciebie kolejnego numeru. Wymagane: name, type ("invoice"), tinType, issueDate, saleDate, dueDate. Przekaż `client` (IRI z clients_list) oraz, dla rozliczenia, które uzgodni się później, `contract` (IRI z contracts_list), aby faktura pojawiła się pod tym kontraktem. Pozycje trafiają do `invoiceRows` — cena jednostkowa netto, ilość i stawka podatku dla każdego wiersza; sumy są wyliczane z wierszy, nie przekazywane. STAWKA WIERSZA TRANSGRANICZNEGO TO PODSTAWA PRAWNA, NIE LICZBA: oprócz stawek liczbowych `vatRate` przyjmuje `np I`, `np II` i `zw`, jest dowolnym 5-znakowym ciągiem i nic nie weryfikuje, którą wartość wysyłasz. `np I` i `np II` to RÓŻNE podstawy prawne i trafiają do różnych pól faktury KSeF: `np II` to P_13_9, usługi z art. 100 ust. 1 pkt 4 polskiej ustawy o VAT (te, które są również wykazywane w informacji podsumowującej VAT-UE); `np I` to P_13_8, każda inna dostawa poza Polską. To, którą z nich jest dana dostawa, jest decyzją podatkową: weź ją od księgowego organizacji lub z potwierdzonej praktyki organizacji dla tego rodzaju klienta i NIE KOPIUJ STAWKI Z JAKIEJKOLWIEK FAKTURY `np`, KTÓRĄ ORGANIZACJA JUŻ MA — precedens sam może być błędny. Numer podatkowy nabywcy musi już być zapisany BEZ prefiksu kraju (clients_create wyjaśnia dlaczego) — ten dokument drukuje tinCountry połączone z tin, więc klient zapisany jako "RO40424862" drukuje się tu jako RORO40424862. `bankAccount` (z bankAccounts_list) wybiera rachunek wydrukowany na dokumencie, a `currency` domyślnie przyjmuje walutę organizacji. Zapis. |
| invoices_update | Popraw fakturę sprzedażową (wychodzącą) po id, przed wystawieniem lub po nim. Codzienne zastosowanie to poprawianie szkicu wystawionego przez invoices_create — błędna data, zły wiersz, brakujące powiązanie z kontraktem — zamiast usuwania i wystawiania od nowa, co spaliłoby numer faktury. Odczytaj najpierw invoices_get: to PATCH na dokumencie, którego sumy są wyprowadzane z jego wierszy, więc zastąpienie `invoiceRows` zastępuje cały zbiór, a faktura, która została już wysłana, nie cofnie się do stanu niewysłanej tylko dlatego, że ją edytowano. Zapis. |
Aktywności leadów
Narzędzia
| Narzędzie | Opis |
|---|---|
| leadActivities_get | Pobiera jedną aktywność leada (kontakt w ramach outreachu) po id. |
| leadActivities_list | Listuje kontakty outreachowe leada — oś czasu jego aktywności (wysłane zaproszenie, odpowiedzi, rozmowy, follow-upy). Filtruj po lead, aby odczytać historię jednego potencjalnego klienta. To ustrukturyzowany odpowiednik crmNotes_list: aktywności to typowany, datowany dziennik kontaktów; notatki to swobodny komentarz. |
| leadActivities_create | Rejestruje JEDEN kontakt outreachowy na leadzie — wysłane zaproszenie, zaakceptowane zaproszenie, wiadomość, odpowiedź, rozmowę, follow-up (wymagane lead + type + occurredAt; opcjonalne channel, contact, body). TO jest właściwe miejsce dla historii kontaktów potencjalnego klienta: crmNote to swobodny komentarz, activity to ustrukturyzowany, filtrowalny dziennik kontaktów renderowany przez oś czasu kolejki prospectingu. NIE opisuj kontaktów w notatce. type: invite_sent | invite_accepted | message_sent | reply_received | call | meeting | follow_up | …; channel: linkedin | email | phone | …. Zapis. |
| leadActivities_update | Aktualizuje zarejestrowaną aktywność outreachową po id (type, channel, occurredAt, body). Zapis. |
| leadActivities_delete | Usuwa zarejestrowaną aktywność outreachową po id. Zapis. |
| leadActivities_byList | Każda aktywność leada w ramach KAMPANII (listy leadów), w jednym wywołaniu — przekaż id listy, IRI lub dokładną nazwę. leadActivities_list filtruje po pojedynczym leadzie, więc raportowanie na poziomie kampanii kosztowałoby inaczej jedno wywołanie na każdego członka (302 dla listy takiej jak PZFD); to narzędzie zamiast tego rozwiązuje członków listy i odczytuje ich aktywności w ograniczonych partiach. Połącz z type oraz occurredAt.after/.before, by uzyskać liczby, o które ludzie faktycznie pytają: współczynnik odpowiedzi (type=reply_received), współczynnik odrzuceń (type=bounced), pokrycie wysyłki (type=message_sent). Zwraca listId, listName, leadCount oraz scalone aktywności posortowane po occurredAt. Nieznana lista to BŁĄD, nie pusty wynik — więc błędnie wpisana nazwa nie może zostać odczytana jako "ta kampania nie miała żadnej aktywności". Id pochodzą z leadLists_list. Tylko do odczytu. |
| leadActivities_bulkImport | Zarejestruj całą falę wysyłki wychodzącej — każdą wiadomość, którą faktycznie wysłano — w JEDNYM wywołaniu, zamiast jednego leadActivities_create na wiadomość. Przekaż tablicę; każdy wiersz wskazuje swojego leada (leadCompanyName, dopasowywane do ISTNIEJĄCEGO leada, lub IRI leada) plus type i occurredAt. Nadaj każdemu wierszowi externalId — stabilne id per wiadomość, np. id wiadomości Gmail — a import jest idempotentny: ponowne uruchomienie go, lub ponowne uruchomienie fali, która została zaimportowana tylko częściowo, zgłasza duplikaty zamiast je tworzyć. Wiersze bez externalId są deduplikowane po (lead, type, occurredAt, contact) — tym samym naturalnym kluczu, którego używa leads_bulkImport, więc fala, która najpierw trafiła przez to narzędzie, nie zostanie tu zduplikowana. Każdy wiersz otrzymuje własny wynik (created | duplicate | error), więc jeden błędnie sformułowany wiersz nie odrzuca reszty partii. NIE tworzy leadów — użyj do tego leads_bulkImport. ≤ 1000 wierszy na wywołanie. Zapis. |
Kontakty leadów
Narzędzia
| Narzędzie | Opis |
|---|---|
| leadContacts_get | Pobierz jeden kontakt leada po id. |
| leadContacts_list | Wylistuj osoby kontaktowe przypisane do leadów. Filtruj po lead, aby odczytać kontakty jednego potencjalnego klienta, lub po email, aby znaleźć, z którego leada pochodzi wiadomość. |
| leadContacts_create | Dodaje osobę kontaktową do leada (wymagane lead + name; opcjonalne email, phone, role, linkedinUrl, isPrimary). Adres URL LinkedIn kontaktu należy umieścić w linkedinUrl, a NIE w crmNote. Zapis. |
| leadContacts_update | Aktualizuje kontakt leada po id — np. ustaw linkedinUrl / email / phone, gdy je znajdziesz. Zapis. |
| leadContacts_delete | Usuń kontakt leada po id. Zapis. |
Przynależności leadów do list
Narzędzia
| Narzędzie | Opis |
|---|---|
| leadListMemberships_get | Pobierz jedno przypisanie leada do listy po id. Jego status i lastContactedAt to migawka zapisana przez wywołującego, a nie stan na żywo — zobacz leadListMemberships_list. |
| leadListMemberships_list | Lista wskazująca, które leady znajdują się na których listach prospectingu wychodzącego. Filtruj po list, lead lub status. UWAGA: status i lastContactedAt to MIGAWKA zapisana przez tego, kto ostatnio zaimportował lub zaktualizował przypisanie. Nie są one wyliczane, a nic ich nie przesuwa w momencie zarejestrowania aktywności — zalogowanie fali 529 follow-upów nie zmienia żadnego z tych pól — więc mogą być dowolnie mocno nieaktualne. Aby odpowiedzieć na pytanie "kiedy ostatnio kontaktowaliśmy się z tym prospektem", odczytaj zamiast tego dziennik aktywności: leadActivities_list dla jednego leada, leadActivities_byList dla całej kampanii. leadListMemberships_syncFromActivities zgłasza tę rozbieżność i może ją usunąć. |
| leadListMemberships_create | Dodaj leada do listy wychodzącej (wymagane list + lead; status opcjonalny). Każde przekazane lastContactedAt to migawka, której nic potem nie przesunie — zarejestruj kontakt również jako aktywność leada, inaczej pozostanie niemożliwy do odpytania. Zapis. |
| leadListMemberships_update | Zaktualizuj przypisanie leada do listy — np. ustaw status kontaktu (contacted/replied/bounced). status i lastContactedAt są utrzymywane przez wywołującego: to, co zapiszesz, obowiązuje, dopóki ktoś nie zapisze ponownie, a rejestrowanie aktywności leadów NIE aktualizuje tych pól. Zapis. |
| leadListMemberships_delete | Usuń leada z listy wychodzącej. Zapis. |
Listy leadów
Narzędzia
| Narzędzie | Opis |
|---|---|
| leadLists_get | Pobierz jedną listę prospectingu wychodzącego po id. |
| leadLists_list | Listuje listy prospectingu wychodzącego. Użyj tego, aby rozwiązać id list przyjmowane przez leadListMemberships_create. |
| leadLists_create | Utwórz listę prospectingu wychodzącego (wymagane name). Zapis. |
| leadLists_update | Zaktualizuj listę wychodzącą po id. Zapis. |
| leadLists_delete | Usuń listę wychodzącą po id. Zapis. |
Powody utraty leadów
Narzędzia
| Narzędzie | Opis |
|---|---|
| leadLostReasons_get | Pobierz jeden powód utraty leada po id. |
| leadLostReasons_list | Wylistuj powody, dla których lead może zostać oznaczony jako utracony, w kolejności. |
Leady
Narzędzia
| Narzędzie | Opis |
|---|---|
| leads_dedupeCheck | Sprawdza, czy potencjalny klient jest już w CRM, używając tych samych filtrów co leads_list (companyName, source, owner, …). Wywołaj to PRZED leads_create: zduplikowany lead rozdziela historię kontaktów między dwa rekordy, a nic dalej w procesie nie scali ich za ciebie. |
| leads_get | Pobierz jednego leada po id — firma, strona internetowa, źródło, status, właściciel i klient, w którego się przekształcił, jeśli dotyczy. |
| leads_list | Listuje leady — cele prospectingowe przed kwalifikacją. Filtruj po status, source, owner, client, companyName lub zakresach createdAt/closedAt. Zakwalifikowany lead staje się klientem (Client) plus otwartą szansą sprzedaży (Deal) poprzez leads_convert; do tego czasu istnieje tylko tutaj, nie w clients_list. |
| leads_create | Utwórz leada (cel prospectingu wychodzącego/przychodzącego; companyName, source, owner, powiązany client opcjonalnie). Nowy lead zawsze ma status=open — status nie jest tu ustawialny i zmienia się wyłącznie przez leads_convert, leads_lose i leads_reopen. Zapis. |
| leads_update | Zaktualizuj leada po id (company, website, source, owner, powiązany client, stage, doNotContact). NIE status ani lostReason: te są odrzucane przez encję i po cichu ignorowane przez ten endpoint, więc zamknięcie leada wymaga leads_lose (z lostReasonId), a cofnięcie tego — leads_reopen. Przesunięcie `stage` przesuwa lead po lejku sprzedażowym; nie zamyka leada. Zapis. |
| leads_delete | Usuń leada po id (miękkie usunięcie). Zapis. |
| leads_convert | Przekształć zakwalifikowanego leada w klienta + jeden kontakt na każdy kontakt leada + otwartą szansę sprzedaży. Wymaga istniejącego klienta (klienta leada lub clientId w treści żądania). Zapis. |
| leads_lose | Zamknij leada jako PRZEGRANEGO — ustawia status=lost i oznacza closedAt. WYMAGA lostReasonId, czyli `id` wpisu z leadLostReasons (uruchom najpierw leadLostReasons_list; to lista wyboru, więc dowolny tekst zostanie odrzucony z kodem 422). To JEDYNY sposób, by zarejestrować leada jako przegranego: leads_update ignoruje status, a doNotContact oznacza "nigdy więcej nie kontaktuj się", co jest innym i znacznie mocniejszym stwierdzeniem niż "nie wygraliśmy tego". Nie przesuwa stage leada — LeadStage nie ma flagi końcowej, więc lead zachowuje swoją pozycję w lejku, a leads_reopen może ją dokładnie przywrócić. Zapis. |
| leads_reopen | Cofnij leads_lose — ustawia status z powrotem na open i czyści closedAt oraz powód przegranej. Stage pozostaje nietknięty, więc lead wraca dokładnie tam, gdzie był. Sięgnij po to, gdy lead został zamknięty na niewłaściwym rekordzie lub prospekt wrócił. Zapis. |
| leads_bulkImport | Importuje wiele leadów w JEDNYM wywołaniu, każdy z zagnieżdżonymi kontaktami, przynależnością do listy i aktywnościami outreachowymi — serwer tworzy leada, a następnie przekazuje jego id do elementów podrzędnych, więc nigdy nie żonglujesz pośrednimi IRI. Idempotentne względem kluczy naturalnych (companyName / email / (list,lead) / (type,occurredAt,contact)): bezpieczne do ponownego uruchomienia i dzielenia na porcje (≤100 leadów/wywołanie). To ścieżka masowa, z jakiej powinien korzystać import kampanii zamiast N wywołań leads_create. Zapis. |
Etapy leadów
Narzędzia
| Narzędzie | Opis |
|---|---|
| leadStages_get | Pobierz jeden etap leada po id. |
| leadStages_list | Listuje w kolejności etapy, przez które przechodzi lead. Leady mają własny zestaw etapów — szanse sprzedaży (deals) korzystają ze stages_list, co jest czymś innym. |
Lokalizacje
Narzędzia
| Narzędzie | Opis |
|---|---|
| locations_get | Pobierz jedną lokalizację po id — jej name oraz godziny pracy biura. Tylko do odczytu. |
| locations_list | Lista lokalizacji organizacji — fizycznych miejsc, w których znajdują się zasoby, pokazywanych w UI jako Lokalizacja. Wymaga ROLE_LOCATIONS_MANAGER, która nietypowo obejmuje ochroną zarówno ODCZYT, jak i zapis. Tylko do odczytu. |
| locations_create | Utwórz lokalizację (wymagane name; opcjonalne officeOpenHour/officeCloseHour jako sekundy od północy). Użyj prawdziwego adresu, a nie nazwy projektu czy inwestycji — tego właśnie potrzebuje ktoś stojący przed zasobem, a nazwa projektu jest już przenoszona gdzie indziej. Wymaga ROLE_LOCATIONS_MANAGER. Zapis. |
| locations_update | Zmień nazwę lokalizacji lub jej godziny pracy biura. Wymaga ROLE_LOCATIONS_MANAGER. Zapis. |
Adresy organizacji
Narzędzia
| Narzędzie | Opis |
|---|---|
| organizationAddresses_get | Pobierz jeden rekord adresu subskrypcji po id — name, street, city, postCode, country oraz pola podatkowe. `street` zawiera numer budynku, gdy został wpisany ręcznie, a nie zawiera go, gdy pochodzi z wyszukiwania NIP/GUS. Tylko do odczytu. |
| organizationAddresses_list | Lista rekordów adresu subskrypcji organizacji — adres przypisany do subskrypcji Flowtly i źródło, z którego renderuje się stopka maila {{organizationAddress}}. Zwykle dokładnie jeden wiersz. TO NIE JEST adres sprzedawcy na fakturze, który znajduje się w kluczach konfiguracyjnych organization-billing-* (configs_get) i z którego korzystają faktury i KSeF; te dwa miejsca są utrzymywane osobno i regularnie się rozjeżdżają. Odczytaj oba, zanim stwierdzisz, który z nich klient faktycznie edytował. Tylko do odczytu. |
| organizationAddresses_update | Zaktualizuj rekord adresu SUBSKRYPCJI organizacji (wymagane id; wyślij tylko zmieniane pola). TO WŁAŚNIE Z TEGO REKORDU RENDERUJE SIĘ STOPKA MAILA: {{organizationAddress}} w stopce jest składane jako "street, postCode city" właśnie stąd, A NIE z kluczy konfiguracyjnych organization-billing-*, z których korzystają faktury i KSeF jako z adresu sprzedawcy. Te dwa magazyny danych rozjeżdżają się, a odczytywanie tego rekordu przez stopkę to znany defekt — więc gdy podpis pokazuje adres, który klient przysięga, że poprawił, w rzeczywistości poprawił klucze billingowe, a ten rekord wciąż trzyma starą wartość. `street` to pojedyncza kolumna tekstowa, która musi nieść też numer budynku: wyszukiwanie NIP/GUS wypełnia tylko nazwę ulicy i po cichu odrzuca numer budynku i lokalu, dlatego adresy tutaj brzmią "ul. Example" bez numeru. Wpisz pełne "ul. Example 8/12", by to naprawić. NAJPIERW ODCZYTAJ organizationAddresses_list i porównaj z configs_get dla organization-billing-street przed zapisem, aby skopiować faktycznie utrzymywaną wartość klienta, a nie wymyślić nową. Wymaga ROLE_BILLINGS_MANAGER. Zapis. |
Organizacje
Narzędzia
| Narzędzie | Opis |
|---|---|
| organizations_get | Pobiera organizację po id. UWAGA — to NIE mówi, z którą organizacją jesteś połączony. Połączenie OAuth jest przypięte do dokładnie jednej organizacji (powiązanej z tokenem), ale ten endpoint zwraca dowolną organizację, której członkiem jest połączony UŻYTKOWNIK, więc udany odczyt tutaj wygląda jak potwierdzenie, że pracujesz w tej organizacji, choć może tak nie być. Aby zweryfikować, na jakim tenancie faktycznie pracujesz, odczytaj dane zawężone do tenanta — people_list lub clients_list — i nigdy nie rozpoczynaj masowego zapisu na podstawie samego tego wywołania. |
Osoby
Narzędzia
| Narzędzie | Opis |
|---|---|
| people_get | Pobierz jeden rekord osoby/pracownika po id — imiona i nazwiska, e-maile, telefon, przełożony oraz informacja, czy jest aktywny. |
| people_list | Wylistuj osoby/pracowników. Filtruj po isActive, reportsTo (id przełożonego), projectMembers.project lub search; stronicuj za pomocą cursor. Osoby i pracownicy współdzielą to samo id, więc w ten sposób ustalisz id pracownika, którego oczekują narzędzia do czasu pracy, odpowiedzialności, członkostwa w projekcie i uprawnień. |
| people_create | Utwórz rekord osoby/pracownika (wymagane firstname + lastname; opcjonalnie companyEmail, contactEmail, contactPhone). Zapis. |
| people_update | Zaktualizuj rekord osoby/pracownika po id (name, companyEmail, contactEmail, contactPhone itd.). Zapis. |
| people_delete | Usuń rekord pracownika/osoby po id (np. aby usunąć zastępczego/testowego pracownika). Wymaga ROLE_EMPLOYEES_MANAGER; backend uruchamia procesor usuwania, który odłącza też powiązane rekordy. Wysoki wpływ, nieodwracalne. Zapis. |
| people_invite | Nadaj istniejącej osobie LOGIN: tworzy oczekujące zaproszenie do organizacji i wysyła je e-mailem w skonfigurowanym w organizacji języku UI. To krok, którego NIE wykonują people_create ani people_setPermissionGroups — osoba z grupami uprawnień wciąż nie może się zalogować, dopóki nie zostanie zaproszona i nie zaakceptuje zaproszenia. Wymaga e-maila danej osoby; kończy się błędem, jeśli już ma login. Kolejność onboardingu: people_create (rekord) -> people_invite (login) -> people_setPermissionGroups (uprawnienia). Zapis. |
| people_setPermissionGroups | Ustaw (zastąp) CAŁY zestaw grup uprawnień danej osoby po numerycznych id grup (zobacz permissionGroups_list — np. grupa "Business Owner" nadaje ROLE_ADMIN): przekaż każdą grupę, z jaką osoba ma ostatecznie zostać, a [] usuwa je wszystkie. Nadaje dostęp; NIE tworzy loginu ani nie wysyła e-maila do osoby — to robi people_invite. PUŁAPKA: nadanie komuś PIERWSZEJ grupy przenosi go na model wyliczany, w którym role pochodzą z grup i nadpisań indywidualnych (overrides), a rola nadana mu ręcznie poza tym modelem znika w tym samym wywołaniu — ROLE_ADMIN przyznana jednej osobie jest dokładnie tym rodzajem roli, który zostaje usunięty. Działa to też w drugą stronę: usunięcie ostatniej grupy przenosi osobę z powrotem poza ten model i sprawia, że te starsze role pojawiają się ponownie. Listy overridesAdded/overridesRemoved nic o tym nie mówią; opisują one nadpisania (overrides) i pozostają puste, mimo że efektywny dostęp się zmienia. Odpowiedź raportuje więc różnicę między rolami, jakie osoba miała przed tym wywołaniem, a tymi po nim, jako rolesLost i rolesGained — to jest para, którą warto odczytać po zwróceniu wyniku. rolesLost równe null (nie []) oznacza, że migawka wykonana przed zapisem nie mogła zostać odczytana, a delta jest NIEZNANA, z powodem podanym w roleDeltaUnavailable: zmiana grup i tak nastąpiła, więc null nie oznacza, że wszystko jest w porządku — sprawdź ponownie za pomocą people_getPermissions. Aby przywrócić rolę, która powinna była przetrwać, nadaj ją za pomocą people_setRoleOverrides. Wymaga ROLE_ROLES_MANAGER. Zapis. |
| people_setRoleOverrides | Ustaw (zastąp) role, które JEDNA osoba otrzymuje dodatkowo — lub które są jej odbierane — ponad jej grupy uprawnień. Sięgnij najpierw po grupę (people_setPermissionGroups): grupy są zamierzoną abstrakcją i skalują się na więcej niż jedną osobę, więc użyj nadpisania (override) tylko tam, gdzie pojedyncza osoba faktycznie różni się od każdej grupy. ZASTĘPUJE obie listy w całości, więc odczytaj najpierw people_getPermissions i odeślij z powrotem każde nadpisanie, które ma zostać zachowane; pominięcie listy ją czyści. Role to stałe ROLE_ — permissionGroups_list pokazuje te, których ta organizacja już używa. Rola obecna jednocześnie w added i removed jest odrzucana, a nie zgadywana. Zwraca tę samą wyliczoną migawkę co people_getPermissions, więc wynik można potwierdzić bez drugiego wywołania. NIE tworzy loginu — zobacz people_invite. Wymaga ROLE_ROLES_MANAGER. Zapis. |
| people_getPermissions | Co dana osoba faktycznie może robić, w postaci wyliczonej: jej grupy uprawnień (każda z rolami, jakie nadaje), jej indywidualne nadpisania (overrides) oraz effectiveRoles, w które te dwa się łączą. TO jest sposób na sprawdzenie, czy zmiana dostępu się utrwaliła — people_list pokazuje pole roles, ale to narzędzie wyjaśnia, DLACZEGO te role obowiązują i którą dźwignię pociągnąć, by je zmienić. Sięgnij po to przed każdym wywołaniem people_setRoleOverrides, ponieważ to narzędzie zastępuje listy nadpisań w całości, a tutaj odczytujesz te bieżące. staleOverrides to usunięte nadpisania, które nie odpowiadają już żadnej roli nadanej przez grupę, więc obecnie nic nie robią. people_list dostarcza id. Wymaga ROLE_ROLES_MANAGER, by przeglądać kogokolwiek poza sobą. Tylko do odczytu. |
Grupy uprawnień
Narzędzia
| Narzędzie | Opis |
|---|---|
| permissionGroups_get | Pobierz jedną grupę uprawnień po id, wraz z ciągami ROLE_*, które nadaje. |
| permissionGroups_list | Listuje grupy uprawnień organizacji oraz role, jakie każda z nich nadaje — np. grupa „Business Owner” nadaje ROLE_ADMIN. Odczytaj to przed people_setPermissionGroups: role w odpowiedzi są autorytatywnym źródłem tego, co grupa faktycznie zezwala, więc nigdy nie musisz zgadywać na podstawie jej nazwy. |
| permissionGroups_create | Utwórz grupę uprawnień (wymagane name; roles = lista ciągów ROLE_*, które nadaje). Zapis. |
| permissionGroups_update | Zaktualizuj nazwę, opis lub nadawane role grupy uprawnień po id. Zapis. |
Pipeline'y
Narzędzia
| Narzędzie | Opis |
|---|---|
| pipelines_get | Pobierz jeden pipeline sprzedaży po id. |
| pipelines_list | Listuje lejki sprzedażowe (pipelines). Pipeline posiada uporządkowany zestaw etapów — odczytaj je za pomocą stages_list filtrowanego po pipeline. |
Stanowiska
Narzędzia
| Narzędzie | Opis |
|---|---|
| positions_list | Listuje stanowiska — nazwane role (np. „Backend Engineer”), które wypełnia alokacja projektowa. Brak filtrów; Position ma wyłączone stronicowanie, więc ten endpoint zawsze zwraca w jednym wywołaniu pełny katalog ról organizacji. Każdy element to {id, name, roles}. Użyj tego, aby rozwiązać nazwę stanowiska stojącą za positionId wiersza z allocations_list, oraz aby znaleźć id stanowiska, do którego musi dopasować się import zasobowy. |
Członkowie projektu
Narzędzia
| Narzędzie | Opis |
|---|---|
| projectMembers_get | Pobierz jedno członkostwo w projekcie po id — jego employee, project i position. Id pochodzą z projectMembers_list lub tablicy projectMembers w projects_get. |
| projectMembers_list | Lista członkostw w projektach — KTO WIDZI KTÓRY PROJEKT. Filtruj po project (`/projects/{id}`), by odczytać skład jednego projektu, lub po employee, by odczytać każdy projekt dostępny dla danej osoby; każdy wiersz zawiera własne id, employee, project oraz position (employee|tech-lead|account-manager|viewer). Sięgnij po to w pierwszej kolejności, gdy ktoś zgłasza, że projekt zniknął z jego listy Projects albo nie może na niego logować czasu: pusty skład, lub skład bez tej osoby, JEST wyjaśnieniem — widoczność to członkostwo. To też źródło id dla projectMembers_update i projectMembers_delete. Zwróć uwagę, że ta sama osoba może pojawić się kilkukrotnie w jednym projekcie, raz na każdą position. |
| projectMembers_create | Przypisz osobę DO projektu (wymagane IRI employee + project, np. "/people/204" i "/projects/243"; opcjonalne position = employee|tech-lead|account-manager|viewer, domyślnie employee). TO JEST KONTROLA DOSTĘPU, nie etykieta: osoba, która nie jest członkiem, w ogóle nie widzi projektu — brakuje go na jej liście Projects i nie może na niego logować czasu — więc to narzędzie przywraca dostęp komuś zablokowanemu w projekcie. POSITION NIE JEST KOSMETYCZNA: użytkownik posiadający rolę zakresu projektowego widzi tylko te projekty, w których position jego członkostwa jej odpowiada — ROLE_PROJECTS_LEAD odpowiada tech-lead, ROLE_PROJECTS_VIEWER odpowiada viewer — więc nadanie liderowi projektu wiersza `employee` pozostawia go równie "niewidomym", jak brak jakiegokolwiek wiersza. Członkostwo NIE kaskaduje: przypisanie kogoś do folderu nadrzędnego nie daje mu niczego na projektach pod nim, więc drzewo folderów wymaga jednego wywołania na projekt. Unikalnym kluczem jest (employee, project, position), co oznacza, że pozycje się kumulują, a nie zastępują — jedna osoba może mieć jednocześnie employee I tech-lead na tym samym projekcie jako dwa osobne wiersze, a dodanie tech-lead komuś, kto już jest tam employee, nie usuwa ani nie podnosi rangi wiersza employee (użyj projectMembers_update, aby zmienić position w miejscu). Najpierw odczytaj bieżące wiersze za pomocą projectMembers_list?project=/projects/{id} lub projects_get, którego tablica projectMembers zawiera id każdego wiersza. WCZYTUJESZ CAŁY SKŁAD? Istnieje forma zbiorcza — projectMembers_import uzgadnia do 500 członkostw w jednym wywołaniu, pomija te, które już są zapisane, więc można go bezpiecznie uruchomić ponownie, i domyślnie ma wyłączone powiadomienie — ale NIE JEST DOSTĘPNY NA TYM POŁĄCZENIU: jest udostępniany wyłącznie w zakresie internal, więc nie możesz go tu wywołać, a szukanie go nic nie da. Wywołuj to narzędzie w pętli albo poproś swojego operatora Flowtly o przeprowadzenie zbiorczego wczytania. NIE DZIAŁA PO CICHU: dodanie osoby, która nie jest jeszcze w projekcie, wysyła do niej powiadomienie o przypisaniu do projektu, więc wsteczne uzupełnienie 17 projektów wysyła 17 powiadomień. Wymaga ROLE_PROJECTS_MANAGER. Zapis. |
| projectMembers_update | Zmień position istniejącego członkostwa po id (employee|tech-lead|account-manager|viewer) — pobierz id z projectMembers_list lub tablicy projectMembers w projects_get. Użyj tego, by awansować lub degradować W MIEJSCU; użyj projectMembers_create, by dodać drugą, dodatkową pozycję obok już posiadanej. Zmiana pozycji może ODEBRAĆ widoczność projektu komuś, kogo rola ma zakres projektowy (ROLE_PROJECTS_LEAD zdegradowany z tech-lead do employee przestaje go widzieć). Nie można przenieść członkostwa do innej osoby lub projektu — w tym celu usuń i utwórz ponownie. Wymaga ROLE_PROJECTS_MANAGER. Zapis. |
| projectMembers_delete | Usuń osobę Z projektu po id członkostwa — znajdź je za pomocą projectMembers_list lub w tablicy projectMembers w projects_get. To ODBIERA DOSTĘP: gdy zniknie ostatni wiersz członkostwa tej osoby w tym projekcie, projekt znika z jej widoku i nie może już na niego logować czasu — dokładnie tak projekt po cichu znika komuś z pola widzenia. Godziny już zalogowane NIE są usuwane i pozostają w projekcie; osoba po prostu nie może ich już widzieć ani dodawać nowych. Usunięcie jednej pozycji pozostawia nietkniętą każdą inną pozycję, jaką ta sama osoba ma w tym samym projekcie. Wymaga ROLE_PROJECTS_MANAGER. Nieodwracalne (ponowne utworzenie tworzy nowy wiersz i wysyła powiadomienie od nowa), wysokie ryzyko. Zapis. |
Projekty
Narzędzia
| Narzędzie | Opis |
|---|---|
| projects_costAllocations | Jak koszty zostały rozdzielone NA ten projekt — które transakcje i pozycje faktur zostały mu przypisane i w jakim udziale. Użyj tego, by wyjaśnić wynik rentowności, a nie tylko go zacytować: tutaj nieoczekiwany wynik jest śledzony aż do dokumentu, który go spowodował. Wymaga ROLE_TRANSACTIONS_MANAGER. Tylko do odczytu. |
| projects_folderCounts | Ile projektów znajduje się w każdym FOLDERZE projektów, jako folderId + total + active. folderId to id tagDefinition — nazwy rozwiąż przez tagDefinitions_list, a które grupy są grupami folderów sprawdzisz przez tagGroups_list (allowedRelations zawiera "project"). Puste folderId to kubełek nieskategoryzowanych. Liczy tylko projekty główne, bo foldery grupują projekty główne, a fazy idą za rodzicem. Tylko do odczytu. |
| projects_get | Pobierz jeden projekt po id — nazwa, typ, klient, daty, opis i cena. |
| projects_list | Wylistuj projekty. Filtruj po type (fixed-price | time-and-material | non-billable | internal), client.name, employee, name lub zakresach dateFrom/dateTo. Użyj tego, aby ustalić id projektu, którego wymagają zadania, rejestrowanie czasu pracy, budżety i umowy. |
| projects_profitability | WYNIK NA PROJEKT — ile projekt zarobił w zestawieniu z tym, ile kosztował. To liczba, którą zwykle chce zobaczyć firma usługowa lub deweloperska, i ta, którą zasila każde inne narzędzie projektowe. Przekaż id projektu z projects_list. Wymaga ROLE_ACCOUNT_MANAGER. Tylko do odczytu. |
| projects_create | Utwórz projekt (wymagane name + type; type = fixed-price|time-and-material|non-billable|internal; opcjonalnie dateFrom/dateTo, client, publicDescription, notes, priceNet). Zapis. |
| projects_update | Zaktualizuj projekt po id (name, type, daty, opis itd.). Zapis. |
| projects_archive | Archiwizuje projekt po id — sposób na wycofanie projektu, którego nie da się usunąć, bo wiszą na nim zarejestrowany czas, faktury lub budżety. Odwracalne przez projects_unarchive. Lepsze niż cofanie daty dateTo, które sprawia jedynie, że projekt wygląda na zakończony. Zapis. |
| projects_unarchive | Przywraca zarchiwizowany projekt po id, cofając projects_archive. Zapis. |
Szablony projektów
Narzędzia
| Narzędzie | Opis |
|---|---|
| projectTemplates_get | Pobierz jeden szablon projektu po id, wraz z pełnym dokumentem structure. projectTemplates_list pozwala znaleźć id. Odczytaj to przed projectTemplates_update — structure jest zapisywana W CAŁOŚCI, więc aktualizacja musi wysłać kompletny dokument, a nie fragment. Tylko do odczytu. |
| projectTemplates_list | Lista szablonów projektów organizacji — wielokrotnego użytku wzorce projektu, jego faz, list zadań i zadań. Sięgnij po to PRZED projects_create, gdy ten sam kształt projektu jest zakładany wielokrotnie (typ zlecenia, audyt, onboarding): utworzenie instancji szablonu buduje całe drzewo w jednym wywołaniu, podczas gdy projects_create tworzy pusty projekt, który trzeba potem wypełnić ręcznie. Wiersz oznaczony isDefault to wbudowany szablon organizacji, stosowany do projektu utworzonego bez wybrania szablonu. Tylko do odczytu. |
| projectTemplates_create | Utwórz wielokrotnego użytku wzorzec projektu z dokumentu structure (version, project, phases oraz ich lists/tasks). Przesunięcia w nim są WZGLĘDNE — startOffsetDays i durationDays są liczone w dniach od startDate podanej w chwili tworzenia instancji, więc jeden szablon obsługuje każdy przyszły start. project.name w strukturze jest wartością zastępczą; nadpisz ją dla każdego klienta przy tworzeniu instancji. Struktura jest walidowana po stronie serwera wobec schematu dla jej zadeklarowanej wersji, a naruszenie wskazuje winny JSON pointer. Zapis. |
| projectTemplates_update | Zaktualizuj szablon projektu po id. Kolumna structure jest przechowywana i zastępowana W CAŁOŚCI, nigdy scalana — wyślij kompletny dokument, inaczej pominięte części znikną. Odczytaj najpierw bieżący za pomocą projectTemplates_get. Zmiana szablonu NIE dotyka projektów już z niego utworzonych; nie ma propagacji wstecznej. Zapis. |
| projectTemplates_delete | Usuń szablon projektu po id. Usuwanie miękkie (soft delete), które NIE dotyka projektów już utworzonych z tego szablonu — te pozostają zwykłymi projektami i żyją dalej. Zapis. |
| projectTemplates_instantiate | Zbuduj rzeczywisty projekt z szablonu — projekt, jego fazy, listy zadań i każde zadanie, w JEDNYM atomowym wywołaniu. startDate jest wymagana i stanowi punkt odniesienia, wobec którego rozwiązywane jest każde startOffsetDays w szablonie. Przekaż name, by nadpisać zastępczą nazwę projektu z szablonu, oraz client, by przypisać nowy projekt do klienta: dwukrotne utworzenie instancji dla TEGO SAMEGO klienta to sposób, w jaki jeden klient kończy z kilkoma zleceniami, każde jako osobny projekt. Zwraca utworzony projekt. Zapis. |
Kandydaci zapotrzebowań na zasoby
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourceRequestCandidates_get | Jeden kandydat rekrutacyjny po id. Id pochodzi z resourceRequestCandidates_list. Wymaga ROLE_HR_MANAGER. Tylko do odczytu. |
| resourceRequestCandidates_list | Kandydaci zgłoszeni na zapotrzebowania rekrutacyjne — osoby w lejku rekrutacyjnym, a nie pracownicy dostępni do alokacji. Filtruj po id zapotrzebowania z resourceRequests_list. Wymaga ROLE_HR_MANAGER. Tylko do odczytu. |
Zapytania o zasoby
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourceRequests_get | Jedno zapotrzebowanie rekrutacyjne po id, ze stanowiskiem i statusem. Pobierz id z resourceRequests_list. Dotyczy HR/rekrutacji, a nie alokacji zasobowej. Wymaga ROLE_HR_MANAGER. Tylko do odczytu. |
| resourceRequests_list | Otwarte zapotrzebowania rekrutacyjne — prośba o rekrutację na stanowisko, w domenie HR. Mimo nazwy NIE jest to zapotrzebowanie na alokację zasobową: to rekrutacja. Zwraca kolekcję; resourceRequests_get odczytuje jedno, a resourceRequestCandidates_list podaje osoby zgłoszone na nie. Wymaga ROLE_HR_MANAGER. Tylko do odczytu. |
Wnioski o planowanie zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourcingRequests_list | Otwarte zapotrzebowania zasobowe — ktoś prosi o alokację osoby do projektu, czyli strona popytowa resourcingu. To przepływ renderowany przez widok Requests w interfejsie Resourcing. NIE myl tego z resourceRequests_list: to jest REKRUTACJA HR (zatrudnienie na stanowisko). Zestaw to z resourcingRequestsHistory_list, aby zobaczyć, co już zdecydowano, oraz z resourcingBench_get, aby zobaczyć, kto mógłby zaspokoić zapotrzebowanie. Wymaga modułu resourcing i ROLE_RESOURCING_MANAGER. Tylko do odczytu. |
Historia wniosków o planowanie zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourcingRequestsHistory_list | Co już stało się z zapotrzebowaniami zasobowymi — ślad decyzji (potwierdzone, odrzucone, zmienione) stojący za otwartymi zapotrzebowaniami z resourcingRequests_list. Sięgnij po to, aby odpowiedzieć na pytanie „czy o to już proszono i odrzucono?”, zanim ponownie zaproponujesz tę samą alokację. Wymaga modułu resourcing i ROLE_RESOURCING_MANAGER. Tylko do odczytu. |
Odpowiedzialności
Narzędzia
| Narzędzie | Opis |
|---|---|
| responsibilities_get | Pobierz jedną odpowiedzialność po id. |
| responsibilities_list | Wylistuj odpowiedzialności w ramach grupy RACI. Filtruj po responsibilityGroup. Odpowiedzialności mogą się zagnieżdżać poprzez parent; osoby są do nich przypisywane przez responsibilityEmployees, a nie bezpośrednio. |
| responsibilities_create | Tworzy odpowiedzialność wewnątrz grupy (responsibilityGroup = id grupy lub IRI, + name, wymagane; opcjonalne description; opcjonalne parent = IRI innej odpowiedzialności do zagnieżdżenia). Przypisuj do niej osoby za pomocą responsibilityEmployees_create. Zapis. |
| responsibilities_update | Zaktualizuj odpowiedzialność po id (name, description, parent, responsibilityGroup = id grupy lub IRI). Zapis. |
Pracownicy odpowiedzialności
Narzędzia
| Narzędzie | Opis |
|---|---|
| responsibilityEmployees_get | Pobierz jedno przypisanie odpowiedzialności po id. |
| responsibilityEmployees_list | Wylistuj, kto jest przypisany do jakiej odpowiedzialności i w jakim procencie. Filtruj po employee, aby odczytać całe obciążenie RACI jednej osoby we wszystkich grupach. |
| responsibilityEmployees_create | Przypisz pracownika do odpowiedzialności (wymagane responsibility = id odpowiedzialności lub IRI, employee = id pracownika lub IRI, percentage 0-100; opcjonalnie targets i description). Zapis. |
| responsibilityEmployees_update | Zaktualizuj przypisanie odpowiedzialności po id (percentage, targets, description). Zapis. |
| responsibilityEmployees_delete | Usuń przypisanie pracownika do odpowiedzialności po id. Zapis. |
Grupy odpowiedzialności
Narzędzia
| Narzędzie | Opis |
|---|---|
| responsibilityGroups_get | Pobierz jedną grupę odpowiedzialności po id. |
| responsibilityGroups_list | Wylistuj grupy odpowiedzialności / obszary RACI — pozycje najwyższego poziomu „Odpowiedzialności”, każda z osobą odpowiedzialną (accountable). Pojedyncze odpowiedzialności znajdują się pod nimi. |
| responsibilityGroups_create | Tworzy grupę odpowiedzialności / obszar RACI (wymagane name; opcjonalne description i responsibleEmployee = osoba odpowiedzialna, podana jako zwykłe id pracownika, np. 6 (z people_list), lub IRI /people/6). To pozycja najwyższego poziomu 'Odpowiedzialności'. Dodawaj pod nią poszczególne odpowiedzialności za pomocą responsibilities_create. Zapis. |
| responsibilityGroups_update | Zaktualizuj grupę odpowiedzialności po id (name, description, responsibleEmployee = id pracownika lub IRI). Zapis. |
Pracownicy harmonogramu
Narzędzia
| Narzędzie | Opis |
|---|---|
| scheduleEmployees_get | Jedno przypisanie harmonogramu do pracownika po id. Id pochodzi z scheduleEmployees_list. Wymaga ROLE_SCHEDULES_MANAGER. Tylko do odczytu. |
| scheduleEmployees_list | Którzy pracownicy są przypisani do których harmonogramów czasu pracy. Użyj tego, aby przejść od harmonogramu (schedules_list) do jego osób, lub aby znaleźć harmonogram, którego przestrzega dany pracownik. Wymaga ROLE_SCHEDULES_MANAGER. Tylko do odczytu. |
Plan harmonogramu
Narzędzia
| Narzędzie | Opis |
|---|---|
| schedulePlan_list | Harmonogramy obowiązujące w JEDNYM podanym dniu — przekaż datę w ścieżce. Sięgnij po to, aby odpowiedzieć na pytanie „kto pracuje dziś / w tym dniu” bez odczytywania każdego harmonogramu i samodzielnego rozwiązywania jego zakresów. W przeciwieństwie do innych odczytów harmonogramów wymaga to tylko ROLE_USER, więc jest to endpoint dostępny dla zwykłego pracownika. Tylko do odczytu. |
Zakresy harmonogramu
Narzędzia
| Narzędzie | Opis |
|---|---|
| scheduleRanges_get | Jeden zakres czasowy harmonogramu po id. Id pochodzi z scheduleRanges_list. Wymaga ROLE_SCHEDULES_MANAGER. Tylko do odczytu. |
| scheduleRanges_list | Zakresy czasowe składające się na harmonogramy czasu pracy — rzeczywiste godziny, jakie obejmuje harmonogram. Najpierw odczytaj rekord nadrzędny za pomocą schedules_get; ten endpoint rozwija jego zakresy. Wymaga ROLE_SCHEDULES_MANAGER. Tylko do odczytu. |
Harmonogramy
Narzędzia
| Narzędzie | Opis |
|---|---|
| schedules_get | Jeden harmonogram czasu pracy po id, z jego zakresami i przypisanymi pracownikami. Id pochodzi z schedules_list; scheduleRanges_list i scheduleEmployees_list odczytują jego części. Wymaga ROLE_SCHEDULES_MANAGER. Tylko do odczytu. |
| schedules_list | Harmonogramy czasu pracy — wzorce zmian/pracy definiowane przez organizację, a NIE alokacja projektowa. Użyj resourcingSchedule_get, aby sprawdzić, kto na czym jest zarezerwowany; tego endpointu użyj dla samych wzorców pracy. schedules_get odczytuje jeden po id. Wymaga ROLE_SCHEDULES_MANAGER. Tylko do odczytu. |
Etapy
Narzędzia
| Narzędzie | Opis |
|---|---|
| stages_get | Pobierz jeden etap szansy sprzedaży po id. |
| stages_list | Listuje w kolejności etapy szans sprzedaży. Filtruj po pipeline. deals_create wymaga id etapu stąd, a przenoszenie szansy sprzedaży między etapami jest tym, co rejestruje dealStageHistories. |
Dostawcy
Narzędzia
| Narzędzie | Opis |
|---|---|
| suppliers_list | Wylistuj dostawców/kontrahentów — obsługiwane z /contractors, więc „supplier” i „contractor” to ten sam rekord. Filtruj po cyclic dla dostawców cyklicznych. Użyj tego, aby ustalić dostawcę, wobec którego zarejestrowany jest koszt, umowa lub faktura przychodząca. |
| suppliers_create | Utwórz nowy rekord dostawcy/kontrahenta (wymagane name, tinType, costGroup). Zapis. |
| suppliers_update | Zaktualizuj dane dostawcy/kontrahenta (name, identyfikator podatkowy, warunki płatności itd.) po id. Zapis. |
Definicje tagów
Narzędzia
| Narzędzie | Opis |
|---|---|
| tagDefinitions_list | Listuje definicje tagów — tagi, które można dołączyć do rekordów, każdy w ramach grupy tagów. tags_create przyjmuje stąd id tagDefinition oraz rekord, do którego ma zostać dołączony. |
| tagDefinitions_create | Tworzy definicję tagu (wymagane name, level, tagGroup) w obrębie grupy tagów. Gdy allowedRelations grupy zawiera "project", każda definicja tutaj JEST folderem projektów — to narzędzie, którym się go tworzy. Zapis. |
Grupy tagów
Narzędzia
| Narzędzie | Opis |
|---|---|
| tagGroups_list | Wylistuj grupy tagów — kontenery porządkujące definicje tagów. |
| tagGroups_create | Tworzy grupę tagów (wymagana nazwa), aby uporządkować powiązane definicje tagów. Tak też tworzy się kontener FOLDERU PROJEKTÓW: podaj allowedRelations: ["project"], a definicje tej grupy staną się folderami na liście projektów. Grupa z pustym allowedRelations jest uniwersalna i NIE jest traktowana jako folder. Zapis. |
Komentarze do zadań
Narzędzia
| Narzędzie | Opis |
|---|---|
| taskComments_list | Wylistuj komentarze do zadań projektowych, od najstarszych. Filtruj po task, aby odczytać dyskusję jednego zadania. |
| taskComments_create | Dodaj komentarz do zadania projektowego (id zadania + content). Zapis. |
Listy zadań
Narzędzia
| Narzędzie | Opis |
|---|---|
| taskLists_list | Listuje listy zadań — kolumny/sekcje tablicy, do których trafiają zadania. Filtruj po project. tasks_create przyjmuje stąd id listy. |
Zadania
Narzędzia
| Narzędzie | Opis |
|---|---|
| tasks_get | Pobierz jedno zadanie projektowe po id — tytuł, projekt, status, lista, przypisane osoby, daty i powtarzalność. |
| tasks_list | Listuje zadania projektowe. Filtruj po project, list, status, assignees, isTemplate lub zakresach startAt/dueAt. Zadania cykliczne udostępniają recurrenceParent i recurrenceRule, więc wygenerowane wystąpienie można prześledzić do reguły, która je utworzyła. Aby ustalić, czy zadanie jest ZAKOŃCZONE, porównaj jego status z taskStatuses_list (isClosed), zamiast dopasowywać po nazwie statusu. |
| tasks_create | Utwórz zadanie projektowe (wymagane title + project; opcjonalnie status, list, assignees, dueAt, priority). Zapis. |
| tasks_update | Zaktualizuj zadanie projektu po id — zmień status (w tym oznacz jako wykonane), assignees, dueAt, title itd., lub PRZENIEŚ zadanie do innego projektu, przekazując `project` (zmiana rodzica; lista zadań jest czyszczona, chyba że wskażesz też `list` w projekcie docelowym, ponieważ lista należy do jednego projektu). Zapis. |
Statusy zadań
Narzędzia
| Narzędzie | Opis |
|---|---|
| taskStatuses_list | Wylistuj statusy zadań projektowych, w kolejności na tablicy. isClosed oznacza stany zakończone, a isDefault status nadawany nowemu zadaniu. Przeczytaj to przed interpretacją statusu zadania — nazwy są konfigurowalne przez organizację, więc „Done” nie jest ciągiem, na którym można polegać przy dopasowywaniu. |
Grupy podatkowe
Narzędzia
| Narzędzie | Opis |
|---|---|
| taxGroups_list | Listuje grupy podatkowe. Użyj tego, aby rozwiązać id taxGroup, po którym filtruje taxRules_list i który niosą wiersze faktury. |
| taxGroups_create | Utwórz grupę podatkową (wymagane name + type). Zapis. |
| taxGroups_update | Zaktualizuj nazwę lub typ grupy podatkowej po id. Zapis. |
Reguły podatkowe
Narzędzia
| Narzędzie | Opis |
|---|---|
| taxRules_list | Wylistuj reguły podatkowe — stawki i okresy, których dotyczą. Filtruj po taxGroup. |
| taxRules_create | Utwórz regułę podatkową. Zapis. |
| taxRules_update | Zaktualizuj regułę podatkową po id. Zapis. |
Transakcje
Narzędzia
| Narzędzie | Opis |
|---|---|
| transactions_list | Wylistuj transakcje bankowe — strumień bankowy, z którym dopasowywane są faktury przychodzące. Filtruj po bankAccount, counterpartyRole, cost, ignored, hasDetectedProblems, zakresie orderDate/execDate lub amount.between. Zwróć uwagę, że orderDate i execDate to różne pola: płatność może zostać zlecona w jednym miesiącu, a zrealizowana w kolejnym. |
| transactions_suggestions | Odczytuje propozycje Flowtly dla jednej transakcji bankowej — do jakiego kontrahenta, grupy kosztów lub dokumentu powinna zostać przypisana. Lustrzane odbicie incomingInvoices_suggestions, od strony pieniędzy. |
| transactions_importStatement | Importuje plik wyciągu bankowego (np. plik MT940 .sta) — przekaż surową treść tekstową każdego pliku dosłownie (NIE base64) wraz z nazwą pliku. NIE MA PARAMETRU bankAccount: backend kieruje plik, usuwając wszystkie znaki niebędące cyframi z numerów twoich kont bankowych oraz z bajtów pliku, i importuje do każdego konta, którego cyfry pojawiają się gdziekolwiek w pliku — więc jeden plik może trafić na kilka kont, a wyciąg dla konta, które nie jest skonfigurowane w Flowtly (lub którego numer jest zapisany inaczej, niż zapisuje go bank), nie importuje się na żadne z nich, kończąc się błędem, który dokładnie wyjaśnia dlaczego — odczytaj tę wiadomość, to jedyna diagnostyka, jaką daje ten endpoint. Przy sukcesie odpowiedź to `{ imported, matching }`: `matching: "in_progress"` oznacza, że dopasowywanie kontrahenta/załącznika dla nowych wierszy nadal trwa po zwróceniu odpowiedzi przez to wywołanie, więc natychmiastowe transactions_list może pokazywać wiersze jeszcze niedopasowane — odczytaj ponownie nieco później, aby uzyskać stan końcowy. Ponowny import tego samego wyciągu nie tworzy duplikatów wierszy; importer rozpoznaje transakcje, które już widział. Gdy wyciąg jest już w systemie, wskaż istniejącą płatność bez linii bankowej na jeden z jego wierszy za pomocą invoiceTransactions_update. Zapis. |
| transactions_delete | Usuwa transakcję bankową po id — znajdziesz ją przez transactions_list. Sięgaj po to WYŁĄCZNIE, aby cofnąć błąd księgowy, którego nie da się poprawić inaczej: wyciąg zaimportowany na niewłaściwe konto bankowe albo wiersze wprowadzone ręcznie przed nadejściem prawdziwego wyciągu i teraz przez niego zdublowane. Transakcja jest zapisem tego, co zrobił bank, więc usunięcie jej na koncie importowanym sprawia, że księgi przestają zgadzać się z bankiem; backend pozwala na to tylko dla ROLE_ADMIN (menedżer transakcji może usuwać jedynie na kontach gotówkowych i ręcznych). ZANIM usuniesz podejrzany duplikat, udowodnij parę: dopasuj zaimportowany wiersz po kwocie ORAZ numerze faktury ORAZ kontrahencie, nie po samej kwocie — wpłata, która przyszła po dacie końca wyciągu, nie ma odpowiednika, a jej usunięcie niszczy jedyny ślad tego przychodu. Backend ODPINA, a nie usuwa to, co na niej wisi: płatności faktur zostają z wyczyszczoną linią bankową (przepnij je przez invoiceTransactions_update), załączniki i nieruchomości są odłączane, natomiast wiersze transakcji projektowych i pracowniczych znikają razem z nią. Nieodwracalne, o dużym wpływie. Zapis. |
Czasy pracy
Narzędzia
| Narzędzie | Opis |
|---|---|
| workTimes_get | Pobierz jeden wpis czasu pracy po id — data, minuty, projekt, notatki oraz pracownik, do którego należy. |
| workTimes_list | Wylistuj wpisy czasu pracy (zarejestrowanych godzin). Filtruj po zakresie dat (date.after / date.before, YYYY-MM-DD) oraz opcjonalnie po employee lub project; stronicuj za pomocą cursor. Każdy wiersz niesie employeeId/employeeName oraz projectId/projectName, więc w ten sposób eksportujesz wszystkie zarejestrowane godziny za dany okres. WAŻNE: wyniki obejmujące całą organizację wymagają ROLE_WORKING_HOURS_VIEWER. Bez tej roli backend NIE zwraca błędu — po cichu zwraca tylko wpisy połączonego użytkownika, więc eksport „godzin wszystkich” może wrócić z zawartością jednej osoby i wyglądać zupełnie poprawnie. Jeśli każdy wiersz należy do jednego pracownika, a nie filtrowałeś po employee, odpowiedź niesie scopeWarning informujący o tym — pokaż to użytkownikowi, zamiast prezentować wynik jako obejmujący całą organizację. |
| workTimes_log | Zarejestruj wpis czasu pracy dla połączonego użytkownika Flowtly (date, durationMinutes, project, notes). NOTATKA MUSI PRZEJŚĆ SERWEROWĄ KONTROLĘ ZBYT KRÓTKIEGO OPISU, na którą powtarzalnie trafia masowe uzupełnianie historii: potrzeba ALBO około 32 znaków (dokładny próg jest ustawieniem per organizacja, a organizacja może ustawić go na 0, wyłączając kontrolę), ALBO odniesienia do zgłoszenia w postaci "#", ALBO linku http(s) — wystarczy jedno z nich. "Flowtly – Scallier" zostanie odrzucone; "Flowtly – Scallier #FLOW-123" już nie. Błąd 422 wskazuje propertyPath `description`, czyli nazwę tego pola po stronie serwera, które to narzędzie nazywa `notes`. Zapis. |
| workTimes_update | Popraw jeden zarejestrowany wpis czasu pracy po id — jego date, minutes, project lub description. Tak właśnie błędnie przypisany wpis zostaje PRZENIESIONY między projektami: workTimes_log wyłącznie tworzy, więc bez tego narzędzia zły projekt lub literówka w opisie są trwałe. Odczytaj najpierw wpis za pomocą workTimes_get. Obowiązuje ta sama kontrola zbyt krótkiego opisu, co przy workTimes_log: mniej więcej 32 znaki — dokładny próg jest ustawieniem per organizacja i może wynosić 0, co ją wyłącza — LUB odniesienie do zgłoszenia w postaci "#", LUB link http(s), wystarczy jedno z trzech. Zapis. |
| workTimes_delete | Usuń jeden zarejestrowany wpis czasu pracy po id. Dla duplikatu lub wpisu zarejestrowanego wobec pracy, która nigdy się nie odbyła — preferuj workTimes_update, gdy wpis jest prawdziwy, lecz błędny, tak by godziny pozostały w rekordzie, zamiast z niego zniknąć. Zarejestrowane godziny zasilają finanse projektu i wykorzystanie zasobów, więc usunięcie po cichu zmienia raportowane liczby dla minionego okresu. Zapis. |
Kontakty klientów
Narzędzia
| Narzędzie | Opis |
|---|---|
| clientContacts_create | Utwórz osobę kontaktową dla klienta (wymagane client, type, name, email). Zapis. |
Konta bankowe kontrahentów
Narzędzia
| Narzędzie | Opis |
|---|---|
| counterpartyBankAccounts_create | Dołącz konto bankowe do kontrahenta (counterparty + accountNumber). Zapis. |
Pozycje harmonogramu płatności
Narzędzia
| Narzędzie | Opis |
|---|---|
| paymentScheduleLines_import | Wczytaj cały harmonogram rat kontraktu w jednym wywołaniu, zamiast jednego zapytania na pozycję. Zbudowane z myślą o kontraktach deweloperskich, które są opłacane w transzach budowlanych — pojedyncza sprzedaż to od sześciu do dwunastu rat, a rejestr takich pozycji to setki wpisów. Każdy wiersz wskazuje swój kontrakt PO NAZWIE (dla zaimportowanego kontraktu deweloperskiego — po numerze umowy), datę płatności oraz kwotę w JEDNOSTKACH POMOCNICZYCH — w groszach, więc 5 300,00 to "530000", a "5300" po cichu zaksięguje 53,00. Wiersze są uzgadniane wobec pozycji już tam obecnych po contract+date+amount+note, więc nieznana pozycja jest tworzona, identyczna jest pomijana, a ponowne uruchomienie tej samej partii niczego nie zmienia; PaymentScheduleLine nie ma kolumny referencji zewnętrznej, więc ten naturalny klucz jest kluczem uzgadniania. Wiersz, którego nazwa kontraktu niczego nie dopasowuje lub dopasowuje WIĘCEJ niż jeden kontrakt, jest zgłaszany jako nieudany, a nie dołączany na podstawie domysłu — umieszczenie raty na złym kontrakcie zniekształca od razu dwa przepływy gotówkowe. Przekaż najpierw dryRun:true przy prawdziwym wczytywaniu. Maksymalnie 1000 wierszy. Zapis. |
| paymentScheduleLines_create | Dodaj jedną ratę do harmonogramu płatności kontraktu — planu tego, co ma zostać zafakturowane lub opłacone, i kiedy. Przekaż IRI kontraktu, datę i kwotę. To właśnie usuwa problem brakującego harmonogramu płatności, który contracts_get zgłasza dla kontraktu niecyklicznego: jednorazowa opłata też ma harmonogram, po prostu jest to pojedyncza pozycja na całą kwotę w dniu, w którym przypada termin. Kontrakty cykliczne nie są pod tym kątem sprawdzane, ponieważ system nie generuje automatycznie pozycji z cykliczności. KWOTA JEST W JEDNOSTKACH POMOCNICZYCH — w groszach, nie w złotych: 5 300,00 to "530000", a "5300" po cichu zaksięguje pozycję 53,00. API zwraca je w ten sam sposób, więc jeśli nie jesteś pewny skali, odczytaj wynik z powrotem za pomocą contracts_paymentScheduleLines. Odczytaj wynik z powrotem za pomocą contracts_paymentScheduleLines. Zapis. |
| paymentScheduleLines_update | Zmień jedną pozycję harmonogramu płatności po id — jej date, amount lub note. Użyj tego, gdy rata się przesuwa lub jest renegocjowana, zamiast usuwać i tworzyć od nowa, tak by pozycja zachowała każdą fakturę już z nią dopasowaną. KWOTA JEST W JEDNOSTKACH POMOCNICZYCH — w groszach, nie w złotych: 5 300,00 to "530000", a "5300" po cichu zaksięguje pozycję 53,00. API zwraca je w ten sam sposób, więc jeśli nie jesteś pewny skali, odczytaj wynik z powrotem za pomocą contracts_paymentScheduleLines. Zapis. |
| paymentScheduleLines_delete | Usuń jedną pozycję harmonogramu płatności po id. Usuwa PLAN, nie pieniądze: faktura lub transakcja już dopasowana do pozycji nie jest naruszona, ale przestaje być z czymkolwiek uzgadniana. Dla raty, która się przesunęła, preferuj paymentScheduleLines_update. Zapis. |
Logo organizacji
Narzędzia
| Narzędzie | Opis |
|---|---|
| organizationLogo_upload | Przesyła/zastępuje logo organizacji (obraz base64 + contentType + filename). Odczytaj bieżące przez configs_get organization-logo-url. Zapis. |
Ikona organizacji
Narzędzia
| Narzędzie | Opis |
|---|---|
| organizationIcon_upload | Przesyła/zastępuje ikonę/favicon organizacji (obraz base64 + contentType + filename). Odczytaj bieżącą przez configs_get organization-icon-url. Zapis. |
Storage
Narzędzia
| Narzędzie | Opis |
|---|---|
| storage_upload | Dołącz plik do dowolnego rekordu akceptowanego przez generyczny storage Flowtly — ZASOBU (relationName "property"), projektu, zadania, klienta, lokalizacji, kontrahenta, faktury. To jedyna droga do ZDJĘCIA zasobu: przesłanie pliku z relationName "property" ustawia obraz, jaki aplikacja pokazuje dla tego zasobu (podawany jako `file` w danych zasobu). Property nie ma kolumny obrazu -- zdjęcie jest wyprowadzane z tej tabeli w momencie odczytu, dlatego nic w encji nie sugeruje, że istnieje. Jest to JEDNO miejsce i wygrywa najnowsze przesłanie, więc drugi obraz zastępuje pierwszy, zamiast dołączać się do galerii. To samo dotyczy location, invoices i transaction-attachments; clients, agreements i candidates zamiast tego kumulują każde przesłanie pod `files`. KAŻDA INNA RELACJA NIE WIĄŻE PRZESŁANEGO PLIKU Z NICZYM WIDOCZNYM, a relationName "employees" to ta, z którą trzeba uważać: zapisuje bajty i NIE tworzy Document, więc Ludzie > Dokumenty pozostaje puste, a dane pracownika nie zawierają żadnego pliku. Trasa /documents na dowolnym rekordzie zwraca encje Document, a przesłanie pliku żadnej nie tworzy. Prawdziwy dokument pracownika wymaga POST /documents z DocumentType, którego relationName to `employee`, id pracownika oraz IRI wiersza Storage zwróconego przez to wywołanie. NIE SKŁADAJ TEGO RĘCZNIE: użyj employeeDocuments_createUploadTicket, które wykonuje wszystkie trzy kroki — zapisuje bajty, tworzy Document i odczytuje go z powrotem przez /people/{id}/documents — oraz raportuje osobno stored / linked / verified. To narzędzie kończy na bajtach. Nie sięgaj też po agreementTypes.*: AgreementType to typ UMOWY o zatrudnienie (Umowa o pracę, Umowa zlecenie) w sekcji Ludzie > Umowy i nie jest DocumentType. Raportuj zapisanie bajtów, powiązanie z rekordem biznesowym i zweryfikowanie widoczności jako trzy osobne twierdzenia i potwierdzaj tylko te, które faktycznie wykonałeś. `file` jest pomijane w odpowiedziach LIST, chyba że żądanie przekaże ?include=file, więc odczytaj rekord z powrotem, by potwierdzić, że zdjęcie się zapisało. Przekaż relationName + relationId (id z narzędzia listującego tego rekordu; IRI /assets/7 jest akceptowane i redukowane) plus bajty jako base64 z contentType i filename. LIMIT ROZMIARU: bajty podróżują jako base64 wewnątrz tego wywołania, więc utrzymaj je poniżej ok. 150 KB — zdjęcia prawie zawsze przekraczają ten próg, a dla nich użyj storage_createUploadTicket, które nie ma pułapu. Uprawnienia to te, których wymaga edycja rekordu BĘDĄCEGO WŁAŚCICIELEM: backend rozwiązuje relationName do tej encji i pyta jej własny voter, więc dołączenie pliku do zasobu wymaga uprawnienia do zasobów, a do klienta — uprawnienia do klientów. Dla kontraktu użyj raczej contractAttachments_create — usuwa ono także contracts.problem_missing_document, czego to narzędzie nie robi. Zapis. |
| storage_createUploadTicket | Wygeneruj krótko żyjący, jednorazowy bilet do dołączenia DUŻEGO pliku do dowolnego rekordu — sposób, w jaki ZDJĘCIA zasobów faktycznie się dostają, ponieważ obraz zawsze przekracza pułap base64. Dla property/location/invoices/transaction-attachments najnowsze przesłanie staje się widocznym obrazem rekordu, zastępując poprzedni; dla clients/agreements/candidates przesłania się kumulują. Użyj tego zamiast storage_upload, gdy plik przekracza kilkadziesiąt KB: to narzędzie niesie bajty jako base64, które wywołujący musi wyemitować jako tekst, a 400 KB JPEG staje się ~533 tys. znaków base64, daleko poza to, co mieści się w jednej odpowiedzi. Przekaż relationName + relationId plus filename; w zamian otrzymasz uploadUrl i gotowe do uruchomienia polecenie curl. Następnie wyślij SUROWE BAJTY pliku na ten URL (curl --data-binary @photo.jpg) — nie base64, nie multipart — a odpowiedź poniesie utworzony rekord Storage. Bilet wygasa po 15 minutach, działa jednorazowo i może dołączyć plik wyłącznie do jednego wskazanego rekordu. Zapis. |
Załączniki umów
Narzędzia
| Narzędzie | Opis |
|---|---|
| contractAttachments_create | Dołącz dokument do kontraktu — zwykle podpisany PDF lub aneks (DPA, SLA, aneks cenowy) zarchiwizowany razem z nim. Przekaż bajty jako base64 z fileName oraz id kontraktu z contracts_list; `contractId` jest tu GOŁYM id, w przeciwieństwie do IRI, których contracts_update oczekuje dla counterparty i project, choć pełne IRI /contracts/<id> jest akceptowane i redukowane. LIMIT ROZMIARU: bajty podróżują jako base64 wewnątrz tego wywołania, więc cały dokument musi zmieścić się w jednej odpowiedzi modelu — utrzymaj go poniżej ok. 150 KB, a dla czegokolwiek większego użyj zamiast tego contractAttachments_createUploadTicket, zbudowanego dokładnie do tego celu i bez takiego pułapu. Podpisany kontrakt z kartą podpisu zwykle znacznie to przekracza (673 617 bajtów staje się 898 156 znakami base64, kilkukrotnie więcej, niż może unieść jedna odpowiedź), a gdy się nie zmieści, nie wraca żaden błąd, ponieważ wywołanie w ogóle nie może zostać wyemitowane — żądanie nigdy nie dociera do serwera, więc sprawdź rozmiar pliku ZANIM zaczniesz, zamiast odkrywać to przez niepowodzenie. To właśnie usuwa problem brakującego dokumentu, który zgłasza contracts_get, więc kontrakt utrzymywany przez API przestaje tkwić w kolejce porządkowej aplikacji. Jeden podpisany dokument może obsłużyć kilka wierszy kontraktu (umowa z częścią cykliczną i jednorazową to dwa wiersze, ponieważ `cyclic` jest ustawiane per rekord) — wywołaj to raz dla każdego id kontraktu z tymi samymi bajtami. To, co dzieje się dalej, zależy od kind. kind "contract": `status` wraca jako "analyzing", a backend odczytuje dokument asynchronicznie, zwykle w ciągu kilku minut; odpytuj contracts_get, aż załącznik będzie "analyzed" lub "failed" (niepowodzenie niesie failureReason i failureRetryable). Odczyt jedynie WYPEŁNIA PUSTE pola kontraktu i nigdy nie nadpisuje nazwy, kierunku, kwoty, dat, waluty, warunków płatności, pozycji harmonogramu ani cen już na nim obecnych; każda wyodrębniona wartość pozostaje w analysisSummary załącznika, a analysisSummary.notApplied wymienia to, co zostało pozostawione jako sugestia. kind "annex": zapisywany i NIE analizowany; `status` to "stored", co jest stanem końcowym, a kontrakt się nie zmienia. Traktuj analysisSummary jako SUGESTIĘ do sprawdzenia, a nie fakt, któremu można ufać. Zapis. |
| contractAttachments_createUploadTicket | Wygeneruj krótko żyjący, jednorazowy bilet do dołączenia DUŻEGO dokumentu do kontraktu — podpisanego PDF-a lub aneksu. Użyj tego zamiast contractAttachments_create, gdy plik przekracza kilkadziesiąt KB: to narzędzie niesie bajty jako base64, które wywołujący musi wyemitować jako tekst, a prawdziwy podpisany kontrakt (~700 KB, ~900 tys. znaków base64) jest daleko poza to, co mieści się w jednej odpowiedzi. Przekaż id kontraktu z contracts_list plus fileName; w zamian otrzymasz uploadUrl i gotowe do uruchomienia polecenie curl. Następnie wyślij SUROWE BAJTY pliku na ten URL (curl --data-binary @file.pdf) — nie base64, nie multipart — a odpowiedź to utworzony załącznik. Bilet wygasa po 15 minutach, działa jednorazowo i może dołączyć plik wyłącznie do jednego wskazanego kontraktu. To właśnie usuwa problem brakującego dokumentu, który zgłasza contracts_get. Zapis. |
Transakcje faktur
Narzędzia
| Narzędzie | Opis |
|---|---|
| invoiceTransactions_create | Rejestruje płatność dla faktury wychodzącej (sprzedażowej). `invoice` to IRI faktury z invoices_list; `date` to data, w której płatność jest traktowana jako dokonana. `transaction` jest opcjonalne — pomiń je, aby zarejestrować rozliczenie bez linii bankowej, co jest właściwe dla historycznych faktur, których wyciąg bankowy nigdy nie został zaimportowany. `amount` jest opcjonalne i domyślnie przyjmuje pozostałą do zapłaty kwotę faktury. Zarejestrowanie płatności to sposób na to, aby wystawiona, przeterminowana faktura przestała być traktowana jako niezapłacona, a więc również na to, aby przestały być dla niej kolejkowane przypomnienia o płatności. Nic nie zapobiega zarejestrowaniu dwóch płatności dla jednej faktury, więc jeśli nie masz pewności, czy jest już rozliczona, najpierw odczytaj invoices_get. Zapis. |
| invoiceTransactions_update | Aktualizuje istniejący rekord płatności faktury po id (z invoiceTransactions w invoices_get lub przez stronicowanie invoiceTransactions). Najczęstsze użycie: wskazanie płatności zarejestrowanej bez linii bankowej na transakcję właśnie zaimportowaną przez transactions_importStatement, poprzez ustawienie `transaction` na IRI/id transakcji z transactions_list. PUŁAPKA: to PATCH, ale backend nadal wymaga `invoice` i `date` przy każdym wywołaniu — NIE scala za ciebie istniejących wartości. Najpierw odczytaj rekord (lub miej go już z wywołania create) i wyślij ponownie niezmienione `invoice` i `date` obok tego, co faktycznie chcesz zmienić, inaczej aktualizacja zostanie odrzucona. `transaction` akceptuje null, aby odłączyć płatność od linii bankowej. `amount` jest opcjonalne. Zapis. |
| invoiceTransactions_delete | Usuwa zapis płatności z faktury po id — identyfikatory odczytasz z invoiceTransactions w invoices_get. Kasuje ZAPIS O TYM, ŻE FAKTURA ZOSTAŁA OPŁACONA, a nie transakcję bankową: użyj, gdy faktura niesie płatność, która nigdy nie powinna powstać, najczęściej gdy tę samą wpłatę zaksięgowano dwa razy — raz ręcznie, raz przez import wyciągu, który później ją dopasował. Sprawdź najpierw invoices_get i usuń ten zapis, którego `transaction` jest błędna (zostaw ten wskazujący na prawdziwą zaimportowaną linię bankową); usunięcie ostatniej płatności czyni fakturę ponownie nieopłaconą, co znów uruchamia dla niej przypomnienia o płatności. Wymaga ROLE_INVOICES_MANAGER. Nieodwracalne, o dużym wpływie. Zapis. |
Planowanie zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourcing_importTimeline | Importuje arkusz osi czasu alokacji zasobowych (pobierz go przez Drive MCP, przekaż jego CSV dosłownie). To PEŁNE ZASTĄPIENIE wierszy Allocation organizacji dla `year`: wiersze z arkusza są tworzone/aktualizowane, a każdy istniejący wiersz dla tego roku, nieobecny w arkuszu, zostaje USUNIĘTY — to nie scalenie. DOMYŚLNIE PRÓBA NA SUCHO: pominięte dryRun podglądowo nic nie zapisuje; przekaż dryRun:false, aby zastosować zmiany. Raport podaje `created` / `replaced` oraz `unmatchedPeople` / `unmatchedProjects`. DWIE RZECZY ŁATWO PRZEOCZYĆ: wiersz arkusza, którego projekt się nie rozwiązuje, jest POMIJANY, a wywołanie mimo to zgłasza sukces, więc pozytywny wynik może ukrywać częściowy import; a kod roli, którego katalog stanowisk jeszcze nie zawiera, jest TWORZONY jako nowe stanowisko zamiast odrzucony — zobacz `createdPositions`. Oba przypadki są sygnalizowane w `warnings`, gdy wystąpią; przekaż to użytkownikowi zamiast zgłaszać tylko `created`. Arkusz, który parsuje się do zera wierszy, jest odrzucany (wygląda dokładnie jak błędny odczyt, który za chwilę wyczyściłby całą oś czasu), chyba że przekażesz force:true. Odczytaj potem allocations_list, aby zobaczyć, co trafiło do systemu. Wysoki wpływ. Zapis. |
Organizacja
Narzędzia
| Narzędzie | Opis |
|---|---|
| organization_whoami | Zwraca organizację, do której jest przypięte to połączenie MCP — { orgId, name, slug, userId }. Wywołaj to, aby potwierdzić, do KTÓREGO tenanta zamierzasz zapisywać, przed jakimkolwiek create/update: połączenie jest przypięte do dokładnie jednej organizacji przez token, a zapisanie prospektów/rekordów do niewłaściwej organizacji to prawdziwy incydent. Tylko do odczytu. |
Dane rzeczywiste zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourcingActuals_get | Raportowane godziny w porównaniu z planem, per osoba i tydzień, w oknie from/to — odpowiada na pytanie „czy zespół faktycznie realizuje plan?”, na które NIE odpowiada żadne inne narzędzie zasobowe: alokacje mówią, co było ZAPLANOWANE, to narzędzie mówi, co zostało ZREALIZOWANE. Zwraca kolumny tygodni oraz jeden wiersz na osobę (planned %, reported %, wariancję, sumy i podział per projekt). reportedPercent równe null oznacza „brak umowy w tym tygodniu”, a 0 oznacza „umowa istniała, ale nic nie zaraportowano” — NIE utożsamiaj tych dwóch przypadków. Przekaż financials, aby uzyskać przychód/koszt/marżę, które w przeciwnym razie są pomijane. Wymaga modułu resourcing i ROLE_RESOURCING_MANAGER. Tylko do odczytu. |
Bench zasobowy
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourcingBench_get | Kto NIE jest obsadzony w oknie from/to — bench. Sięgnij po to, gdy pada pytanie, kogo przydzielić do nowego projektu lub gdzie moc przerobowa jest niewykorzystana; resourcingActuals_get mówi, jak obciążone są osoby, to narzędzie mówi, kto nie ma żadnego obciążenia. NIE WIE NIC O URLOPACH: freePercent to 100 minus potwierdzone alokacje, nic więcej, więc ktoś na trzytygodniowym zatwierdzonym urlopie pojawia się jako 100% wolny i żadne pole w odpowiedzi nie mówi inaczej. Odpowiadanie na pytanie „kto jest dostępny” wyłącznie na tej podstawie doprowadzi do przydzielenia do projektów osób, które są nieobecne — sprawdź krzyżowo holidays_active lub holidays_list. Wymaga modułu resourcing. Tylko do odczytu. |
Harmonogram zasobów
Narzędzia
| Narzędzie | Opis |
|---|---|
| resourcingSchedule_get | Planowany harmonogram zasobowy w oknie from/to — oś czasu alokacji taka, jaką pokazuje planista. Użyj go, aby zobaczyć, co jest ZAREZERWOWANE na przyszłość; użyj resourcingActuals_get, aby zobaczyć, co faktycznie zaraportowano wobec tego planu. Wymaga modułu resourcing i ROLE_RESOURCING_MANAGER. Tylko do odczytu. |