Server MCP
Connetti strumenti AI a Flowtly tramite il Model Context Protocol su mcp.flowtly.eu.
Connect
claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp
In questa pagina
Accordi
Strumenti
| agreements_get | Recupera un contratto di lavoro per id — type, variant, l'intervallo dateFrom/dateTo, hoursPerWeek, e i campi derivati `calculable`, `active` e `status`. agreements_list fornisce l'id. Richiede ROLE_AGREEMENTS_MANAGER o ROLE_MEETING_MANAGER. Sola lettura. |
| agreements_list | Elenca i contratti di lavoro — filtra per employee (IRI), isActive, type o variant. IL modo per rispondere a "perché people_list dice che questa persona è inattiva": ogni riga porta `calculable` e `active`, e una persona è attiva esattamente quando ne possiede uno che è entrambi. È anche il posto dove leggere i codici `type` di contratto che questa org usa realmente prima di chiamare agreements_create, perché un'org può aggiungerne di propri. Richiede ROLE_AGREEMENTS_MANAGER o ROLE_MEETING_MANAGER. Sola lettura. |
| agreements_create | Crea un contratto di lavoro per una persona. QUESTO È IL PASSAGGIO CHE RENDE QUALCUNO ATTIVO: people_create crea solo il record, e una persona senza agreement riporta isActive false per sempre — un import massivo quindi arriva al 100% inattivo finché questo non viene eseguito per ciascuno di loro. DUE COSE DEVONO ESSERE ENTRAMBE VERE altrimenti restano inattivi senza alcun errore: il `type` deve essere CALCULABLE (i predefiniti "agreement", "annex", "termination" lo sono; "list-of-intent" e "work-experience" no), e la finestra dateFrom/dateTo deve coprire oggi (passa dateTo null per un contratto in corso invece di una data lontana nel futuro). `employee` è un IRI — /people/<id> da people_list. I type sono estendibili per org, quindi esegui agreements_list su qualcuno già attivo per vedere i codici realmente usati da questa org. Richiede ROLE_AGREEMENTS_MANAGER. Scrittura. |
| agreements_update | Modifica un contratto di lavoro esistente — il modo in cui un agreement viene TERMINATO, perché il backend non espone alcuna delete su questa risorsa: imposta `dateTo` all'ultimo giorno coperto e la persona smette di essere attiva da quel momento, con il record e la sua storia intatti. Questa è la mossa corretta per una riga adiacente alle buste paga; non c'è modo di far sparire una riga, e non dovrebbe esserci. È anche il modo per correggere un `type`, `variant` o `positionName` errato sul posto invece di accumulare un secondo agreement sulla persona — DUE agreement non si annullano a vicenda, quello calculable la mantiene attiva, quindi "aggiungerne uno corretto accanto" lascia silenziosamente in vigore quello sbagliato. `amount`, `amountType` e `billingType` sono accettati ma l'API non li restituisce mai, quindi non puoi rileggere ciò che hai scritto. Richiede ROLE_AGREEMENTS_MANAGER. Scrittura. |
Tipi di accordo
Strumenti
| agreementTypes_get | Recupera un tipo di contratto per id — il suo name o translationKey, `calculable`, `isActive`, `position` e `builtIn`. L'id È il codice, quindi questo rilegge un tipo con la stessa stringa che un agreement memorizza in `type`. Usalo per confermare che un tipo sia stato salvato dopo agreementTypes_create, e per verificare `calculable` prima di assegnarlo a qualcuno. Richiede ROLE_USER. Sola lettura. |
| agreementTypes_list | Elenca i tipi di contratto che QUESTA org può assegnare a un agreement — i valori dietro `Ludzie > <person> > Umowy > Edytuj umowę`. Leggilo prima di agreements_create o agreements_import, perché l'elenco è per-tenant: vengono forniti cinque tipi predefiniti ("agreement", "annex", "termination", "list-of-intent", "work-experience") e un'org può aggiungerne di propri, quindi un `type` valido in un'org restituisce 422 in un'altra. L'ID È IL CODICE — l'`id` di ogni riga è esattamente la stringa che `agreements_create` vuole in `type`, non una chiave numerica da consultare. `calculable` è il campo che decide se possedere questo tipo rende qualcuno ATTIVO e lo conta nel resourcing bench, nella maturazione ferie e nella base di costo; un tipo non calculable lo lascia inattivo senza alcun errore da nessuna parte, il che è voluto per un tipo come "list-of-intent" ed è un bug silenzioso se scelto per errore. Le righe `builtIn` portano una translationKey e un name nullo; le righe personalizzate portano un name reso verbatim e una translationKey nulla. Richiede ROLE_USER. Sola lettura. |
| agreementTypes_create | Aggiungi un tipo di contratto all'elenco di QUESTA org, così un agreement può essere registrato per qualcosa che i cinque predefiniti non coprono — "Umowa zlecenie", "Kontrakt B2B", "Użytkownik funkcyjny". Questa è configurazione, non una modifica di codice: l'elenco è una tabella per-tenant, e un tipo personalizzato non richiede alcuna voce di traduzione perché il suo `name` viene reso verbatim in tutte e sette le locali. NON INVIARE `id`: il codice viene generato come slug dal name lato server con i diacritici appiattiti ("Użytkownik funkcyjny" diventa "uzytkownik-funkcyjny"), e passare un id viene rifiutato con 422 "Update is not allowed for this operation". Invia il name e rileggi il codice assegnato dalla risposta. `calculable` HA DEFAULT FALSE ED È SILENZIOSO: decide chi conta come occupato — il resourcing bench, la maturazione ferie, la base di costo e di budget — quindi un tipo pensato per persone che NON devono maturare ferie o occupare un FTE è corretto a false, e un tipo pensato per un'occupazione reale DEVE impostarlo a true altrimenti chiunque lo possieda risulta inattivo senza alcun errore. Nulla ti dirà quale hai ottenuto. `position` ordina il dropdown; `isActive` ha default true. Non c'è update o delete via MCP di proposito — `agreement.type` memorizza l'id di questa riga come stringa nuda senza chiave esterna, quindi rinominare o rimuovere un tipo rende orfano ogni agreement che punta a esso. Richiede ROLE_AGREEMENTS_MANAGER. Scrittura. |
Allocazioni
Strumenti
| allocations_get | Un'allocazione per id — la prenotazione di una singola persona su un progetto, con le sue date e percentuale. allocations_list trova l'id; questo legge il record completo. Un'allocazione senza dipendente è un ruolo APERTO (domanda non coperta), non una prenotazione. Richiede il modulo resourcing. Sola lettura. |
| allocations_list | Elenca le allocazioni di resourcing — assegnazioni con intervallo di date di una posizione su un progetto a un dipendente (o a nessuno ancora, un ruolo aperto). Nessun filtro; paginazione con cursore. Ogni elemento porta employeeId/employeeName e projectId/projectName già risolti (employeeId null significa ruolo aperto); positionId è nudo — risolvi il nome tramite positions_list. source distingue le righe importate da foglio da quelle create direttamente in Flowtly. Usalo per riconciliare un import di un foglio di resourcing: rileggi cosa è arrivato e confrontalo con quanto inviato. |
Prenotazioni asset
Strumenti
| assetBookings_get | Recupera una prenotazione di asset per id — l'asset, il suo detentore, le date, e se è stata cancellata. Sola lettura. |
| assetBookings_list | Elenca le prenotazioni di asset — chi o cosa detiene attualmente ciascun asset, ovvero l'assegnazione mostrata nella schermata Assets e l'unico posto dove vive realmente un collegamento asset-persona. Ogni riga porta l'asset, il detentore (`relationName` employee | project più `relationId`), le date di inizio/fine e, una volta rilasciata, `cancelReason` e `cancelledAt`. Filtra per `property` per vedere lo storico di un asset, o per `employee` per vedere tutto ciò che una persona detiene — questo secondo caso è quello da eseguire prima che qualcuno lasci l'organizzazione. Nota che `employee` qui è l'id NUMERICO, non l'IRI /people che assetBookings_create richiede. Aggiungi `exists.cancelledAt: false` per vedere solo ciò che è ancora detenuto; senza, l'elenco include anche le prenotazioni rilasciate. Sola lettura. |
| assetBookings_create | Assegna un asset a una persona o a un progetto. `property` è l'IRI dell'asset (/assets/{id}) ed è richiesto. Indica il detentore in UNO dei tre modi: `relation` con un singolo IRI (/people/{id} per una persona, /projects/{id} per un progetto), oppure `relationName` (employee | project) più `relationId`, oppure il campo IRI `employee` / `project` direttamente. Deve risolversi esattamente un detentore — non indicarne nessuno viene rifiutato con "Employee or Project must be set." e indicarli entrambi con "Employee and Project cannot be set at the same time." DUE COSE NON PRESENTI NELLO SCHEMA CHE TI DARANNO 422: l'asset deve essere già prenotabile (`bookingAllowed: true` — impostalo con assets_update), una regola di business imposta per OGNI chiamante, incluso un manager, rifiutata con "This asset is not reservable."; e il `bookingType` proprio dell'asset (minutes | days | single-days | permanently) è ciò che dà senso a `duration` / `endDate` — uno spazio dedicato a una persona indefinitamente è `permanently` con uno `startDate` e nessuna fine. Le prenotazioni concorrenti su un asset sono serializzate lato server, quindi una sovrapposizione viene rifiutata invece di generare una doppia prenotazione. Richiede ROLE_PROPERTY_BOOKINGS_MANAGER per prenotare per conto di qualcun altro. Scrittura. |
| assetBookings_update | Aggiorna una prenotazione di asset esistente — le sue date, duration, importo/valuta di fatturazione, o quota di consumo misurato. `relationName` e `relationId` sono richiesti dal payload, quindi invia il detentore che la prenotazione ha già, a meno che tu non la stia deliberatamente spostando. Per terminare un'assegnazione usa assetBookings_cancel, non un endDate nel passato. Richiede ROLE_PROPERTY_BOOKINGS_MANAGER. Scrittura. |
| assetBookings_cancel | Rilascia un asset — il modo in cui termina un'assegnazione, e la cosa più vicina a una delete che questa risorsa possiede (non esiste un'operazione di delete). Richiede l'id della prenotazione e un `cancelReason` di 3-255 caratteri; la prenotazione viene mantenuta e timbrata con `cancelledAt` così la storia sopravvive, e l'asset diventa libero per il prossimo detentore. È la chiamata da fare quando un dipendente lascia l'organizzazione: assetBookings_list filtrato per `employee` trova cosa detiene, e questo rilascia ciascuna prenotazione. Richiede ROLE_PROPERTY_BOOKINGS_MANAGER. Scrittura. |
Letture contatori asset
Strumenti
| assetMeterReadings_get | Recupera una lettura di contatore per id — il suo meter, date e value. Sola lettura. |
| assetMeterReadings_list | Elenca le letture dei contatori — i valori datati registrati su un contatore di asset, i dati grezzi da cui legge la ripartizione della fatturazione a consumo. Ogni riga porta meter, date e value. Usalo per leggere lo storico di un contatore: un valore che non cambia mai tra i periodi (un contatore bloccato o condiviso) fattura zero, e un contatore senza righe recenti è uno che nessuno sta leggendo. Sola lettura. |
Contatori asset
Strumenti
| assetMeters_get | Recupera un contatore di asset per id — l'asset su cui si trova, il tipo di utenza, l'unità e l'identificativo esterno/QR, con le sue letture. Sola lettura. |
| assetMeters_list | Elenca i contatori di asset dell'org — i contatori di utenze/consumi collegati agli asset (elettricità, acqua, gas, riscaldamento). Ognuno porta l'asset su cui si trova, il suo tipo di utenza e unità, e le sue letture. Filtra per `property` (l'asset a cui appartiene) e `utilityType`. Usalo per risolvere l'id del contatore richiesto dalle letture, e per individuare contatori che leggono zero, sono bloccati su un valore, o si trovano su un contatore condiviso/collettivo. Sola lettura. |
| assetMeters_update | Aggiorna un contatore di asset — il suo label, tipo di utenza, unit, o stato active. Usalo per ritirare un contatore dal conteggio (ad es. un'utenza ora fatturata direttamente dalla fattura) senza eliminare la sua storia di letture. Richiede ROLE_PROPERTIES_MANAGER. Scrittura. |
Asset
Strumenti
| assets_get | Recupera un asset per id — name, status, categoria (attributeSet), parent, assetCode, numero di serie, date di acquisto e garanzia, location e impostazioni di prenotazione. Sola lettura. |
| assets_list | Elenca gli asset dell'org — il registro delle cose fisiche che possiede o vende, da laptop e scrivanie ad appartamenti, posti auto e unità di stoccaggio. Filtra per status (in-stock | damaged | sold), attributeSet (la categoria secondo cui l'elenco Assets raggruppa), bookingAllowed, o un name o serialNumber parziale; ordina per name, status, serialNumber, boughtAt o warrantyTo. NON PAGINATO — l'intero set torna in un'unica risposta, quindi un registro grande è un payload unico e grande, non una prima pagina. Usalo per risolvere l'id dell'asset richiesto dalle prenotazioni asset e dai documenti asset. Sola lettura. |
| assets_import | Carica MOLTI asset in un'unica chiamata, chiavizzata su `assetCode` — lo strumento per portare un inventario da un altro sistema, dove assets_create sarebbe un round trip per record. Le righe si riconciliano rispetto all'org: un assetCode sconosciuto crea, uno noto aggiorna sul posto, una riga identica viene saltata, quindi rieseguire non cambia nulla e un'esecuzione a metà è sicura da ripetere. `parentAssetCode` annida una riga sotto un'altra TRAMITE IL SUO CODE, risolto rispetto all'org e rispetto alle righe precedenti dello stesso batch; un parent che non si risolve mai fa fallire quella riga invece di lasciarla silenziosamente orfana. TRE CAMPI RENDONO IL RECORD LEGGIBILE invece che un nome nudo: `attributeSetName` è la categoria che la UI mostra come Typ zasobu e secondo cui l'elenco raggruppa, `locationName` è dove la cosa si trova fisicamente, e `attributes` è una mappa {name: value} per area, floor, price e qualsiasi altra cosa porti la fonte. Tutti e tre vengono risolti PER NAME — la categoria, la location, le definizioni di attributo e le loro associazioni vengono trovate o create per te, quindi un chiamante non gestisce mai uno di quegli IRI, e i name vengono abbinati senza distinzione tra maiuscole e minuscole, così "Mieszkanie" e "mieszkanie " non possono dividere l'elenco in due. `attributes` ha bisogno di una categoria a cui appoggiarsi, e un valore che viene interpretato come numero crea un attributo numerico, deciso la prima volta che il name compare. Un attributo la cui scrittura fallisce NON fa fallire il suo asset. PASSA PRIMA dryRun:true su un caricamento di inventario reale — riporta would-create / would-update / would-skip per riga e non crea assolutamente nulla, categorie e location incluse. Max 1000 righe. Richiede ROLE_PROPERTIES_MANAGER. Scrittura. |
| assets_create | Crea un asset (name + status + bookingType richiesti; status = in-stock | damaged | sold, bookingType = minutes | days | single-days | permanently). bookingType è richiesto anche quando l'asset non viene mai prenotato — passa "permanently" per qualcosa che non viene dato in prestito, e lascia bookingAllowed false. Due campi portano la struttura: `parent` annida un asset sotto un altro (un'unità sotto un edificio, un monitor sotto una scrivania), e `attributeSet` imposta la categoria secondo cui l'elenco Assets raggruppa, che è anche dove vivono gli attributi personalizzati come area o floor. `assetCode` è un handle UNICO cross-system — usalo per conservare l'id che questo asset ha nel sistema di origine da cui è stato importato, così un re-import aggiorna invece di duplicare. Richiede ROLE_PROPERTIES_MANAGER. Scrittura. |
| assets_update | Aggiorna un asset per id — name, status, categoria, parent, assetCode, numero di serie, date, location o impostazioni di prenotazione. È così che un asset passa da in-stock a sold. Nota che il vocabolario di status è in-stock | damaged | sold e NON ha uno stato reserved, quindi un blocco temporaneo deve essere modellato in altro modo. Richiede ROLE_PROPERTIES_MANAGER. Scrittura. |
Valori attributo entità
Strumenti
| attributeEntityValues_list | Elenca i VALORI degli attributi — cosa possiede realmente un asset, progetto, budget o cliente specifico per un attributo associato. Ogni riga porta l'attribute, il value, e `relationId` che indica l'entità a cui appartiene. Sola lettura. |
| attributeEntityValues_create | Imposta un valore di attributo su un'entità (attribute + value richiesti). `relation` È UN IRI — "/properties/7", non la parola "property": il backend lo risolve e deriva il relation name dalla classe della risorsa, quindi passare un nome nudo genera un errore. (`relationId` accetta un id semplice e funziona ancora, ma è deprecato a favore dell'IRI.) L'attributo deve essere già ASSOCIATO alla categoria di quell'entità, altrimenti il valore viene memorizzato e non mostrato mai. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
| attributeEntityValues_update | Modifica sul posto un valore di attributo, tramite il suo id. Usa questo invece di creare un secondo valore per la stessa coppia (entità, attributo) — nulla impone l'unicità, quindi un duplicato viene accettato e la UI ne mostra solo uno. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
| attributeEntityValues_delete | Rimuovi un valore di attributo da un'entità. La definizione e l'associazione sopravvivono; sparisce solo il valore di questa entità. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
Attributi
Strumenti
| attributes_get | Recupera una definizione di attributo per id — name, type, se è required o multiple, il valore di default e il pattern di formato. Sola lettura. |
| attributes_list | Elenca le DEFINIZIONI di attributo — i campi con nome (area, floor, price) che le categorie associano e per cui gli asset portano valori. Ognuno ha un type: number | string | date | state | period. Sola lettura. |
| attributes_create | Crea una definizione di attributo (name + type richiesti; type è number | string | date | state | period). IL TYPE È LA DECISIONE: è condiviso da ogni entità che porta questo attributo, quindi un campo creato come `string` non potrà in seguito essere totalizzato o ordinato come numero senza riscrivere ogni valore esistente. Decidilo in base ai valori che hai realmente, non al primo che vedi. Una definizione da sola non fa nulla — associala a una categoria con attributeSetAttributes_create, altrimenti non comparirà mai da nessuna parte. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
| attributes_update | Aggiorna una definizione di attributo — name, type, required, multiple, default o format. Cambiare `type` su una definizione che ha già valori è l'operazione rischiosa: i valori esistenti non vengono convertiti. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
Attributi dei set di attributi
Strumenti
| attributeSetAttributes_list | Elenca le associazioni tra categorie e definizioni di attributo — quali campi compaiono su quale categoria. Sola lettura. |
| attributeSetAttributes_create | Associa una definizione di attributo a una categoria (attributeSet + attribute, entrambi IRI). QUESTO È CIÒ CHE FA COMPARIRE UN ATTRIBUTO: senza l'associazione un valore può essere scritto con successo su un'entità e non comparirà mai nella UI — un fallimento senza alcun sintomo. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
| attributeSetAttributes_delete | Rimuovi l'associazione di un attributo da una categoria. La definizione ed eventuali valori sopravvivono; smettono semplicemente di essere mostrati per quella categoria, il che fa sembrare una perdita di dati quando non lo è. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
Set di attributi
Strumenti
| attributeSets_get | Recupera un attribute set per id — il suo name, relationName, icon, e gli attributi ad esso associati. Sola lettura. |
| attributeSets_list | Elenca gli attribute set dell'org — le CATEGORIE sotto cui sono archiviati asset, progetto, budget o cliente. Filtra per relationName: "property" per le categorie di asset (ciò che la UI chiama Typ zasobu e secondo cui raggruppa l'elenco Assets), oltre a "project", "budget" e "client". Consultalo prima di crearne una: una categoria duplicata per errore di ortografia o maiuscole/minuscole divide silenziosamente l'elenco che raggruppa, e nulla nella UI spiega il perché. Sola lettura. |
| attributeSets_create | Crea una categoria (name + relationName richiesti; relationName è uno tra property | project | budget | client, e per una categoria di asset è la stringa semplice "property" — NON un IRI). icon opzionale da un elenco fisso (room, parking, building, office, local, desk, monitor e così via) che la UI mostra accanto alla categoria. ELENCA PRIMA: i name non sono unici, quindi un secondo "Mieszkanie" viene accettato e divide silenziosamente in due l'elenco Assets. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
| attributeSets_update | Rinomina una categoria, cambia la sua icon, o spostala su un altro relationName. È così che una categoria creata con un errore di battitura viene corretta invece che duplicata. Richiede ROLE_ATTRIBUTES_MANAGER. Scrittura. |
Conti bancari
Strumenti
| bankAccounts_get | Recupera un conto bancario per id — nome, valuta, banca e il formato in cui vengono importati gli estratti conto. |
| bankAccounts_list | Elenca i conti bancari dell'organizzazione. Filtra per banca, oppure imposta hidden per includere quelli archiviati. Usalo per risolvere l'id bankAccount su cui filtra transactions_list. |
| bankAccounts_create | Crea un conto bancario (type, name, currency, defaultImportFormat obbligatori). Scrittura. |
| bankAccounts_update | Aggiorna un conto bancario per id. Scrittura. |
Banche
Strumenti
| banks_get | Recupera una banca per id — l'istituto, non un conto detenuto presso di essa. Usa bankAccounts_get per il conto. |
| banks_list | Elenca le banche presso cui sono detenuti i conti dell'org. Le banche nascoste sono INCLUSE di default — passa hidden=false per la vista dei selettori, o hidden=true per trovare quelle ritirate. Usalo per risolvere l'id della banca su cui filtra bankAccounts_list e che bankAccounts_create richiede. |
| banks_create | Crea una banca — l'istituto a cui appartiene un conto bancario, non il conto stesso (per quello c'è bankAccounts_create). Scrittura. |
| banks_update | Aggiorna una banca per id. È anche così che una banca viene nascosta e ri-mostrata: imposta `hidden` a true per ritirarla dai selettori senza eliminarla, false per farla ritornare. Non esiste uno strumento di archiviazione separato perché l'API non ha un'azione di archiviazione per una banca — il flag è il meccanismo. Scrittura. |
Budget
Strumenti
| budgets_employeePnl | P&L per dipendente per un budget — quanto il tempo di ciascuna persona ha generato rispetto a quanto costa. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
| budgets_get | Recupera un budget per id — il suo period, scope e le impostazioni. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
| budgets_list | Elenca i budget dell'org — i periodi rispetto a cui vengono pianificati e confrontati ricavi e costi. Usalo per risolvere l'id del budget richiesto da ogni strumento pnl. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
| budgets_pnlByTags | P&L per un budget, suddiviso PER TAG — income, costsByTag, costsByProject e netByTag sui periodi del budget. L'asse dei tag è ciò che lo rende leggibile per un'attività i cui costi non sono naturalmente per-progetto: assegna i tag ai documenti, e la suddivisione segue di conseguenza. Porta displayPricePerSqm quando l'org ha abilitato il price-per-sqm e nominato un attributo di area, il che lo trasforma in una vista per metro quadro per uno sviluppatore immobiliare. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
| budgets_pnlByTagsDrilldown | I documenti dietro una cella di budgets_pnlByTags. Consultalo quando un totale per tag sembra sbagliato — indica le transazioni che compongono il numero invece di lasciarti indovinare. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
Clienti
Strumenti
| clients_get | Recupera un cliente per id — nome, paese, valuta, partita IVA e stato. |
| clients_list | Elenca i clienti (i clienti dell'organizzazione). Filtra per status, oppure per externalPaymentCustomerId per trovare il cliente dietro un id del provider di pagamento. Usalo per risolvere l'id client su cui filtrano invoices_list, deals_list, projects_list e contracts_list. |
| clients_import | Carica MOLTI clienti in un'unica chiamata, chiavizzata su `externalRef` — lo strumento per portare un elenco di clienti o acquirenti da un altro sistema, dove clients_create sarebbe un round trip per persona. Le righe si riconciliano rispetto all'org: un externalRef sconosciuto crea, uno noto aggiorna sul posto, una riga identica viene saltata, quindi rieseguire non cambia nulla. Il ref è memorizzato come `externalPaymentCustomerId`, l'unica colonna di riferimento esterno che un client possiede, e `clients_list` filtra su di essa. NON abbinare i client per name invece — un elenco di acquirenti è pieno di cognomi condivisi e acquisti congiunti. Ogni risultato porta `counterpartyId`, richiesto da contracts_import e contracts_create. Due trappole che lo schema non può esprimere: un `tin` viene RIFIUTATO senza un `tinCountry`, e una riga di contatto richiede un'e-mail, quindi un solo numero di telefono non può crearne una. PASSA PRIMA dryRun:true su un caricamento di onboarding reale. Massimo 500 righe. Richiede ROLE_CLIENTS_MANAGER. Scrittura. |
| clients_create | Crea un nuovo record cliente (name, country, currency, status, tinType obbligatori). Scrittura. |
| clients_update | Aggiorna un record cliente per id. Scrittura. |
Chiavi di configurazione
Strumenti
| configKeys_catalog | Elenca ogni chiave di configurazione dell'organizzazione riconosciuta dal backend, con il suo tipo e i valori consentiti. Questo è il catalogo di ciò che è configurabile — leggilo prima di configs_get o configs_update invece di indovinare il nome di una chiave. Il permesso è applicato per chiave dal backend, quindi la presenza di una chiave qui non garantisce che l'utente connesso possa scriverla. |
Configurazioni
Strumenti
| configs_get | Legge un valore di configurazione dell'organizzazione per id, dove l'id è una chiave da configKeys_catalog (es. organization-logo-url, organization-icon-url). |
| configs_update | Aggiorna un valore di configurazione dell'organizzazione per id (type + name obbligatori; il permesso è applicato dal backend chiave per chiave). Scrittura. |
Contratti
Strumenti
| contracts_get | Recupera un contratto per id — parti, direzione, valore, termini ciclici e date. |
| contracts_list | Elenca i contratti. Filtra per direction — i valori memorizzati sono "out" (vendiamo / emettiamo) e "in" (acquistiamo / riceviamo), più "unknown" — uno stato reale e filtrabile, non un errore. Un contratto creato caricando un documento parte come "unknown" e ci resta finché l'estrazione o una persona non lo definisce, quindi ometti il filtro per ottenere tutti e tre: "in" e "out" interrogati separatamente NON sommano all'insieme completo (flowtly-mcp#130). NON "outgoing"/"incoming": questi non corrispondono a nulla e tornano come elenco vuoto invece che come errore. Filtra anche su counterparty, project, cyclic, name o tags. Usalo per risolvere l'id del contratto letto da contracts_paymentScheduleLines e a cui deals_win può collegare un deal vinto. |
| contracts_paymentScheduleLines | Elenca il piano di pagamento di un contratto — le rate in cui si prevede venga fatturato o pagato. Passa contractId da contracts_list. Questo è il piano, non i consuntivi: confrontalo con transactions_list per vedere cosa è stato realmente pagato. L'amount di ogni riga è in UNITÀ MINORI — grosze, non złote: "530000" corrisponde a 5 300,00, quindi dividi per 100 prima di riportare una cifra a chiunque. |
| contracts_import | Carica MOLTI contratti in un'unica chiamata, chiavizzata su `name` — il numero dell'accordo. A differenza di un client o di un asset, un contract NON ha una colonna di riferimento esterno, quindi il name È la chiave di idempotenza; un batch contenente lo stesso name due volte viene RIFIUTATO INTERAMENTE invece di aggiornare un contratto due volte, perché un numero duplicato significa che la fonte è sbagliata. `counterpartyExternalRef` risolve l'acquirente tramite lo stesso ref fornito a clients_import, così i due si compongono: importa prima i client, poi i contratti, senza mai gestire un counterparty id numerico — un ref che non corrisponde a nessun client fa fallire quella riga invece di creare un contratto senza controparte. `direction` è "out" (vendiamo) o "in" (acquistiamo); la colonna non ha alcun vincolo lato server, quindi una parola sbagliata viene memorizzata e il contratto non corrisponderà poi a nessun filtro da nessuna parte. PASSA PRIMA dryRun:true. Massimo 500 righe. Richiede ROLE_CONTRACTS_MANAGER. Scrittura. |
| contracts_create | Crea un contratto. Scrittura. |
| contracts_update | Aggiorna un contratto per id. Scrittura. |
| contracts_delete | Elimina un contratto per id. Scrittura. |
Centri di costo
Strumenti
| costGroups_list | Elenca i cost group / centri di costo — i contenitori in cui sono archiviati costi, fornitori e fatture in entrata. Usalo per risolvere l'id costGroup richiesto da suppliers_create e proposto dai suggerimenti sulle fatture in entrata. |
| costGroups_create | Crea un centro di costo (name + type obbligatori). Scrittura. |
| costGroups_update | Aggiorna il nome o il tipo di un centro di costo per id. Scrittura. |
Controparti
Strumenti
| counterparties_get | Recupera una controparte per id. |
| counterparties_list | Elenca le controparti — ogni soggetto con cui l'organizzazione ha rapporti. I flag supplier e client indicano quale ruolo (o ruoli) ricopre una controparte, e un record può essere entrambi. È il soggetto presente su una transazione bancaria, quindi è ciò con cui vengono abbinate le fatture in entrata e le transazioni. Filtra per type, supplier, client, cyclic o budgetNeutral. |
Note CRM
Strumenti
| crmNotes_get | Recupera una nota CRM per id. |
| crmNotes_list | Elenca le note scritte su lead e trattative. Filtra per lead o deal per leggere il commentario progressivo su un singolo record. |
| crmNotes_create | Aggiunge una nota a un lead o a una trattativa (body + esattamente uno tra lead/deal). L'autore è l'utente connesso. Scrittura. |
| crmNotes_update | Aggiorna il testo di una nota CRM per id. Scrittura. |
| crmNotes_delete | Elimina una nota CRM per id. Scrittura. |
Motivi di perdita trattativa
Strumenti
| dealLostReasons_get | Recupera un motivo di perdita trattativa per id. |
| dealLostReasons_list | Elenca i motivi per cui un affare può essere segnato come perso, in ordine. deals_lose richiede un lostReasonId da qui. |
Trattative
Strumenti
| deals_get | Recupera una trattativa per id — titolo, cliente, fase, importo, responsabile, contatto, data di chiusura prevista ed effettiva. |
| deals_list | Elenca le trattative/opportunità — la pipeline di vendita. Filtra per status (open / won / lost), stage, owner, client, lead, oppure per intervalli di expectedCloseDate / closedAt. Gli importi sono espressi in unità minori con una valuta esplicita; non dare per scontata quella predefinita dell'organizzazione. |
| deals_create | Crea un deal/opportunità. Richiesti: title, stage (da stages_list), e un'ANCORA — almeno uno tra client o lead. Un deal senza nessuno dei due viene rifiutato con 422 "A deal must reference a client or a lead.", quindi ancora un prospect per cui non hai un record cliente al suo lead (`/leads/<id>` da leads_list) invece di inventare un client; passa client (`/clients/<id>` da clients_list) una volta che ce n'è uno. Impostare entrambi è consentito. Opzionali: amountMinor, currency, expectedCloseDate, owner, contact. Creare direttamente in uno stage won richiede inoltre client — un deal solo-lead non può essere vinto. Scrittura. |
| deals_update | Aggiorna un deal per id (title, stage, amountMinor, currency, expectedCloseDate, owner, contact, client, lead). Spostare lo stage viene registrato automaticamente. La regola dell'ancora di deals_create si applica comunque al risultato, quindi non puoi azzerare l'unico client o lead che un deal possiede — sostituiscine prima uno. Spostare un deal in uno stage won richiede client: collega qui il cliente (o esegui leads_convert) prima di vincere un deal solo-lead. Scrittura. |
| deals_delete | Elimina una trattativa per id (eliminazione soft). Scrittura. |
| deals_win | Contrassegna un deal come vinto — lo sposta in uno stage won e lo timbra come chiuso; contractId opzionale collega un contratto esistente. BACKFILL DI UNA VITTORIA STORICA: passa closedAt opzionale (ISO-8601, es. "2026-05-07" o un timestamp completo) per registrare la data in cui si è EFFETTIVAMENTE chiuso. Omettilo e il server timbra now, il che mette un deal vecchio nella cifra "vinti questo mese" del mese corrente — quindi impostalo ogni volta che stai inserendo un deal chiuso prima di oggi. Non può essere nel futuro (422), e PUÒ essere anteriore al createdAt del deal stesso: un deal creato oggi e chiuso a maggio è la forma normale di un backfill corretto, non un errore. Il deal deve GIÀ referenziare un client: vincere un deal solo-lead viene rifiutato con 422 "Attach a customer before marking this deal Won.", perché non c'è un cliente da fatturare. Trasforma il lead in uno con leads_convert, o imposta client con deals_update, poi vinci. Scrittura. |
| deals_lose | Contrassegna un deal come perso — richiede lostReasonId (da dealLostReasons_list); lostReasonNote opzionale. BACKFILL DI UNA PERDITA STORICA: passa closedAt opzionale (ISO-8601) per registrare la data in cui si è EFFETTIVAMENTE chiuso, esattamente come fa deals_win. Omettilo e il server timbra now. Non può essere nel futuro (422), e può essere anteriore al createdAt del deal. Scrittura. |
| deals_reopen | Riapre una trattativa vinta/persa riportandola a open. Scrittura. |
Cronologie fasi trattativa
Strumenti
| dealStageHistories_get | Recupera un record di cambio fase trattativa per id. |
| dealStageHistories_list | Elenca le transizioni di stage di un affare, dalla più recente. Filtra per deal. Ogni deals_update che sposta lo stage viene registrato qui automaticamente, quindi questo è il modo per ricostruire quanto tempo un affare è rimasto in ogni stage — l'affare stesso porta solo quello corrente. |
Dipartimenti
Strumenti
| departments_list | I dipartimenti dell'org, con l'id numerico con cui ciascuno viene referenziato. LEGGI QUESTO PRIMA DI people_create o people_update: entrambi accettano un IRI `department` e non c'è altro modo per scoprirne uno valido. La collezione non è paginata ed è ordinata per name, quindi una singola chiamata restituisce ogni dipartimento dell'org. Filtra per `name` (corrispondenza parziale) o `code` (esatto). Le righe portano id, name e code; `manager` è una relazione e non è incluso nelle righe dell'elenco — leggilo con people_list dall'altro lato se ti serve. Richiede ROLE_EMPLOYEES_VIEWER. Sola lettura. |
| departments_create | Aggiungi un dipartimento, così le persone possono essere archiviate sotto di esso. `name` è richiesto (fino a 128 caratteri) ed è UNICO in tutta l'org; `code` è opzionale (fino a 64) ed è ANCH'ESSO unico — la forma breve che un'org usa già nei propri fogli di calcolo (CEO, TECH, PROC). `manager` è un IRI employee opzionale da people_list. ELENCA PRIMA E ASPETTATI COLLISIONI: poiché sia name che code sono unici, ripostare un dipartimento già esistente FALLISCE invece di essere idempotente, quindi un import che presuma create-per-riga si bloccherà la prima volta che incontra un dipartimento già presente nell'org — tipicamente uno rimasto da una prova. Riconcilia quella riga con departments_update invece di crearne un'altra attorno. NON C'È DELETE: il backend non espone alcuna delete su un dipartimento, quindi un name o code sbagliato viene corretto sul posto con departments_update e non viene mai rimosso. Richiede ROLE_EMPLOYEES_MANAGER. Scrittura. |
| departments_update | Rinomina un dipartimento, assegnagli un code, o imposta il suo manager. È lo strumento che rende possibile un import di dipartimenti, non solo comodo: `name` e `code` sono entrambi unici, quindi un dipartimento che l'org ha già — la singola riga "HR" che una proof-of-concept tende a lasciare — non può essere creato di nuovo, e l'elenco reale si raggiunge CORREGGENDO quella riga invece di collidere con essa. Cambiano solo i campi che invii, quindi passare solo `code` lascia il name intatto. `id` è l'id numerico da departments_list; `manager` è un IRI employee da people_list. NON C'È DELETE, il che rende questo l'intera storia della riparazione: un dipartimento creato con un errore di battitura viene corretto qui, e uno che non dovrebbe esistere può solo essere rinominato, non rimosso. Richiede ROLE_EMPLOYEES_MANAGER. Scrittura. |
Limiti giorni di ferie
Strumenti
| holidayDaysLimits_get | Una riga di entitlement per id — l'amount, il type, la variant del contratto e la data in cui entra in vigore. holidayDaysLimits_list trova l'id. Gli importi sono in SECONDI (#3763). Sola lettura. |
| holidayDaysLimits_list | Quante ferie ogni persona ha DIRITTO a prendere, per type — non quante ne ha prese, che è holidays_list. Filtra per employee. Una persona può avere più righe per un tipo nel tempo, perché un saldo viene integrato o corretto: la riga IN VIGORE è quella con il dateFrom più recente già raggiunto, e le righe datate nel futuro vengono deliberatamente ignorate fino ad allora. Gli importi sono in SECONDI (#3763) — un giorno di ferie da 8h è 28800. Richiede ROLE_HOLIDAYS_MANAGER. Sola lettura. |
| holidayDaysLimits_create | Concedi a una persona un'indennità di un tipo di ferie, con effetto da una data. `seconds`, NON giorni (#3763): un giorno da 8h è 28800, quindi 21 giorni sono 604800 e un saldo di straordinari di 2h30 è 9000 — una cifra che non aveva dove andare finché questo veniva memorizzato in giorni interi. `employee` e `holidayType` sono IRI (forniti da people_list e holidayTypes_list); `variant` è il tipo di contratto a cui appartiene l'indennità (uop, b2b, uz, uod). Per CORREGGERE un saldo esistente, aggiungi una riga con un dateFrom successivo invece di modificare quella vecchia — la riga in vigore è la più recente il cui dateFrom è già arrivato, quindi la storia resta intatta e una correzione può essere inserita prima che entri in vigore. (employee, holidayType, variant, dateFrom) è unico, quindi ripostare lo stesso giorno non sostituisce nulla e fallisce. Richiede ROLE_HOLIDAYS_MANAGER. Scrittura. |
| holidayDaysLimits_update | Correggi una riga inserita erroneamente — un errore di battitura nell'amount, la variant sbagliata. Gli importi sono in SECONDI (#3763). NON è così che si registra un saldo che CAMBIA nel tempo: per quello, crea con holidayDaysLimits_create una nuova riga con un dateFrom successivo, che preserva quale fosse il saldo precedente e quando. Modificare sul posto riscrive la storia e rende la vecchia cifra irrecuperabile. holidayDaysLimits_list trova l'id. Richiede ROLE_HOLIDAYS_MANAGER. Scrittura. |
Richieste di ferie
Strumenti
| holidayRequests_list | RICHIESTE di ferie e a che punto sono — in attesa, approvate, rifiutate. Distinto da holidays_list, che sono le ferie prenotate: una richiesta ancora in attesa di decisione non è ancora un'assenza, quindi pianifica su holidays_list e usa questo per vedere cosa è in attesa di qualcuno. Fornisce l'holidayRequestId che holidays_approve e holidays_bulkApprove utilizzano. Sola lettura. |
| holidayRequests_cancel | Annulla una richiesta di ferie — usalo per eliminare una richiesta su cui non si dovrebbe mai agire, come una riga lasciata da una prova, un test, o qualcuno che ha lasciato l'organizzazione. DUE COSE CHE SORPRENDONO LE PERSONE. (1) NON ELIMINA LA RIGA: il backend imposta status a `canceled` invece di rimuovere la riga. MA UNA RICHIESTA ANNULLATA SPARISCE DA holidayRequests_list — verificato in produzione: successivamente né l'elenco senza filtri né status=canceled la restituiscono. Quindi non puoi rileggere ciò che hai annullato e non c'è undo tramite l'MCP; sii sicuro dell'id prima di chiamare. (2) NON È LA STESSA COSA DI RIFIUTARE. Rifiutare registra una decisione — scrive una voce nel log di approvazione con il tuo nome e MANDA UN'EMAIL AL DIPENDENTE per dire che le sue ferie sono state rifiutate — mentre annullare notifica solo l'HR, e solo quando `notify-hr-managers-of-leave-activity` è attivo per l'org. Per una riga che non è mai stata una richiesta genuina, cancel è quella onesta e più silenziosa. FUNZIONA SOLO SU UNA RICHIESTA PENDENTE (`requested`) quando non ne sei il proprietario: una richiesta accettata ha già prodotto una Holiday che questo non rimuove, quindi annullarne una lascerebbe un'assenza prenotata dietro a una richiesta che legge `canceled`. Richiede ROLE_HOLIDAYS_MANAGER per la richiesta di qualcun altro; il richiedente può sempre annullare la propria. holidayRequests_list fornisce l'id. Scrittura. |
Festività
Strumenti
| holidays_active | Chi è assente ADESSO — ogni ferie attualmente in corso, a livello di organizzazione, per tutti. Questo è lo strumento per 'chi è fuori oggi', e quello da verificare prima di trattare freePercent di resourcingBench_get come disponibilità, perché il bench non sottrae le ferie. A differenza di holidays_list non applica alcuno scoping di progetto e non richiede alcun permesso oltre l'essere autenticati, quindi la sua risposta copre l'intera organizzazione. Restituisce ogni assenza con il suo tipo e le date. Sola lettura. |
| holidays_get | Un record di ferie per id, con il suo tipo, date e durata. Ottieni l'id da holidays_list o holidays_active. Sola lettura. |
| holidays_list | Ferie prenotate in un periodo — la vista di pianificazione, mentre holidays_active risponde solo per oggi. Filtra per dipendente, per intervallo di date o per progetto. COSA VEDI DIPENDE DAI TUOI PERMESSI, e un elenco corto non è prova che nessuno sia assente: un holidays manager o un accountancy viewer ottiene l'intera organizzazione, mentre un project lead o viewer DEVE passare un filtro di progetto (o chiedere di sé stesso) e viene rifiutato apertamente senza — quel rifiuto è un limite di permesso, non un calendario vuoto. Sola lettura. |
| holidays_create | Registra un'assenza che una persona sta effettivamente prendendo — l'assenza prenotata in sé, non il diritto maturato (holidayDaysLimits_create) e non una richiesta pendente (holiday request, che devono ancora essere approvate). Ciò che questo scrive è tempo libero già concordato, quindi compare subito in holidays_list e non richiede alcun passaggio di approvazione. `employee` è un IRI da people_list; `type` è un id da holidayTypes_list. `dateFrom`/`dateTo` inclusivi, e una singola chiamata copre un intero intervallo invece di una riga per giorno. Due cose mordono: un type il cui `descriptionRequired` è true (leggi prima holidayTypes_list — `vacations` comunemente lo è) RIFIUTA una create senza `description`; e `pick-up-day` è tempo già dovuto, quindi NON consuma l'indennità annuale come fa `vacations` — registrare come `vacations` un giorno restituito per una festività di sabato consuma silenziosamente un giorno del diritto di qualcuno. Controlla holidays_list per la stessa persona e le stesse date prima di creare, perché una sovrapposizione viene RIFIUTATA, non duplicata: il backend solleva `validation_holiday_dates_overlap` come 422 su `dateTo` quando l'intervallo tocca un qualsiasi giorno già coperto da un'altra assenza per quella persona. L'unica eccezione è ristretta — due assenze parziali di UN SOLO GIORNO nella stessa data, di type DIVERSI, entrambe `vacations` o `pick-up-day`, le cui ore insieme rientrano nella giornata lavorativa. Qualsiasi altra sovrapposizione fallisce. ESISTE un holidays_update, quindi cambiare il type di un'assenza non richiede più delete-poi-create. OGNI CREATE MANDA UN'EMAIL AL DIPENDENTE, al suo indirizzo aziendale, per dire che l'assenza è stata aggiunta — quindi caricare un anno di storia già vissuta arriva nella sua casella di posta riga per riga, e per il personale che non è ancora stato invitato è la prima volta che sente parlare di Flowtly. STAI CARICANDO UN ANNO DI STORIA? Esiste una forma bulk — holidays_import riconcilia fino a 500 assenze in un'unica chiamata, salta quelle già registrate così è sicuro rieseguirlo, e ha la mail disattivata per default — ma NON È DISPONIBILE SU QUESTA CONNESSIONE: è servito solo allo scope internal, quindi non puoi chiamarlo qui e cercarlo non lo troverà. Esegui questo strumento in ciclo, oppure chiedi al tuo operatore Flowtly di eseguire il caricamento bulk. Passa `notify: false` per un BACKFILL di assenze già avvenute; lascialo stare quando registri qualcosa di nuovo, perché allora la mail è lo scopo. Sopprime solo il messaggio — la riga, il suo `createdAt` e il suo dato di payroll vengono scritti in ogni caso. Richiede ROLE_HOLIDAYS_MANAGER. Scrittura. |
| holidays_delete | Rimuovi definitivamente un'assenza prenotata — la riga viene eliminata, a differenza di holidayRequests_cancel che si limita a cambiare lo status di una richiesta. Usalo per eliminare assenze che non avrebbero mai dovuto contare: righe demo o di test lasciate da una prova, o orfane perché il loro dipendente è stato eliminato (people_delete scollega le assenze invece di rimuoverle, quindi sopravvivono con un employee name vuoto). QUESTO MUOVE NUMERI REALI: un'assenza prenotata è `payrollEligible` e consuma il diritto della persona, quindi eliminarne una cambia il suo saldo ferie — questo è lo scopo quando si ripulisce dati di test, ed è un bug di perdita dati quando la riga era genuina. Nessun undo, nessuna notifica. Leggi prima holidays_list e sii certo che la riga non sia storia reale: una description nella lingua dell'org, o date corrispondenti a un'assenza reale, di solito significano che lo è. Richiede ROLE_HOLIDAYS_MANAGER. Scrittura. |
Tipi di ferie
Strumenti
| holidayTypes_list | I tipi di ferie/assenza usati da questa org, con l'id con cui ciascuno viene referenziato. Leggilo prima di holidayDaysLimits_create/update, che richiedono un IRI holidayType e altrimenti verrebbe indovinato. Quello che non è una vacanza nel senso ordinario è `pick-up-day` — tempo libero dovuto per straordinari già lavorati (in polacco *odbior nadgodzin*), che è un saldo CONCESSO piuttosto che un diritto annuale. Sola lettura. |
| holidayTypes_create | Aggiungi un tipo di ferie/assenza che l'org non offre ancora — un sabbatico, un congedo parentale non retribuito, un giorno di formazione — così le assenze possono essere prenotate su di esso con holidays_create e un'indennità concessa con holidayDaysLimits_create. `name` (3–64 caratteri) è ciò tra cui le persone scelgono quando prenotano; `color` e `icon` sono come appare nel calendario; `reducesWorkingTime` false contrassegna tempo libero che NON riduce le ore attese del mese; e `descriptionRequired` true fa sì che il tipo richieda un motivo, che holidays_create poi impone — vedi quello strumento per cosa rifiuta. `status` ha default `active`, quindi un tipo creato senza pensarci viene offerto a tutti immediatamente. LEGGI PRIMA holidayTypes_list: i type sono a livello di org, e NON C'È DELETE — un duplicato o un nome sbagliato può solo essere nascosto di nuovo impostando status a inactive con holidayTypes_update, e nel frattempo mantiene ogni assenza prenotata su di esso. Richiede ROLE_HOLIDAYS_MANAGER. Scrittura. |
| holidayTypes_update | Modifica un tipo di ferie/assenza, e soprattutto RIATTIVANE uno. `status` commuta tra `active` e `inactive`, e un tipo inactive viene rifiutato da holidays_create — quindi registrare ferie storiche su un tipo che l'org ha nel frattempo ritirato inizia qui, ed è questo che sblocca un import di storico ferie invece di mandare qualcuno nella UI dell'app. DISATTIVARE NON È ELIMINARE, e non c'è delete: le assenze già prenotate mantengono un tipo inactive e si leggono comunque con esso in holidays_list, quindi inactive significa solo 'non offerto per nuove prenotazioni'. LA TRAPPOLA CHE NE DERIVA: riattivi `vacations` per caricare le assenze dell'anno scorso, dimentichi di riportarlo a `inactive`, e non hai semplicemente completato un import — hai cambiato ciò che l'organizzazione offre oggi, perché ogni dipendente che prenota ferie ora rivede quel tipo nell'elenco. Riportalo indietro nella stessa sessione in cui hai importato. `descriptionRequired` incide anche su holidays_create, che rifiuta una prenotazione senza description una volta attivato; attivarlo lascia in pace le assenze già registrate. `id` è l'id stringa da holidayTypes_list (`vacations`, `not-paid`), e cambiano solo i campi che invii. Richiede ROLE_HOLIDAYS_MANAGER. Scrittura. |
Fatture in entrata
Strumenti
| incomingInvoices_get | Recupera una fattura in entrata (fornitore) o un documento di supporto per id, con i campi estratti via OCR e lo stato di abbinamento attuale. |
| incomingInvoices_list | Elenca le fatture in entrata (fornitori) e i documenti di supporto — la inbox di contabilità. Una fattura in entrata È un documento allegato a una transazione bancaria, quindi exists.transaction=false è il modo per trovare documenti non ancora abbinati a un pagamento. Filtra anche per status, relatedMonth, controparte, progetto, tag o hasDetectedProblems. Ogni documento è identificato univocamente come externalId 'upload_sha256:<sha256 dei byte>' — calcola l'hash di un file e cerca quell'externalId qui PRIMA di incomingInvoices_create, altrimenti creerai un duplicato. |
| incomingInvoices_matchCandidates | Elenca le transazioni bancarie che potrebbero corrispondere al pagamento di questa fattura in entrata, classificate dal matcher del backend. Usalo quando un documento non ha una transazione allegata e devi sceglierne una; preferisci questi candidati piuttosto che indovinare tu stesso dagli importi. |
| incomingInvoices_suggestions | Legge le proposte di Flowtly per una fattura in entrata — corrispondenza fornitore, cost group, transazione bancaria corrispondente, avviso di duplicato. Sono esattamente le proposte che un utente umano vede nell'app. Leggile prima, poi applica una per id con incomingInvoices_applySuggestion, oppure accettale tutte con acceptAllSuggestions. Passa refresh per ricalcolare invece di servire l'insieme in cache. |
| incomingInvoices_suggestionsDebug | Spiega PERCHÉ i suggerimenti di una fattura in entrata sono usciti così — il punteggio del matcher, per diagnosticare un suggerimento mancante o errato. Solo diagnostico; usa incomingInvoices_suggestions per il lavoro normale. |
| incomingInvoices_create | Archivia una fattura in entrata (fornitore) o un documento di supporto in contabilità — passa i byte come base64 con un fileName e receivedAt. Flowtly esegue l'OCR e suggerisce un fornitore e una transazione bancaria corrispondente. Il file è identificato univocamente come externalId 'upload_sha256:<sha256 dei byte>': per evitare un duplicato, calcola l'hash dei byte e verifica incomingInvoices_list per quell'externalId PRIMA di caricare. Scrittura. |
| incomingInvoices_applySuggestion | Accetta uno dei suggerimenti di Flowtly su una fattura in entrata — le stesse proposte che un utente umano vede nell'app (corrispondenza fornitore, cost group, transazione bancaria corrispondente, avviso di duplicato). Leggili prima con incomingInvoices_suggestions, poi applicane uno per il suo id. Preferisci questo a indovinare: è il matcher di Flowtly, non l'agente, a decidere cosa è plausibile. Scrittura. |
| incomingInvoices_acceptAllSuggestions | Accetta in un'unica chiamata tutti i suggerimenti in sospeso su una fattura in entrata — ciò che un utente fa con il pulsante "accetta tutto" dell'app. Il server applica, ricalcola e riapplica finché non compare più nulla di nuovo: l'abbinamento della transazione NON esiste finché fornitore e importo non sono stati applicati, quindi un singolo passaggio lascerebbe il documento non associato. Restituisce un report (cosa è stato applicato, cosa è stato rifiutato e perché, e la transazione a cui è stato infine associato). Passa dryRun per un'anteprima senza scrivere. Non accetta mai supplier_create né un avviso di duplicato. Scrittura. |
| incomingInvoices_checkEInvoices | Recupera eventuali nuove e-fatture KSeF nell'organizzazione — ciò che fa il pulsante "Sprawdź e-faktury" dell'app. Chiamalo prima di concludere che manca la fattura di un fornitore: senza di esso non puoi distinguere "il fornitore non l'ha mai inviata" da "la nostra sincronizzazione non è ancora stata eseguita". Ritorna una volta che il recupero è in coda; rileggi incomingInvoices_list dopo per vedere cosa è arrivato. Scrittura. |
Voci di budget iniziale
Strumenti
| initialBudgetItems_list | Elenca le voci di riga del budget iniziale — gli importi pianificati, per tag, rispetto ai quali contractComparison restituisce il confronto. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
Budget iniziali
Strumenti
| initialBudgets_contractComparison | PIANIFICATO contro CONTRATTUALIZZATO, per tag — gli importi pianificati del budget iniziale rispetto alla somma dei valori di contratto effettivamente firmati per quel progetto. Questa è la domanda 'abbiamo impegnato più di quanto pianificato, e dove', e legge direttamente dai contratti già presenti nell'org, quindi importare i contratti la rende rispondibile senza ulteriore lavoro. Gli importi sono in grosze; un progetto multi-valuta produce un avviso invece di un totale silenziosamente sbagliato. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
| initialBudgets_get | Recupera un budget iniziale per id, con le sue voci. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
| initialBudgets_list | Elenca i budget iniziali — il piano ORIGINALE per un progetto o investimento, in contrapposizione al budget live rispetto a cui viene misurato. Richiede ROLE_BUDGETS_VIEWER. Sola lettura. |
Fatture
Strumenti
| invoices_get | Recupera una fattura in uscita (vendita) per id — cliente, righe, totali, data di vendita e di emissione, stato. |
| invoices_list | Elenca le fatture in uscita (vendite). Filtra per cliente, tag, ricerca o un intervallo saleDate. Nota che saleDate — non la data di emissione né la data di creazione — è il campo su cui filtra invoices_export, quindi usa lo stesso qui quando riconcili un export. |
| invoices_export | Avvia un export zip delle fatture EMESSE per un periodo (from/to, entrambi YYYY-MM-DD, inclusivi) filtrato su DATA DI VENDITA — non data di emissione né di creazione. Sono incluse solo le fatture EMESSE; le bozze e le fatture non inviate sono escluse, ma le note di credito/correzioni SONO incluse. Client opzionale limita a un cliente (id o IRI da clients_list). Massimo 200 fatture per export — se il periodo ne ha di più, restringilo (es. esporta un mese alla volta); un periodo con 0 fatture emesse viene rifiutato. Questa chiamata mette solo in coda il job (il rendering di un mese può richiedere minuti) — NON restituisce un link di download. Fai polling di invoices_exportStatus con l'exportId restituito finché non riporta "ready". Scrittura. |
| invoices_exportStatus | Fa polling dello stato di un export zip avviato da invoices_export, tramite exportId. Una volta che lo status è "ready", la risposta include downloadUrl (un link firmato a breve termine — scade dopo 1 ora, vedi expiresAt), filename e byteSize; i byte del file non vengono mai restituiti tramite questo strumento. Se lo status è "failed", failureReason spiega il motivo. |
| invoices_import | Archivia una fattura attiva (vendita) GIÀ EMESSA nell'org — per portare dentro lo storico fatture durante l'onboarding. Il numero di fattura esterno che passi viene preservato verbatim, l'acquirente viene risolto tramite tax id (creato se assente), e la fattura atterra come issued SENZA renderizzare un PDF, inviare email al client, o inviare a KSeF. Importare un numero già esistente è un no-op che segnala la fattura esistente, quindi un import massivo è sicuro da rieseguire — ma questa garanzia vale solo per chiamate sequenziali; due import realmente concorrenti dello stesso numero possono entrambi atterrare. Passa expectedGrossTotal (il lordo stampato sul documento sorgente) e l'import viene rifiutato se non concorda con il totale calcolato dalle righe. buyer.tin è richiesto — l'acquirente non viene mai abbinato per name. Usa invoices_create, non questo, per emettere una nuova fattura genuina. Scrittura. Passa dryRun:true per un'ANTEPRIMA senza scrivere — segnala would-create / would-skip e non crea alcuna fattura né alcun client; esegui prima a secco un backfill storico e controlla i conteggi prima di eseguirlo per davvero. |
| invoices_create | Emetti una NUOVA fattura attiva (vendita) — lo strumento per fatturare un client per la prima volta. Non confonderlo con i suoi due vicini: invoices_import archivia retroattivamente una fattura GIÀ emessa altrove (storico di onboarding), e incomingInvoices_create archivia un documento di COSTO di un fornitore. La fattura atterra NON INVIATA: lo status è derivato dalle righe di log della fattura e una fattura appena creata non ne ha, quindi questa chiamata non renderizza, invia email, o sottomette nulla a KSeF — tratta il risultato come una bozza da rivedere prima dell'emissione. `name` è il numero di fattura e sta a te sceglierlo (max 32 caratteri) — leggi prima invoices_list e segui la serie esistente dell'org invece di inventarne una, perché nulla qui alloca il prossimo numero per te. Richiesti: name, type ("invoice"), tinType, issueDate, saleDate, dueDate. Passa `client` (IRI da clients_list) e, per una registrazione che si riconcilia più avanti, `contract` (IRI da contracts_list) così la fattura compare sotto quel contratto. Le voci di riga vanno in `invoiceRows` — prezzo unitario netto, quantità e un'aliquota fiscale per riga; i totali vengono calcolati dalle righe, non passati direttamente. L'ALIQUOTA DI UNA RIGA TRANSFRONTALIERA È UNA BASE GIURIDICA, NON UN NUMERO: oltre alle aliquote numeriche `vatRate` accetta `np I`, `np II` e `zw`, è una stringa libera di 5 caratteri, e nulla convalida quale invii. `np I` e `np II` sono basi giuridiche DIVERSE e finiscono in campi diversi della fattura KSeF: `np II` è P_13_9, servizi ai sensi dell'art. 100 ust. 1 pkt 4 della legge polacca sull'IVA (quelli dichiarati anche nell'elenco riepilogativo VAT-UE); `np I` è P_13_8, ogni altra cessione fuori dalla Polonia. Quale delle due sia una data cessione è una decisione fiscale: prendila dal commercialista dell'org o dalla prassi confermata dell'org per quel tipo di cliente, e NON COPIARE L'ALIQUOTA DA QUALUNQUE FATTURA `np` L'ORG ABBIA GIÀ — un precedente può essere a sua volta sbagliato. Il numero fiscale dell'acquirente deve essere già memorizzato SENZA il suo prefisso di paese (clients_create spiega perché) — questo documento stampa tinCountry unito a tin, quindi un client salvato come "RO40424862" qui viene stampato RORO40424862. `bankAccount` (da bankAccounts_list) sceglie il conto stampato sul documento, e `currency` ha come default quella dell'org. Scrittura. |
| invoices_update | Correggi una fattura attiva (vendita) per id, prima o dopo l'emissione. L'uso quotidiano è correggere una bozza emessa da invoices_create — una data sbagliata, una riga sbagliata, un collegamento a contratto mancante — invece di eliminarla e riemetterla, il che brucerebbe un numero di fattura. Leggi prima invoices_get: questo è un PATCH su un documento i cui totali sono derivati dalle sue righe, quindi sostituire `invoiceRows` sostituisce l'intero set, e una fattura già inviata non si "de-invierà" da sola perché l'hai modificata. Scrittura. |
Attività lead
Strumenti
| leadActivities_get | Ottiene un'attività di un lead (contatto di outreach) per id. |
| leadActivities_list | Elenca i contatti di outreach di un lead — la sua timeline di attività (invito inviato, risposte, chiamate, follow-up). Filtra per lead per leggere la storia di un singolo prospect. Questo è l'equivalente strutturato di crmNotes_list: le attività sono il registro dei contatti tipizzato e datato; le note sono commenti liberi. |
| leadActivities_create | Registra UN contatto di outreach su un lead — un invito inviato, un invito accettato, un messaggio, una risposta, una chiamata, un follow-up (lead + type + occurredAt richiesti; channel, contact, body opzionali). QUESTO è dove appartiene la storia di outreach di un prospect: una crmNote è commento libero, un'activity è il registro di contatti strutturato e filtrabile che la timeline della coda di prospecting rende. NON narrare i contatti in una nota. type: invite_sent | invite_accepted | message_sent | reply_received | call | meeting | follow_up | …; channel: linkedin | email | phone | …. Scrittura. |
| leadActivities_update | Aggiorna un'attività di outreach registrata per id (type, channel, occurredAt, body). Scrittura. |
| leadActivities_delete | Elimina un'attività di outreach registrata per id. Scrittura. |
| leadActivities_byList | Ogni lead activity su una CAMPAGNA (una lead list), in un'unica chiamata — passa l'id, l'IRI, o il name esatto della lista. leadActivities_list filtra per un singolo lead, quindi il reporting a livello di campagna costerebbe altrimenti una chiamata per membro (302 per una lista come PZFD); questo risolve invece i membri della lista e legge le loro attività in batch limitati. Combina con type e occurredAt.after/.before per ottenere i conteggi che le persone chiedono realmente: reply rate (type=reply_received), bounce rate (type=bounced), send coverage (type=message_sent). Restituisce listId, listName, leadCount, e le attività unite ordinate per occurredAt. Una lista sconosciuta è un ERRORE, non un risultato vuoto — quindi un name digitato male non può essere letto come "questa campagna non ha avuto attività". Gli id provengono da leadLists_list. Sola lettura. |
| leadActivities_bulkImport | Registra un'intera ondata outbound — ogni messaggio realmente inviato — in UNA chiamata, invece di un leadActivities_create per messaggio. Passa un array; ogni riga indica il proprio lead (leadCompanyName, abbinato a un lead ESISTENTE, o un IRI di lead) più type e occurredAt. Dai a ogni riga un externalId — l'id stabile per messaggio, ad es. l'id del messaggio Gmail — e l'import è idempotente: rieseguirlo, o rieseguire un'ondata solo parzialmente importata, segnala duplicati invece di crearli. Le righe senza externalId deduplicano su (lead, type, occurredAt, contact), la stessa chiave naturale usata da leads_bulkImport, quindi un'ondata atterrata per prima tramite quello strumento non viene duplicata qui. Ogni riga ottiene il proprio esito (created | duplicate | error), quindi una riga malformata non scarta il resto del batch. NON crea lead — usa leads_bulkImport per quello. ≤ 1000 righe/chiamata. Scrittura. |
Contatti lead
Strumenti
| leadContacts_get | Recupera un contatto lead per id. |
| leadContacts_list | Elenca le persone di contatto associate ai lead. Filtra per lead per leggere i contatti di un singolo prospect, oppure per email per trovare da quale lead proviene un messaggio. |
| leadContacts_create | Aggiunge una persona di contatto a un lead (lead + name richiesti; email, phone, role, linkedinUrl, isPrimary opzionali). L'URL LinkedIn di un contatto appartiene a linkedinUrl, NON a una crmNote. Scrittura. |
| leadContacts_update | Aggiorna un contatto di lead per id — es. imposta linkedinUrl / email / phone una volta trovati. Scrittura. |
| leadContacts_delete | Elimina un contatto lead per id. Scrittura. |
Appartenenze a liste lead
Strumenti
| leadListMemberships_get | Recupera un'appartenenza lead-lista per id. Il suo status e lastContactedAt sono uno snapshot scritto dal chiamante, non uno stato live — vedi leadListMemberships_list. |
| leadListMemberships_list | Elenca quali lead si trovano su quali liste di prospecting outbound. Filtra per list, lead o status. ATTENZIONE: status e lastContactedAt sono uno SNAPSHOT scritto da chiunque abbia importato o aggiornato per ultimo l'appartenenza. Non sono derivati, e nulla li fa avanzare quando viene registrata un'attività — registrare un'ondata di 529 follow-up non modifica nessuno dei due campi — quindi possono essere arbitrariamente indietro. Per rispondere a "quando abbiamo contattato per l'ultima volta questo prospect", leggi invece il registro attività: leadActivities_list per un singolo lead, leadActivities_byList per un'intera campagna. leadListMemberships_syncFromActivities segnala lo scarto e può colmarlo. |
| leadListMemberships_create | Aggiungi un lead a una lista outbound (list + lead richiesti; status opzionale). Qualsiasi lastContactedAt tu passi è uno snapshot che nulla farà avanzare in seguito — registra il contatto anche come lead activity, altrimenti resta non interrogabile. Scrittura. |
| leadListMemberships_update | Aggiorna l'appartenenza di un lead a una lista — ad es. imposta lo status di outreach (contacted/replied/bounced). status e lastContactedAt sono mantenuti dal chiamante: ciò che scrivi resta finché qualcuno non scrive di nuovo, e registrare lead activity NON li aggiorna. Scrittura. |
| leadListMemberships_delete | Rimuove un lead da una lista in uscita. Scrittura. |
Liste lead
Strumenti
| leadLists_get | Recupera una lista di prospecting in uscita per id. |
| leadLists_list | Elenca le liste di prospecting in uscita. Usalo per risolvere l'id list che leadListMemberships_create richiede. |
| leadLists_create | Crea una lista di prospecting in uscita (name obbligatorio). Scrittura. |
| leadLists_update | Aggiorna una lista in uscita per id. Scrittura. |
| leadLists_delete | Elimina una lista in uscita per id. Scrittura. |
Motivi di perdita lead
Strumenti
| leadLostReasons_get | Recupera un motivo di perdita lead per id. |
| leadLostReasons_list | Elenca, in ordine, i motivi per cui un lead può essere segnato come perso. |
Lead
Strumenti
| leads_dedupeCheck | Verifica se un prospect è già nel CRM, usando gli stessi filtri di leads_list (companyName, source, owner, …). Chiamalo PRIMA di leads_create: un lead duplicato divide la storia di outreach su due record, e nulla a valle li unirà per te. |
| leads_get | Recupera un lead per id — azienda, sito web, source, status, owner e il cliente in cui è stato convertito, se presente. |
| leads_list | Elenca i lead — obiettivi prospect, prima della qualificazione. Filtra per status, source, owner, client, companyName o intervalli createdAt/closedAt. Un lead qualificato diventa un Client più un Deal aperto tramite leads_convert; fino ad allora vive solo qui, non in clients_list. |
| leads_create | Crea un lead (target di prospect outbound/inbound; companyName, source, owner, linked client opzionali). Un nuovo lead è sempre status=open — status non è impostabile qui, e si muove solo tramite leads_convert, leads_lose e leads_reopen. Scrittura. |
| leads_update | Aggiorna un lead per id (company, website, source, owner, linked client, stage, doNotContact). NON status o lostReason: questi vengono rifiutati dall'entità e silenziosamente ignorati da questo endpoint, quindi chiudere un lead richiede leads_lose (con un lostReasonId) e annullare ciò richiede leads_reopen. Spostare `stage` avanza nel funnel; non chiude il lead. Scrittura. |
| leads_delete | Elimina un lead per id (eliminazione soft). Scrittura. |
| leads_convert | Converte un lead qualificato in un Client + un contatto per ciascun lead-contact + una Deal aperta. Richiede un client esistente (il client del lead o un clientId nel body). Scrittura. |
| leads_lose | Chiudi un lead come PERSO — imposta status=lost e timbra closedAt. RICHIEDE lostReasonId, l'`id` di una voce leadLostReasons (esegui prima leadLostReasons_list; è una picklist, quindi il testo libero viene rifiutato con 422). Questo è l'UNICO modo per registrare un lead come perso: leads_update ignora status, e doNotContact significa "non contattare mai più", che è un'affermazione diversa e molto più forte di "non l'abbiamo vinto". NON sposta lo stage del lead — LeadStage non ha un flag terminale, quindi il lead mantiene la sua posizione nel funnel e leads_reopen può ripristinarla esattamente. Scrittura. |
| leads_reopen | Annulla leads_lose — riporta status a open e azzera closedAt e il lost reason. Lo stage resta intoccato, quindi il lead riprende esattamente da dove si trovava. Usalo quando un lead è stato chiuso sul record sbagliato o il prospect è tornato. Scrittura. |
| leads_bulkImport | Importa molti lead in UNA chiamata, ciascuno con i suoi contatti, appartenenza a lista e attività di outreach annidate — il server crea il lead poi inserisce il suo id nei figli, così non devi mai gestire IRI intermedi. Idempotente per chiavi naturali (companyName / email / (list,lead) / (type,occurredAt,contact)): sicuro da rieseguire e da suddividere in blocchi (≤100 lead/chiamata). Questo è il percorso massivo che un import di campagna dovrebbe usare invece di N chiamate leads_create. Scrittura. |
Fasi lead
Strumenti
| leadStages_get | Recupera una fase lead per id. |
| leadStages_list | Elenca gli stage attraversati da un lead, in ordine. I lead hanno un proprio set di stage — i deal usano stages_list, che è una cosa diversa. |
Ubicazioni
Strumenti
| locations_get | Recupera una location per id — il suo name e gli orari d'ufficio. Sola lettura. |
| locations_list | Elenca le location dell'org — i luoghi fisici in cui si trovano gli asset, mostrati nella UI come Lokalizacja. Richiede ROLE_LOCATIONS_MANAGER, che insolitamente vincola anche la LETTURA oltre alla scrittura. Sola lettura. |
| locations_create | Crea una location (name richiesto; officeOpenHour/officeCloseHour opzionali come secondi dopo mezzanotte). Usa l'indirizzo reale invece di un nome di progetto o investimento — è ciò di cui ha bisogno chi si trova davanti all'asset, e il nome del progetto è già portato altrove. Richiede ROLE_LOCATIONS_MANAGER. Scrittura. |
| locations_update | Rinomina una location o cambia i suoi orari d'ufficio. Richiede ROLE_LOCATIONS_MANAGER. Scrittura. |
Indirizzi organizzazione
Strumenti
| organizationAddresses_get | Recupera un record di indirizzo di abbonamento per id — name, street, city, postCode, country, e i campi fiscali. `street` porta il numero civico quando è stato inserito a mano, e non lo porta quando proviene dalla ricerca NIP/GUS. Sola lettura. |
| organizationAddresses_list | Elenca i record di indirizzo di abbonamento dell'organizzazione — l'indirizzo collegato all'abbonamento Flowtly, e la fonte da cui il footer email {{organizationAddress}} viene renderizzato. Normalmente esattamente una riga. NON è l'indirizzo del venditore in fattura, che vive nelle chiavi di configurazione organization-billing-* (configs_get) e che fatture e KSeF leggono; i due sono mantenuti separatamente e regolarmente non coincidono. Leggi entrambi prima di concludere quale un cliente abbia effettivamente modificato. Sola lettura. |
| organizationAddresses_update | Aggiorna il record di indirizzo di ABBONAMENTO dell'organizzazione (id richiesto; invia solo i campi che stai cambiando). QUESTO È IL RECORD DA CUI VIENE RENDERIZZATO IL FOOTER EMAIL: il {{organizationAddress}} del footer è composto come "street, postCode city" a partire da qui, NON dalle chiavi di configurazione organization-billing-* che fatture e KSeF usano come indirizzo del venditore. I due archivi divergono, e il fatto che il footer legga questo è un difetto noto — quindi quando una firma mostra un indirizzo che il cliente giura di aver corretto, in realtà ha corretto le chiavi di billing e questo è il record che detiene ancora il vecchio valore. `street` è un'unica colonna di testo libero che deve portare anche il numero civico: la ricerca NIP/GUS compila solo il nome della via e scarta silenziosamente numero civico e interno, motivo per cui gli indirizzi qui riportano "ul. Example" senza numero. Scrivi il "ul. Example 8/12" completo per ripararlo. LEGGI PRIMA con organizationAddresses_list e confronta con configs_get su organization-billing-street prima di scrivere, così copi il valore realmente mantenuto dal cliente invece di inventarne uno. Richiede ROLE_BILLINGS_MANAGER. Scrittura. |
Organizzazioni
Strumenti
| organizations_get | Ottiene un'organizzazione per id. ATTENZIONE — questo NON indica a quale organizzazione sei connesso. Una connessione OAuth è fissata a esattamente un'org (legata al token), ma questo endpoint restituisce qualsiasi org di cui l'UTENTE connesso è membro, quindi una lettura riuscita qui può sembrare conferma di stare lavorando in quell'org quando potrebbe non essere così. Per verificare il tenant su cui stai realmente operando, leggi invece dati con scope al tenant — people_list o clients_list — e non avviare mai una scrittura massiva basandoti solo su questa chiamata. |
Persone
Strumenti
| people_get | Recupera un record persona/dipendente per id — nomi, email, telefono, responsabile e se è attivo. |
| people_list | Elenca le persone/dipendenti. Filtra per isActive, reportsTo (l'id di un responsabile), projectMembers.project o search; pagina con cursor. Persone e dipendenti condividono lo stesso id, quindi è così che ottieni l'id employee richiesto da ore lavorate, responsabilità, appartenenza ai progetti e strumenti di permessi. |
| people_create | Crea un record persona/dipendente (firstname + lastname obbligatori; opzionali companyEmail, contactEmail, contactPhone). Scrittura. |
| people_update | Aggiorna un record persona/dipendente per id (name, companyEmail, contactEmail, contactPhone, ecc.). Scrittura. |
| people_delete | Elimina un record dipendente/persona per id (ad es. per rimuovere un dipendente segnaposto/fittizio). Richiede ROLE_EMPLOYEES_MANAGER; il backend esegue un processore di eliminazione che scollega anche i record correlati. Impatto elevato, irreversibile. Scrittura. |
| people_invite | Assegna un LOGIN a una persona esistente: crea un invito organizzativo in sospeso e glielo invia via email, nella lingua UI configurata dall'org. Questo è il passaggio che people_create e people_setPermissionGroups NON fanno — una persona con permission group non può comunque accedere finché non viene invitata e accetta. Richiede l'email della persona; fallisce se ha già un login. Ordine di onboarding: people_create (record) -> people_invite (login) -> people_setPermissionGroups (diritti). Scrittura. |
| people_setPermissionGroups | Imposta (sostituisce) l'INTERO insieme di permission group di una persona tramite id numerici di gruppo (vedi permissionGroups_list — ad es. il gruppo "Business Owner" concede ROLE_ADMIN): passa ogni gruppo con cui deve finire, e [] li rimuove tutti. Concede accesso; NON crea un login né invia email alla persona — per quello c'è people_invite. LA TRAPPOLA: assegnare a qualcuno il suo PRIMO gruppo lo sposta sul modello calcolato, dove i ruoli derivano da gruppi e override per persona, e un ruolo concesso a mano al di fuori di quel modello scompare nella stessa identica chiamata — un ROLE_ADMIN assegnato a una persona è esattamente il tipo che questo rimuove. Vale anche al contrario: rimuovere l'ultimo gruppo la riporta fuori da quel modello e fa riapparire quei ruoli più vecchi. Gli elenchi overridesAdded/overridesRemoved non dicono nulla di tutto questo; descrivono gli override e restano vuoti mentre l'accesso effettivo cambia. Quindi la risposta riporta la differenza tra i ruoli posseduti dalla persona prima di questa chiamata e dopo, come rolesLost e rolesGained — è quella la coppia da leggere una volta che la chiamata ritorna. rolesLost null (non []) significa che lo snapshot preso prima della scrittura non poteva essere letto e il delta è SCONOSCIUTO, con il motivo in roleDeltaUnavailable: il cambio di gruppo è comunque avvenuto, quindi un null non è un certificato di buona salute — ricontrolla con people_getPermissions. Per restituire un ruolo che avrebbe dovuto sopravvivere, concedilo con people_setRoleOverrides. Richiede ROLE_ROLES_MANAGER. Scrittura. |
| people_setRoleOverrides | Imposta (sostituisce) i ruoli che UNA persona ottiene in aggiunta — o si vede tolti — rispetto ai propri permission group. Ricorri prima a un gruppo (people_setPermissionGroups): i gruppi sono l'astrazione prevista e scalano a più di una persona, quindi usa un override solo dove un singolo individuo differisce realmente da ogni gruppo. SOSTITUISCE entrambi gli elenchi per intero, quindi leggi prima people_getPermissions e ripassa ogni override che deve mantenere; omettere un elenco lo azzera. I roles sono costanti ROLE_ — permissionGroups_list mostra quelli già usati da questa org. Un ruolo presente sia in added che in removed viene rifiutato invece che indovinato. Restituisce lo stesso snapshot risolto di people_getPermissions, così puoi confermare il risultato senza una seconda chiamata. NON crea un login — vedi people_invite. Richiede ROLE_ROLES_MANAGER. Scrittura. |
| people_getPermissions | Cosa una persona può effettivamente fare, risolto: i suoi permission group (ciascuno con i ruoli che concede), i suoi override per persona, e gli effectiveRoles in cui i due si combinano. IL modo per verificare se una modifica di accesso è andata a buon fine — people_list mostra un campo roles, ma questo è quello che spiega PERCHÉ possiede quei ruoli e quale leva azionare per cambiarli. Consultalo prima di ogni chiamata a people_setRoleOverrides, perché quello strumento sostituisce gli elenchi di override per intero e qui è dove leggi quelli attuali. staleOverrides sono override-rimossi che non corrispondono più a nessun ruolo concesso da un gruppo, quindi attualmente non fanno nulla. people_list fornisce l'id. Richiede ROLE_ROLES_MANAGER per visualizzare chiunque all'infuori di te stesso. Sola lettura. |
Gruppi di permessi
Strumenti
| permissionGroups_get | Recupera un gruppo di permessi per id, incluse le stringhe ROLE_* che concede. |
| permissionGroups_list | Elenca i gruppi di permessi dell'organizzazione e i ruoli che ciascuno concede — es. il gruppo "Business Owner" concede ROLE_ADMIN. Leggilo prima di people_setPermissionGroups: i ruoli nella risposta sono l'autorità su ciò che un gruppo permette realmente, così non devi mai indovinare dal suo nome. |
| permissionGroups_create | Crea un gruppo di permessi (name obbligatorio; roles = elenco di stringhe ROLE_* concesse). Scrittura. |
| permissionGroups_update | Aggiorna nome, descrizione o ruoli concessi di un gruppo di permessi per id. Scrittura. |
Pipeline
Strumenti
| pipelines_get | Recupera una pipeline di vendita per id. |
| pipelines_list | Elenca le pipeline di vendita. Una pipeline possiede un insieme ordinato di stage — leggili con stages_list filtrato per pipeline. |
Posizioni
Strumenti
| positions_list | Elenca le posizioni — i ruoli nominati (es. "Backend Engineer") che un'allocazione di progetto ricopre. Nessun filtro; Position ha la paginazione disabilitata, quindi questo restituisce sempre l'intero catalogo dei ruoli dell'organizzazione in un'unica chiamata. Ogni elemento è {id, name, roles}. Usalo per risolvere il nome della posizione dietro il positionId di una riga di allocations_list, e per trovare l'id position con cui un import di resourcing deve corrispondere. |
Membri del progetto
Strumenti
| projectMembers_get | Recupera un'appartenenza a progetto per id — il suo employee, project e position. Gli id provengono da projectMembers_list o dall'array projectMembers su projects_get. |
| projectMembers_list | Elenca le appartenenze a progetto — CHI PUÒ VEDERE QUALE PROGETTO. Filtra per project (`/projects/{id}`) per leggere il roster di un progetto, o per employee per leggere ogni progetto raggiungibile da una persona; ogni riga porta il proprio id, l'employee, il project e la position (employee|tech-lead|account-manager|viewer). Consultalo per primo quando qualcuno segnala un progetto mancante dalla propria lista Projects o non può registrare tempo su di esso: un roster vuoto, o un roster senza quella persona, È la spiegazione — la visibilità è appartenenza. È anche la fonte di id per projectMembers_update e projectMembers_delete. Nota che la stessa persona può comparire più volte sullo stesso progetto, una per position. |
| projectMembers_create | Metti una persona SU un progetto (employee + project IRI richiesti, es. "/people/204" e "/projects/243"; position opzionale = employee|tech-lead|account-manager|viewer, default employee). QUESTO È IL CONTROLLO ACCESSI, non un'etichetta: una persona che non è membro non vede affatto il progetto — manca dalla sua lista Projects e non può registrare tempo su di esso — quindi questo è lo strumento che ripristina qualcuno escluso da un progetto. LA POSITION NON È COSMETICA: un utente con un ruolo a livello di progetto vede solo i progetti dove la sua position di appartenenza corrisponde — ROLE_PROJECTS_LEAD corrisponde a tech-lead, ROLE_PROJECTS_VIEWER corrisponde a viewer — quindi dare a un project lead una riga `employee` lo lascia altrettanto cieco che non avere alcuna riga. L'appartenenza NON è a cascata: mettere qualcuno su una cartella padre non gli dà nulla sui progetti sottostanti, quindi un albero di cartelle richiede una chiamata per progetto. La chiave unica è (employee, project, position), il che significa che le position si accumulano invece di sostituirsi — una persona può avere employee E tech-lead sullo stesso progetto come due righe separate, e aggiungere tech-lead a qualcuno che è già employee lì non rimuove né aggiorna la riga employee (usa projectMembers_update per cambiare una position sul posto). Leggi prima le righe attuali con projectMembers_list?project=/projects/{id}, oppure projects_get, il cui array projectMembers riporta l'id di ogni riga. STAI CARICANDO UN INTERO ORGANICO? Esiste una forma bulk — projectMembers_import riconcilia fino a 500 appartenenze in un'unica chiamata, salta quelle già registrate così è sicuro rieseguirlo, e ha la notifica disattivata per default — ma NON È DISPONIBILE SU QUESTA CONNESSIONE: è servito solo allo scope internal, quindi non puoi chiamarlo qui e cercarlo non lo troverà. Esegui questo strumento in ciclo, oppure chiedi al tuo operatore Flowtly di eseguire il caricamento bulk. NON SILENZIOSO: aggiungere una persona che non è ancora sul progetto le invia una notifica di assegnazione al progetto, quindi un backfill su 17 progetti invia 17 notifiche. Richiede ROLE_PROJECTS_MANAGER. Scrittura. |
| projectMembers_update | Cambia la position di un'appartenenza esistente per id (employee|tech-lead|account-manager|viewer) — ottieni l'id da projectMembers_list o dall'array projectMembers su projects_get. Usalo per promuovere o retrocedere SUL POSTO; usa projectMembers_create per aggiungere una seconda position, aggiuntiva rispetto a quella già posseduta. Cambiare una position può REVOCARE la visibilità del progetto a qualcuno il cui ruolo è a livello di progetto (un ROLE_PROJECTS_LEAD retrocesso da tech-lead a employee smette di vederlo). Non può spostare un'appartenenza su un'altra persona o progetto — per quello elimina e ricrea. Richiede ROLE_PROJECTS_MANAGER. Scrittura. |
| projectMembers_delete | Togli una persona DA un progetto tramite l'id di appartenenza — trovalo con projectMembers_list o nell'array projectMembers di projects_get. QUESTO REVOCA L'ACCESSO: una volta che l'ultima riga di appartenenza per quella persona su quel progetto è sparita, il progetto scompare dalla sua vista e non può più registrare tempo su di esso, il che è esattamente come un progetto svanisce silenziosamente per qualcuno. Le ore già registrate NON vengono eliminate e restano sul progetto; la persona semplicemente non può più vederle o aggiungerne. Eliminare una position lascia intatta qualsiasi altra position che la stessa persona possiede sullo stesso progetto. Richiede ROLE_PROJECTS_MANAGER. Irreversibile (ricreare crea una nuova riga e rinotifica), alto impatto. Scrittura. |
Progetti
Strumenti
| projects_costAllocations | Come i costi sono stati ripartiti SU questo progetto — quali transactions e righe fattura gli sono state attribuite, e in quale quota. Usalo per spiegare una cifra di profittabilità invece di limitarti a citarla: è qui che un risultato inatteso viene ricondotto al documento che lo ha causato. Richiede ROLE_TRANSACTIONS_MANAGER. Sola lettura. |
| projects_folderCounts | Quanti progetti si trovano in ciascuna CARTELLA di progetti, come folderId + total + active. Il folderId è un id di tagDefinition — risolvi i nomi con tagDefinitions_list e individua quali gruppi sono gruppi di cartelle con tagGroups_list (allowedRelations contiene "project"). Un folderId nullo è il contenitore dei non categorizzati. Conta solo i progetti radice, poiché le cartelle raggruppano le radici e le fasi seguono il progetto padre. Sola lettura. |
| projects_get | Recupera un progetto per id — nome, tipo, cliente, date, descrizione e prezzo. |
| projects_list | Elenca i progetti. Filtra per type (fixed-price | time-and-material | non-billable | internal), client.name, employee, name, oppure per intervalli di dateFrom/dateTo. Usalo per ottenere l'id project richiesto da attività, registrazione delle ore lavorate, budget e contratti. |
| projects_profitability | IL RISULTATO PER PROGETTO — quanto un progetto ha guadagnato rispetto a quanto è costato. È il numero che un'attività di servizi o sviluppo cerca solitamente di vedere, e quello che ogni altro strumento di progetto alimenta. Passa l'id del progetto da projects_list. Richiede ROLE_ACCOUNT_MANAGER. Sola lettura. |
| projects_create | Crea un progetto (name + type obbligatori; type = fixed-price|time-and-material|non-billable|internal; opzionali dateFrom/dateTo, client, publicDescription, notes, priceNet). Scrittura. |
| projects_update | Aggiorna un progetto per id (name, type, date, descrizione, ecc.). Scrittura. |
| projects_archive | Archivia un progetto tramite id — il modo per ritirare un progetto che non può essere eliminato perché ha tempo registrato, fatture o budget collegati. Reversibile con projects_unarchive. Preferibile a retrodatare dateTo, che fa solo sembrare concluso il progetto. Scrittura. |
| projects_unarchive | Ripristina un progetto archiviato tramite id, annullando projects_archive. Scrittura. |
Modelli di progetto
Strumenti
| projectTemplates_get | Recupera un template di progetto per id, incluso il suo documento structure completo. projectTemplates_list trova l'id. Leggilo prima di projectTemplates_update — la structure viene scritta PER INTERO, quindi un update deve inviare il documento completo, non un frammento. Sola lettura. |
| projectTemplates_list | Elenca i template di progetto dell'org — blueprint riutilizzabili di un progetto, le sue fasi, le sue liste di task e i suoi task. Consultalo PRIMA di projects_create quando lo stesso tipo di progetto viene creato ripetutamente (un tipo di incarico, un audit, un onboarding): istanziare un template costruisce l'intero albero in un'unica chiamata, mentre projects_create crea un progetto vuoto che poi devi riempire a mano. La riga contrassegnata isDefault è il template predefinito dell'org, applicato a un progetto creato senza scegliere un template. Sola lettura. |
| projectTemplates_create | Crea un blueprint di progetto riutilizzabile a partire da un documento structure (version, project, phases, e le loro lists/tasks). Gli offset al suo interno sono RELATIVI — startOffsetDays e durationDays sono contati in giorni a partire dallo startDate fornito al momento dell'istanziazione, quindi un template serve ogni avvio futuro. Il project.name nella structure è un placeholder; sovrascrivilo per cliente al momento dell'istanziazione. La structure viene validata lato server rispetto allo schema della sua version dichiarata, e una violazione indica il JSON pointer incriminato. Scrittura. |
| projectTemplates_update | Aggiorna un template di progetto per id. La colonna structure viene memorizzata e sostituita PER INTERO, mai unita — invia il documento completo o le parti che ometti spariranno. Leggi prima quello attuale con projectTemplates_get. Cambiare un template NON tocca i progetti già istanziati da esso; non c'è back-propagation. Scrittura. |
| projectTemplates_delete | Elimina un template di progetto per id. Soft delete, e NON tocca i progetti già creati dal template — quelli sono progetti ordinari e continuano a esistere. Scrittura. |
| projectTemplates_instantiate | Costruisci un progetto reale a partire da un template — il progetto, le sue fasi, le sue liste di task e ogni task, in UNA chiamata atomica. startDate è richiesto ed è l'ancora rispetto a cui si risolve ogni startOffsetDays nel template. Passa name per sovrascrivere il nome placeholder del progetto del template, e client per collegare il nuovo progetto a un cliente: istanziare due volte sullo STESSO client è come un cliente finisce per avere più incarichi, ciascuno il proprio progetto. Restituisce il progetto creato. Scrittura. |
Candidati per richieste di risorsa
Strumenti
| resourceRequestCandidates_get | Un candidato per il recruitment per id. L'id proviene da resourceRequestCandidates_list. Richiede ROLE_HR_MANAGER. Sola lettura. |
| resourceRequestCandidates_list | I candidati proposti per le richieste di assunzione — persone in una pipeline di recruitment, non dipendenti disponibili per l'allocazione. Filtra per l'id della richiesta da resourceRequests_list. Richiede ROLE_HR_MANAGER. Sola lettura. |
Richieste di risorse
Strumenti
| resourceRequests_get | Una richiesta di assunzione per id, con la sua posizione e stato. Ottieni l'id da resourceRequests_list. HR/recruitment, non allocazione di resourcing. Richiede ROLE_HR_MANAGER. Sola lettura. |
| resourceRequests_list | Richieste di assunzione aperte — una richiesta di reclutare per una posizione, nel dominio HR. Nonostante il nome NON è domanda di allocazione di resourcing: è recruitment. Restituisce la collezione; resourceRequests_get legge una, e resourceRequestCandidates_list fornisce le persone proposte per essa. Richiede ROLE_HR_MANAGER. Sola lettura. |
Richieste di Resourcing
Strumenti
| resourcingRequests_list | Richieste di resourcing aperte — qualcuno che chiede che una persona venga allocata a un progetto, che è il lato della domanda nel resourcing. Questo è il flusso che la vista Requests dell'UI di Resourcing rende. NON confonderlo con resourceRequests_list: quello è RECRUITMENT HR (assunzione per una posizione). Abbinalo a resourcingRequestsHistory_list per ciò che è già stato deciso, e a resourcingBench_get per chi potrebbe soddisfare una richiesta. Richiede il modulo resourcing e ROLE_RESOURCING_MANAGER. Sola lettura. |
Storico richieste di Resourcing
Strumenti
| resourcingRequestsHistory_list | Cosa è già successo alle richieste di resourcing — la traccia delle decisioni (confermate, rifiutate, modificate) dietro le richieste aperte in resourcingRequests_list. Usalo per rispondere a 'questo era già stato chiesto e rifiutato?' prima di proporre di nuovo la stessa allocazione. Richiede il modulo resourcing e ROLE_RESOURCING_MANAGER. Sola lettura. |
Responsabilità
Strumenti
| responsibilities_get | Recupera una responsabilità per id. |
| responsibilities_list | Elenca le responsabilità all'interno di un gruppo RACI. Filtra per responsibilityGroup. Le responsabilità possono essere annidate tramite parent; le persone vi vengono assegnate tramite responsibilityEmployees, non direttamente. |
| responsibilities_create | Crea una responsabilità all'interno di un gruppo (responsibilityGroup = id o IRI del gruppo, + name, richiesti; description opzionale; parent opzionale = un altro IRI responsibility per l'annidamento). Assegna persone ad essa tramite responsibilityEmployees_create. Scrittura. |
| responsibilities_update | Aggiorna una responsabilità per id (name, description, parent, responsibilityGroup = id gruppo o IRI). Scrittura. |
Dipendenti responsabilità
Strumenti
| responsibilityEmployees_get | Recupera un'assegnazione di responsabilità per id. |
| responsibilityEmployees_list | Elenca chi è assegnato a quale responsabilità, e con quale percentuale. Filtra per employee per leggere l'intero carico RACI di una persona su tutti i gruppi. |
| responsibilityEmployees_create | Assegna un dipendente a una responsabilità (responsibility = id responsabilità o IRI, employee = id employee o IRI, percentage 0-100, tutti obbligatori; opzionali targets e description). Scrittura. |
| responsibilityEmployees_update | Aggiorna un'assegnazione di responsabilità per id (percentage, targets, description). Scrittura. |
| responsibilityEmployees_delete | Rimuove l'assegnazione di un dipendente da una responsabilità per id. Scrittura. |
Gruppi di responsabilità
Strumenti
| responsibilityGroups_get | Recupera un gruppo di responsabilità per id. |
| responsibilityGroups_list | Elenca i gruppi di responsabilità / aree RACI — le voci di primo livello "Odpowiedzialności", ciascuna con una persona responsabile (accountable). Le singole responsabilità sono annidate sotto di esse. |
| responsibilityGroups_create | Crea un gruppo di responsabilità / area RACI (nome richiesto; description e responsibleEmployee opzionali = la persona responsabile, indicata come id dipendente semplice come 6 (da people_list) o l'IRI /people/6). Questo è l'elemento di primo livello 'Odpowiedzialności'. Aggiungi responsabilità individuali sotto di esso tramite responsibilities_create. Scrittura. |
| responsibilityGroups_update | Aggiorna un gruppo di responsabilità per id (name, description, responsibleEmployee = id employee o IRI). Scrittura. |
Dipendenti del turno
Strumenti
| scheduleEmployees_get | Un'assegnazione schedule-dipendente per id. L'id proviene da scheduleEmployees_list. Richiede ROLE_SCHEDULES_MANAGER. Sola lettura. |
| scheduleEmployees_list | Quali dipendenti sono assegnati a quali orari di lavoro. Usalo per passare da uno schedule (schedules_list) alle sue persone, o per trovare lo schedule seguito da un dato dipendente. Richiede ROLE_SCHEDULES_MANAGER. Sola lettura. |
Piano dei turni
Strumenti
| schedulePlan_list | Gli orari in vigore in UNA data specifica — passa la data nel path. Usalo per rispondere a 'chi sta lavorando oggi / in questa data' senza leggere ogni schedule e risolvere i suoi intervalli da solo. A differenza delle altre letture di schedule questo richiede solo ROLE_USER, quindi è quello disponibile a un dipendente ordinario. Sola lettura. |
Intervalli orari
Strumenti
| scheduleRanges_get | Un intervallo orario di schedule per id. L'id proviene da scheduleRanges_list. Richiede ROLE_SCHEDULES_MANAGER. Sola lettura. |
| scheduleRanges_list | Gli intervalli orari che compongono gli orari di lavoro — le ore effettive coperte da uno schedule. Leggi prima il genitore con schedules_get; questo espande i suoi intervalli. Richiede ROLE_SCHEDULES_MANAGER. Sola lettura. |
Turni
Strumenti
| schedules_get | Un orario di lavoro per id, con i suoi intervalli e i dipendenti assegnati. L'id proviene da schedules_list; scheduleRanges_list e scheduleEmployees_list leggono le sue parti. Richiede ROLE_SCHEDULES_MANAGER. Sola lettura. |
| schedules_list | Orari di lavoro — i pattern di turno/lavoro definiti da un'organizzazione, NON allocazione di progetto. Usa resourcingSchedule_get per chi è prenotato su cosa; usa questo per i pattern di lavoro stessi. schedules_get legge uno per id. Richiede ROLE_SCHEDULES_MANAGER. Sola lettura. |
Fasi
Strumenti
| stages_get | Recupera una fase trattativa per id. |
| stages_list | Elenca gli stage di un affare, in ordine. Filtra per pipeline. deals_create richiede un id stage da qui, e spostare un affare tra stage è ciò che dealStageHistories registra. |
Fornitori
Strumenti
| suppliers_list | Elenca i fornitori — serviti da /contractors, quindi "supplier" e "contractor" sono lo stesso record. Filtra per cyclic per i fornitori ricorrenti. Usalo per ottenere il supplier a cui è associato un costo, un contratto o una fattura in entrata. |
| suppliers_create | Crea un nuovo record fornitore (name, tinType, costGroup obbligatori). Scrittura. |
| suppliers_update | Aggiorna i dati di un fornitore (nome, partita IVA, termini di pagamento, ecc.) per id. Scrittura. |
Definizioni di tag
Strumenti
| tagDefinitions_list | Elenca le definizioni di tag — i tag che possono essere associati ai record, ciascuno all'interno di un tag group. tags_create richiede un id tagDefinition da qui più il record a cui associarlo. |
| tagDefinitions_create | Crea una definizione di tag (name, level, tagGroup obbligatori) all'interno di un gruppo di tag. Quando allowedRelations del gruppo contiene "project", ogni definizione qui È una cartella di progetti — questo è lo strumento che ne crea una. Scrittura. |
Gruppi di tag
Strumenti
| tagGroups_list | Elenca i gruppi di tag — i contenitori che organizzano le definizioni di tag. |
| tagGroups_create | Crea un gruppo di tag (nome obbligatorio) per organizzare definizioni di tag correlate. È anche il modo in cui si crea un contenitore CARTELLA PROGETTI: passa allowedRelations: ["project"] e le definizioni del gruppo diventano cartelle nell'elenco dei progetti. Un gruppo con allowedRelations vuoto è universale e NON viene trattato come cartella. Scrittura. |
Commenti attività
Strumenti
| taskComments_list | Elenca i commenti sulle attività di progetto, dal più vecchio. Filtra per task per leggere la discussione di una singola attività. |
| taskComments_create | Aggiunge un commento a un'attività di progetto (id task + content). Scrittura. |
Elenchi di attività
Strumenti
| taskLists_list | Elenca le liste di task — le colonne/sezioni della board in cui i task sono archiviati. Filtra per progetto. tasks_create richiede un id list da qui. |
Attività
Strumenti
| tasks_get | Recupera un'attività di progetto per id — titolo, progetto, stato, elenco, assegnatari, date e ricorrenza. |
| tasks_list | Elenca i task di progetto. Filtra per progetto, list, status, assegnatari, isTemplate o intervalli startAt/dueAt. I task ricorrenti espongono recurrenceParent e recurrenceRule, così un'occorrenza generata può essere ricondotta alla regola che l'ha prodotta. Per decidere se un task è COMPLETATO, confronta il suo status con taskStatuses_list (isClosed) invece di confrontare il nome dello status. |
| tasks_create | Crea un'attività di progetto (title + project obbligatori; opzionali status, list, assignees, dueAt, priority). Scrittura. |
| tasks_update | Aggiorna un task di progetto per id — cambia status (incl. contrassegnare come completato), assignees, dueAt, title, ecc., oppure SPOSTA il task su un altro progetto passando `project` (re-parenting; la task list viene azzerata a meno che tu non indichi anche una `list` nel progetto di destinazione, perché una list appartiene a un solo progetto). Scrittura. |
Stati attività
Strumenti
| taskStatuses_list | Elenca gli stati delle attività di progetto, nell'ordine della board. isClosed contrassegna gli stati di completamento e isDefault lo stato assegnato a una nuova attività. Consultalo prima di interpretare lo status di un'attività — i nomi sono configurabili a livello di organizzazione, quindi "Done" non è una stringa affidabile su cui fare corrispondenza. |
Gruppi fiscali
Strumenti
| taxGroups_list | Elenca i tax group. Usalo per risolvere l'id taxGroup su cui filtra taxRules_list e che le righe fattura portano. |
| taxGroups_create | Crea un gruppo fiscale (name + type obbligatori). Scrittura. |
| taxGroups_update | Aggiorna il nome o il tipo di un gruppo fiscale per id. Scrittura. |
Regole fiscali
Strumenti
| taxRules_list | Elenca le regole fiscali — le aliquote e i periodi a cui si applicano. Filtra per taxGroup. |
| taxRules_create | Crea una regola fiscale. Scrittura. |
| taxRules_update | Aggiorna una regola fiscale per id. Scrittura. |
Transazioni
Strumenti
| transactions_list | Elenca le transazioni bancarie — il flusso bancario a cui vengono abbinate le fatture in entrata. Filtra per bankAccount, counterpartyRole, cost, ignored, hasDetectedProblems, un intervallo orderDate/execDate o amount.between. Nota che orderDate ed execDate sono diversi: un pagamento può essere disposto in un mese ed eseguito nel successivo. |
| transactions_suggestions | Legge le proposte di Flowtly per una transazione bancaria — a quale controparte, cost group o documento dovrebbe essere archiviata. L'immagine speculare di incomingInvoices_suggestions, dal lato del denaro. |
| transactions_importStatement | Importa un file di estratto conto bancario (es. un file MT940 .sta) — passa il contenuto testuale grezzo di ogni file letteralmente (NON base64) con un filename. NON C'È UN PARAMETRO bankAccount: il backend instrada un file rimuovendo tutti i caratteri non numerici dai numeri dei tuoi conti bancari e dai byte del file, e importando in ogni conto le cui cifre appaiono ovunque nel file — quindi un file può finire in più conti, e un estratto per un conto non configurato in Flowtly (o il cui numero è registrato diversamente da come lo scrive la banca) non viene importato in nessuno di essi, fallendo con un errore che spiega esattamente il motivo — leggi quel messaggio, è l'unico strumento diagnostico che questo endpoint fornisce. In caso di successo la risposta è `{ imported, matching }`: `matching: "in_progress"` significa che il matching di contraente/allegato per le nuove righe è ancora in esecuzione dopo che questa chiamata ritorna, quindi una transactions_list immediata potrebbe mostrare righe non ancora abbinate — rileggi un po' più tardi per lo stato finale. Reimportare lo stesso estratto non crea righe duplicate; l'importer riconosce le transazioni già viste. Una volta che un estratto è dentro, punta un pagamento esistente senza riga bancaria a una delle sue righe con invoiceTransactions_update. Scrittura. |
| transactions_delete | Elimina una transazione bancaria tramite id — trovala con transactions_list. Ricorri a questo SOLO per annullare un errore contabile non correggibile in altro modo: un estratto conto importato sul conto bancario sbagliato, o righe inserite a mano prima dell'arrivo dell'estratto reale e ora da esso duplicate. Una transazione è la registrazione di ciò che ha fatto la banca, quindi eliminarne una su un conto importato fa divergere la contabilità dalla banca; il backend lo consente solo a ROLE_ADMIN (un responsabile delle transazioni può eliminare unicamente su conti cassa e manuali). PRIMA di eliminare un sospetto duplicato, dimostra la coppia: abbina la riga importata per importo E numero di fattura E controparte, non per il solo importo — un incasso arrivato dopo la data di fine dell'estratto non ha corrispettivo, ed eliminarlo distrugge l'unica traccia di quel ricavo. Il backend SCOLLEGA anziché eliminare ciò che vi dipende: i pagamenti delle fatture sopravvivono con la riga bancaria svuotata (riassegnali con invoiceTransactions_update), allegati e immobili vengono scollegati, mentre le righe di transazione di progetto e dipendente vengono rimosse insieme a essa. Irreversibile, ad alto impatto. Scrittura. |
Ore lavorate
Strumenti
| workTimes_get | Recupera una singola voce di ore lavorate per id — data, minuti, progetto, note e il dipendente a cui appartiene. |
| workTimes_list | Elenca le voci di ore lavorate (registrate). Filtra per intervallo di date (date.after / date.before, YYYY-MM-DD) ed eventualmente per employee o project; pagina con cursor. Ogni riga riporta employeeId/employeeName e projectId/projectName, quindi è così che esporti tutte le ore registrate per un periodo. IMPORTANTE: i risultati a livello di organizzazione richiedono ROLE_WORKING_HOURS_VIEWER. Senza questo ruolo il backend NON restituisce un errore — restituisce silenziosamente solo le voci dell'utente connesso, quindi un'esportazione "ore di tutti" può tornare contenendo una sola persona e sembrare comunque corretta. Se ogni riga appartiene a un solo dipendente e non hai filtrato per employee, la risposta include uno scopeWarning che lo segnala — mostralo all'utente invece di presentare il risultato come a livello di organizzazione. |
| workTimes_log | Registra una voce di tempo lavorato per l'utente Flowtly connesso (date, durationMinutes, project, notes). LA NOTA DEVE SUPERARE IL CONTROLLO ANTI-DESCRIZIONE-SCARNA DEL SERVER, che un backfill in batch incontra ripetutamente: richiede O circa 32 caratteri (la soglia esatta è un'impostazione per organizzazione, e un'org può impostarla a 0 per disattivare il controllo) O un riferimento a ticket "#" O un link http(s) — uno qualsiasi basta. "Flowtly – Scallier" viene rifiutato; "Flowtly – Scallier #FLOW-123" no. Il 422 indica il propertyPath `description`, il nome lato server del campo che questo strumento chiama `notes`. Scrittura. |
| workTimes_update | Correggi una voce di tempo lavorato registrata, per id — la sua date, minutes, project o description. È così che una voce archiviata erroneamente viene SPOSTATA tra progetti: workTimes_log crea soltanto, quindi senza questo un progetto sbagliato o un errore di battitura nella description è permanente. Leggi prima la voce con workTimes_get. Si applica lo stesso controllo anti-descrizione-scarna di workTimes_log: circa 32 caratteri — la soglia è un'impostazione per organizzazione e può essere 0, che lo disabilita — O un riferimento a ticket "#" O un link http(s), uno qualsiasi dei tre. Scrittura. |
| workTimes_delete | Elimina una voce di tempo lavorato registrata, per id. Per un duplicato o una voce registrata su un lavoro mai svolto — preferisci workTimes_update quando la voce è reale ma sbagliata, così le ore restano nel record invece di sparire da esso. Le ore registrate alimentano le finanze e l'utilizzo del progetto, quindi una delete cambia silenziosamente i numeri riportati per un periodo passato. Scrittura. |
Contatti cliente
Strumenti
| clientContacts_create | Crea una persona di contatto per un cliente (client, type, name, email obbligatori). Scrittura. |
Conti bancari controparte
Strumenti
| counterpartyBankAccounts_create | Associa un conto bancario a una controparte (counterparty + accountNumber). Scrittura. |
Righe piano pagamenti
Strumenti
| paymentScheduleLines_import | Carica l'intero piano rate di un contratto in un'unica chiamata, invece di un round trip per riga. Costruito per i contratti sviluppatore, che vengono pagati in tranche di costruzione — una singola vendita è da sei a dodici rate, e un registro di esse è centinaia. Ogni riga indica il proprio contratto PER NAME (per un contratto sviluppatore importato, il suo numero di accordo), una due date, e un amount in UNITÀ MINORI — grosze, quindi 5 300,00 è "530000" e "5300" registra silenziosamente 53,00. Le righe si riconciliano rispetto alle righe già presenti su contract+date+amount+note, quindi una riga sconosciuta viene creata, una identica viene saltata, e rieseguire lo stesso batch non cambia nulla; PaymentScheduleLine non ha una colonna di riferimento esterno, quindi quella chiave naturale è la chiave di riconciliazione. Una riga il cui contract name non corrisponde a nulla, o corrisponde a PIÙ di un contratto, viene segnalata come fallita invece che collegata a un'ipotesi — mettere una rata sul contratto sbagliato falsa due flussi di cassa contemporaneamente. Passa prima dryRun:true su un caricamento reale. Massimo 1000 righe. Scrittura. |
| paymentScheduleLines_create | Aggiungi una rata al piano di pagamento di un contratto — il piano di cosa ci si aspetta venga fatturato o pagato, e quando. Passa l'IRI del contratto, una date e un amount. Questo risolve il problema di piano-di-pagamento-mancante che contracts_get segnala su un contratto non ciclico: anche una tariffa una tantum ha un piano, è semplicemente un'unica riga per l'intero importo nel giorno in cui scade. I contratti ciclici non vengono controllati per averne uno, perché il sistema non genera automaticamente righe da una cadenza. L'AMOUNT È IN UNITÀ MINORI — grosze, non złote: 5 300,00 è "530000", e "5300" registra silenziosamente una riga da 53,00. L'API le restituisce nello stesso modo, quindi rileggine una con contracts_paymentScheduleLines se non sei sicuro della scala. Rileggi il risultato con contracts_paymentScheduleLines. Scrittura. |
| paymentScheduleLines_update | Modifica una riga del piano di pagamento per id — la sua date, amount o note. Usalo quando una rata slitta o viene rinegoziata, invece di eliminare e ricreare, così la riga mantiene qualsiasi fattura già abbinata a essa. L'AMOUNT È IN UNITÀ MINORI — grosze, non złote: 5 300,00 è "530000", e "5300" registra silenziosamente una riga da 53,00. L'API le restituisce nello stesso modo, quindi rileggine una con contracts_paymentScheduleLines se non sei sicuro della scala. Scrittura. |
| paymentScheduleLines_delete | Rimuovi una riga del piano di pagamento per id. Elimina il PIANO, non il denaro: una fattura o transazione già abbinata alla riga non ne è influenzata, ma smette di essere riconciliata con qualcosa. Preferisci paymentScheduleLines_update per una rata che si è spostata. Scrittura. |
Logo organizzazione
Strumenti
| organizationLogo_upload | Carica/sostituisce il logo dell'organizzazione (immagine base64 + contentType + filename). Leggi quello attuale tramite configs_get organization-logo-url. Scrittura. |
Icona organizzazione
Strumenti
| organizationIcon_upload | Carica/sostituisce l'icona/favicon dell'organizzazione (immagine base64 + contentType + filename). Leggi quella attuale tramite configs_get organization-icon-url. Scrittura. |
Archiviazione
Strumenti
| storage_upload | Allega un file a qualsiasi record che lo storage generico di Flowtly accetta — un ASSET (relationName "property"), un progetto, un task, un client, una location, un fornitore, una fattura. Questa è l'unica via per un'IMMAGINE di asset: caricare con relationName "property" imposta l'immagine mostrata dall'app per quell'asset (servita come `file` nel payload dell'asset). Property non ha una colonna immagine -- l'immagine viene derivata da questa tabella al momento della lettura, motivo per cui nulla sull'entità lascia intuire che esista. È UN SOLO slot e l'upload più recente vince, quindi una seconda immagine sostituisce la prima invece di aggiungersi a una galleria. Lo stesso vale per location, invoices e transaction-attachments; clients, agreements e candidates invece accumulano ogni upload sotto `files`. OGNI ALTRA RELAZIONE COLLEGA L'UPLOAD A NULLA DI VISIBILE, e relationName "employees" è quella a cui fare attenzione: memorizza i byte e NON crea alcun Document, quindi People > Documents resta vuoto e il payload del dipendente non riporta alcun file. La rotta /documents su qualsiasi record restituisce entità Document, e un upload non ne crea nessuna — ed è così che PDF firmati di NDA ed ESOP sono stati segnalati come archiviati mentre la scheda Documents non mostrava nulla (#255). Un vero documento del dipendente richiede POST /documents con un DocumentType il cui relationName è `employee`, l'id del dipendente e l'IRI della riga Storage che questa chiamata restituisce. NON ASSEMBLARLO A MANO: usa employeeDocuments_createUploadTicket, che esegue tutti e tre i passaggi — memorizza i byte, crea il Document e lo rilegge tramite /people/{id}/documents — e riporta stored / linked / verified separatamente. Questo strumento si ferma ai byte. Non ricorrere nemmeno ad agreementTypes.*: un AgreementType è il tipo di un CONTRATTO di lavoro (Umowa o pracę, Umowa zlecenie) sotto Ludzie > Umowy, e non è un DocumentType. Riporta byte memorizzati, record di business collegato e visibilità verificata come tre affermazioni separate, e asserisci solo quelle che hai effettivamente fatto. `file` viene omesso dalle risposte LIST a meno che la richiesta non passi ?include=file, quindi rileggi un record per confermare che l'immagine sia arrivata. Passa relationName + relationId (l'id dallo strumento list di quel record; un IRI /assets/7 è accettato e ridotto) più i byte in base64 con un contentType e un filename. LIMITE DI DIMENSIONE: i byte viaggiano come base64 all'interno di questa chiamata, quindi mantienili sotto circa 150 KB — le fotografie superano quasi sempre questa soglia, e per quelle usa storage_createUploadTicket, che non ha limiti. I permessi sono quelli richiesti per modificare il record PROPRIETARIO: il backend risolve relationName in quell'entità e interroga il suo voter, quindi archiviare su un asset richiede il permesso assets, su un client quello clients. Per un contratto, preferisci invece contractAttachments_create — risolve anche contracts.problem_missing_document, cosa che questo non fa. Scrittura. |
| storage_createUploadTicket | Genera un ticket di breve durata e a uso singolo per allegare un file GRANDE a qualsiasi record — il modo in cui le IMMAGINI di asset entrano realmente, dato che un'immagine supera sempre il limite del base64. Su property/location/invoices/transaction-attachments l'upload più recente diventa l'immagine visibile del record, sostituendo la precedente; su clients/agreements/candidates gli upload si accumulano. Usa questo invece di storage_upload ogni volta che il file supera qualche decina di KB: quello strumento porta i byte come base64, che un chiamante deve emettere come testo, e un JPEG da 400 KB diventa ~533 K caratteri base64, ben oltre ciò che entra in una risposta. Passa relationName + relationId più un filename; ricevi indietro un uploadUrl e un curl pronto all'uso. Poi invia i BYTE GREZZI del file a quell'URL (curl --data-binary @photo.jpg) — non base64, non multipart — e la risposta porta il record Storage creato. Il ticket scade dopo 15 minuti, funziona una volta, e può archiviare solo contro il record che indica. Scrittura. |
Allegati contratto
Strumenti
| contractAttachments_create | Allega un documento a un contratto — normalmente il PDF firmato, o un annesso (DPA, SLA, price annex) archiviato insieme a esso. Passa i byte come base64 con un fileName e il contract id da contracts_list; `contractId` qui è un id NUDO, a differenza degli IRI che contracts_update richiede per counterparty e project, sebbene un IRI completo /contracts/<id> venga accettato e ridotto. LIMITE DI DIMENSIONE: i byte viaggiano come base64 all'interno di questa chiamata, quindi l'intero documento deve entrare in una singola risposta del modello — mantienilo sotto circa 150 KB, e per qualsiasi cosa più grande usa invece contractAttachments_createUploadTicket, costruito esattamente per questo e senza tale limite. Un contratto firmato con una scheda firma è di solito ben oltre quella soglia (673.617 byte diventano 898.156 caratteri base64, diverse volte ciò che una risposta può portare), e non torna alcun errore quando non entra, perché la chiamata non può essere emessa affatto — la richiesta non raggiunge mai il server, quindi controlla la dimensione del file PRIMA di iniziare invece di scoprirlo tramite un fallimento. Questo risolve il problema di documento-mancante che contracts_get segnala, così un contratto mantenuto tramite l'API smette di restare nella coda di sistemazione dell'app. Un documento firmato può coprire più righe di contratto (un accordo con una parte ricorrente e una una tantum è due righe, perché `cyclic` è per record) — chiama questo una volta per ogni contract id con gli stessi byte. Ciò che accade dopo dipende da kind. kind "contract": `status` torna come "analyzing" e il backend legge il documento in modo asincrono, normalmente entro pochi minuti; interroga contracts_get finché l'allegato non è "analyzed" o "failed" (un fallimento riporta failureReason e failureRetryable). La lettura RIEMPIE SOLO i campi VUOTI del contratto e non sovrascrive mai un nome, una direzione, un importo, date, valuta, termini di pagamento, righe di pianificazione o prezzi già presenti; ogni valore estratto resta nell'analysisSummary dell'allegato, e analysisSummary.notApplied elenca ciò che ha lasciato come suggerimento. kind "annex": memorizzato e NON analizzato; `status` è "stored", che è definitivo, e il contratto non cambia. Tratta analysisSummary come un SUGGERIMENTO da verificare piuttosto che un fatto di cui fidarsi. Scrittura. |
| contractAttachments_createUploadTicket | Genera un ticket di breve durata e a uso singolo per allegare un documento GRANDE a un contratto — il PDF firmato, o un annesso. Usa questo invece di contractAttachments_create ogni volta che il file supera qualche decina di KB: quello strumento porta i byte come base64, che un chiamante deve emettere come testo, e un vero contratto firmato (~700 KB, ~900 K caratteri base64) è ben oltre ciò che entra in una risposta. Passa il contract id da contracts_list più un fileName; ricevi indietro un uploadUrl e un curl pronto all'uso. Poi invia i BYTE GREZZI del file a quell'URL (curl --data-binary @file.pdf) — non base64, non multipart — e la risposta è l'allegato creato. Il ticket scade dopo 15 minuti, funziona una volta, e può allegare solo al contratto che indica. Questo risolve il problema di documento-mancante che contracts_get segnala. Scrittura. |
Transazioni fattura
Strumenti
| invoiceTransactions_create | Registra un pagamento a fronte di una fattura in uscita (vendite). `invoice` è un IRI fattura da invoices_list; `date` è quando il pagamento è considerato effettuato. `transaction` è opzionale — omettilo per registrare la liquidazione senza una riga bancaria, ciò che serve per fatture storiche il cui estratto conto non è mai stato importato. `amount` è opzionale e per default è l'importo residuo della fattura. Registrare un pagamento è ciò che impedisce che una fattura emessa e scaduta sia trattata come non pagata, quindi è anche ciò che impedisce che vengano accodati promemoria di pagamento per essa. Nulla impedisce di registrare due pagamenti sulla stessa fattura, quindi leggi prima invoices_get se non sei sicuro che ne sia già stata registrata una. Scrittura. |
| invoiceTransactions_update | Aggiorna un record di pagamento fattura esistente per id (da invoiceTransactions di invoices_get, o paginando invoiceTransactions). L'uso più comune: puntare un pagamento registrato senza riga bancaria a una transazione appena importata tramite transactions_importStatement, impostando `transaction` su un IRI/id transazione da transactions_list. IL TRABOCCHETTO: questa è una PATCH, ma il backend richiede comunque `invoice` e `date` a ogni chiamata — NON unisce i valori esistenti per te. Leggi prima il record (o averlo già dalla chiamata di creazione) e reinvia i suoi `invoice` e `date` invariati insieme a qualsiasi cosa tu voglia realmente cambiare, altrimenti l'aggiornamento viene rifiutato. `transaction` accetta null per scollegare un pagamento da una riga bancaria. `amount` è opzionale. Scrittura. |
| invoiceTransactions_delete | Elimina una registrazione di pagamento da una fattura tramite id — gli id si leggono da invoiceTransactions di invoices_get. Rimuove LA REGISTRAZIONE CHE UNA FATTURA È STATA PAGATA, non una transazione bancaria: usala quando una fattura porta un pagamento che non sarebbe mai dovuto esistere, il caso tipico essendo lo stesso pagamento contabilizzato due volte — una a mano e una dall'importazione dell'estratto conto che poi lo ha riconciliato. Controlla prima invoices_get ed elimina la registrazione la cui `transaction` è quella sbagliata (mantieni quella che punta alla vera riga bancaria importata); eliminando l'ultimo pagamento rimasto la fattura torna non pagata, il che riattiva i solleciti di pagamento. Richiede ROLE_INVOICES_MANAGER. Irreversibile, ad alto impatto. Scrittura. |
Resourcing
Strumenti
| resourcing_importTimeline | Importa un foglio di timeline di allocazione resourcing (recuperalo tramite l'MCP Drive, passa il suo CSV letteralmente). Questo è uno specchio a SOSTITUZIONE COMPLETA delle righe Allocation dell'organizzazione per `year`: le righe nel foglio vengono create/aggiornate, e qualsiasi riga esistente per quell'anno assente dal foglio viene ELIMINATA — non è un merge. DRY-RUN PER DEFAULT: un dryRun omesso mostra un'anteprima e non scrive nulla; passa dryRun:false per applicare. Il report fornisce `created` / `replaced` più `unmatchedPeople` / `unmatchedProjects`. DUE COSE SONO FACILI DA PERDERE: una riga del foglio il cui progetto non si risolve viene SALTATA mentre la chiamata riporta comunque successo, quindi un risultato verde può nascondere un import parziale; e un codice ruolo che il catalogo posizioni non possiede già viene CREATO come nuova posizione invece di essere rifiutato — vedi `createdPositions`. Entrambi sono segnalati in `warnings` quando accadono; comunicalo all'utente invece di riportare solo `created`. Un foglio che si analizza a zero righe viene rifiutato (sembra esattamente una lettura errata sul punto di cancellare l'intera timeline) a meno che tu non passi force:true. Leggi allocations_list dopo per vedere cosa è arrivato. Alto impatto. Scrittura. |
Organizzazione
Strumenti
| organization_whoami | Restituisce l'organizzazione a cui è vincolata questa connessione MCP — { orgId, name, slug, userId }. Chiamalo per confermare A QUALE tenant stai per scrivere prima di qualsiasi create/update: la connessione è fissata a esattamente un'org dal token, e scrivere prospect/record nell'org sbagliata è un incidente reale. Sola lettura. |
Consuntivi di Resourcing
Strumenti
| resourcingActuals_get | Ore riportate rispetto al piano, per persona per settimana, su una finestra from/to — la domanda 'il team è realmente in linea col piano?', a cui NESSUN altro strumento di resourcing risponde: le allocazioni dicono cosa era PIANIFICATO, questo dice cosa è stato CONSEGNATO. Restituisce colonne settimanali più una riga per persona (percentuale pianificata, percentuale riportata, scostamento, totali e una scomposizione per progetto). reportedPercent null significa 'nessun contratto quella settimana' e 0 significa 'un contratto esisteva e non è stato riportato nulla' — NON confondere i due. Passa financials per ricavi/costi/margine, altrimenti omessi. Richiede il modulo resourcing e ROLE_RESOURCING_MANAGER. Sola lettura. |
Bench di Resourcing
Strumenti
| resourcingBench_get | Chi NON è staffato su una finestra from/to — il bench. Usalo quando ti viene chiesto chi mettere su un nuovo progetto o dove la capacità non viene utilizzata; resourcingActuals_get dice quanto sono caricate le persone, questo dice chi non ha alcun carico. NON SA NULLA DELLE FERIE: freePercent è 100 meno le allocazioni confermate, nient'altro, quindi qualcuno in tre settimane di ferie approvate risulta libero al 100% e nessun campo nella risposta lo segnala. Rispondere a 'chi è disponibile' solo da questo metterà persone su progetti mentre sono assenti — verifica incrociando holidays_active o holidays_list. Richiede il modulo resourcing. Sola lettura. |
Pianificazione di Resourcing
Strumenti
| resourcingSchedule_get | La pianificazione di resourcing prevista su una finestra from/to — la timeline di allocazione come la mostra il planner. Usalo per ciò che è PRENOTATO in avanti; usa resourcingActuals_get per ciò che è stato realmente riportato rispetto ad essa. Richiede il modulo resourcing e ROLE_RESOURCING_MANAGER. Sola lettura. |