Cosa sono le API e quando utilizzarle
Le API sono interfacce che consentono l'accesso programmatico, in lettura o scrittura, ai dati salvati su Fluida HR Suite. Le API permettono a sistemi software di terze parti di compiere operazioni con le diverse entità di dati o risorse che esistono in Fluida, come timbrature, giustificativi, note spese e documenti.
Grazie alle API, è possibile realizzare integrazioni personalizzate ed estendere le funzionalità oggi disponibili con le applicazioni ufficiali di Fluida. Per poter interagire con le API di Fluida, i sistemi terzi che sfruttano un'integrazione personalizzata oppure sono già disponibili come estensione di Fluida devono essere autorizzati attraverso l'identificativo unifico dell'azienda (Company ID) e una chiave API (API key - paragonabile a una password).
Tutte le informazioni in merito all'utilizzo delle API e alle modalità e possibilità di interazione con le risorse di Fluida HR Suite sono disponibili sul Developer Portal 👇
💡 Se sei uno sviluppatore già in possesso di un'API key, scopri come utilizzarla per autenticare le tue richieste HTTP!
Aggiungi una nuova chiave API
Segui i semplici passaggi descritti di seguito per generare una nuova chiave API per permettere l'integrazione di altri software con Fluida.
1. Accedi al menu Azienda > Generali > API
2. Clicca su "Aggiungi"
3. Scegli un nome
4. Abilita la chiave
⚠️ Ti suggeriamo di dare un nome riconoscibile alla chiave API. Ad esempio, se stai generando la chiave per l'integrazione nativa con i software paghe Zucchetti, puoi chiamare la chiave API "Zucchetti Paghe Web".
5. Imposta i permessi associati alla chiave, scegliendo tra le seguenti opzioni:
Permessi Completi - la chiave API permetterà l'accesso in lettura e scrittura a tutte le risorse gestite da Fluida
Permessi di Sola Lettura - la chiave API permetterà l'accesso in sola lettura a tutte le risorse
Permessi Custom - puoi personalizzare i permessi per ogni risorsa
6. Clicca su Salva.
Cliccando sulla chiave appena creata, sarà possibile apportare modifiche e copiare i valori di Company ID e API Key da utilizzare per l'integrazione.
Personalizza i permessi di una chiave API
Scegliendo l'opzione Custom per i permessi di una chiave API, è possibile definire per ogni entità o risorsa di Fluida HR Suite, se il sistema di terze parti che utilizza la chiave ha la possibilità di accedere in sola lettura (Read) oppure anche in scrittura (Write). La chiave API non permette l'accesso alle risorse per cui scegli l'opzione Disabled.
Potresti, ad esempio, configurare una chiave con i seguenti permessi:
Justification - Read
Stamping - Write
e l'opzione Disabled per tutte le altre risorse.
Con questa chiave, un sistema terzo sarà in grado di:
recuperare tutti i giustificativi della categoria ferie ma NON inserire una nuove richieste di ferie,
creare una nuova timbratura ma NON recuperare le timbrature esistenti.
L'accesso, in lettura e scrittura, ad ogni altro tipo di risorsa non sarà consentito utilizzando questa chiave.
Autenticati tramite chiave API
Se sei uno sviluppatore, ottenuta una API Key utilizzala come valore per il Request Header "x-fluida-app-uuid", da aggiungere ad ogni richiesta HTTP che invii alle API Fluida.
⚠️ Negli esempi del Developer Portal, è presente il Request Header "Authorization": ignora questo parametro e il token di accesso Bearer indicati, in favore del parametro "x-fluida-app-uuid" e della API key.
Casi di utilizzo
Nei paragrafi successivi verranno descritte alcune delle chiamate API utili per implementare flussi di integrazione in lettura e scrittura con Fluida HR Suite, in base alle funzionalità con cui è necessario interagire.
Funzionalità generali
Le entità principali di Fluida HR Suite, che non dipendono da una funzionalità specifica, sono le seguenti.
Company
Un oggetto di tipologia Company rappresenta l'azienda, ovvero l'organizzazione che utilizza Fluida, con i suoi dati di fatturazione e dell'abbonamento a Fluida HR Suite sottoscritto.
L'elenco completo degli attributi dell'oggetto è indicato nella documentazione del modello dati (schema) dell'entità Company.
Contract
Un oggetto di tipologia Contract rappresenta il contratto in essere tra azienda e lavoratore, che può essere visto come la persona che accede a Fluida per interagire con l'azienda attraverso un utente.
Un oggetto Contract è caratterizzato dai dati che definiscono la sua relazione con la Company: l'elenco completo degli attributi è indicato nella documentazione del modello dati (schema) dell'entità Contract.
Team
Un oggetto di tipologia Team rappresenta un raggruppamento di persone in azienda che hanno qualcosa in comune, come un reparto aziendale o un gruppo di lavoro. Il team può essere guidato da un leader.
L'elenco completo degli attributi dell'oggetto è indicato nella documentazione del modello dati (schema) dell'entità Team.
Subsidiary
Un oggetto di tipologia Subsidiary rappresenta una sede aziendale, o comunque il luogo dove i membri dell'organizzazione prestano l'attività lavorativa.
Oltre al nome, alla sede può essere attribuito un codice (ref_code) utile per agevolare l'identificazione dello stesso nell’integrazione con un sistema esterno.
L'elenco completo degli attributi dell'oggetto è indicato nella documentazione del modello dati (schema) dell'entità Subsidiary.
Customer
Un oggetto di tipologia Customer rappresenta un committente o cliente dell'azienda. Solitamente, il committente, interno o esterno all'azienda, richiede l'esecuzione di un progetto o commessa.
Oltre al nome, al committente può essere attribuito un codice (ref_code) utile per agevolare l'identificazione dello stesso nell’integrazione con un sistema esterno.
L'elenco completo degli attributi dell'oggetto è indicato nella documentazione del modello dati (schema) dell'entità Customer.
Order
Un oggetto di tipologia Order rappresenta un progetto o commessa dell'azienda. Solitamente, chi lavora per l'azienda svolge attività e sostiene spese relative a uno specifico progetto o commessa. Un progetto è sempre associato al suo committente (Customer).
Oltre al nome e al riferimento del committente (customer_id), al progetto può essere attribuito un codice (ref_code) utile per agevolare l'identificazione dello stesso nell’integrazione con un sistema esterno.
L'elenco completo degli attributi dell'oggetto è indicato nella documentazione del modello dati (schema) dell'entità Order.
Ottieni tramite API l'elenco dei contratti (utenti) associati a un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco dei contratti associati a un'azienda.
💡 il contratto rappresenta la relazione tra azienda e persona: ogni persona che accede ad un'azienda in Fluida ha sempre un utente (indipendente dall'azienda) e un contratto
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sui contratti, è possibile utilizzare l'operazione "Renders a list contract entries for a given company id". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK Contracts
Ottieni tramite API l'elenco dei team di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco dei team (reparti o gruppi) di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sui team aziendali, è possibile utilizzare l'operazione "Renders a list of teams for a given company id". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Ottenere tramite API l'elenco delle sedi di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle sedi di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sulle sedi aziendali, è possibile utilizzare l'operazione "Renders a list of subsidiaries for a given company id". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Aggiungere tramite API un nuovo committente di un'azienda
Di seguito, un esempio di come utilizzare le API per aggiungere in modo programmatico un nuovo committente di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per creare un nuovo committente aziendale, è possibile utilizzare l'operazione "Creates a customer". Di seguito un esempio della richiesta e dei relativi parametri.
Request URL: https://api.fluida.io/api/v1/activities/customers
Request method: POST
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Request body example:
{
"customer": {
"ref_code": "000158",
"name": "Customer A",
"company_id": "{company_id}"
}
}
La risposta ricevuta contiene l'ID del committente che può essere utilizzato, ad esempio, per aggiungere tramite API un nuovo progetto di un'azienda.
Response example (201 Created):
{
"company_id": "{company_id}",
"disabled": false,
"id": "{customer_id}",
"name": "Customer A",
"ref_code": "000158"
}
Ottenere tramite API l'elenco dei committenti di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco dei committenti di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sui progetti aziendali, è possibile utilizzare l'operazione "Renders a list of Customers with a specific Company ID". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK Customers
ℹ️ Il percorso indicato nella documentazione contiene un'imprecisione: fai riferimento all'URL della richiesta nell'esempio.
Aggiungere tramite API un nuovo progetto di un'azienda
Di seguito, un esempio di come utilizzare le API per aggiungere in modo programmatico un nuovo progetto di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Sei in possesso dell'ID del committente (customer_id) a cui vuoi associare il progetto.
Per creare un nuovo progetto aziendale, è possibile utilizzare l'operazione "Creates an Order". Di seguito un esempio della richiesta e dei relativi parametri.
Request URL: https://api.fluida.io/api/v1/activities/orders
Request method: POST
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Request body example:
{
"order": {
"name": "Project A",
"ref_code": "P1",
"customer_id": "{customer_id}",
"company_id": "{company_id}"
}
}Response example (201 Created):
{
"company_id": "{company_id}",
"customer_id": "{customer_id}",
"disabled": false,
"id": "{customer_id}",
"name": "Project A",
"ref_code": "P1"
}
Ottenere tramite API l'elenco dei progetti di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco dei progetti di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sui progetti aziendali, è possibile utilizzare l'operazione "Renders a list of Orders with a specific Company ID". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK Orders
ℹ️ Il percorso indicato nella documentazione contiene un'imprecisione: fai riferimento all'URL della richiesta nell'esempio.
Funzionalità Gestione presenze e Timbratura smart
Esporta tramite API il file Excel presenze e timbrature
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un'esportazione in formato xlsx dei dati di presenza e timbratura di un'azienda. Puoi partire da quest'esempio per realizzare un sistema che, al termine di ogni mese, estragga in automatico i dati e li invii in allegato a un indirizzo email.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per esportare i dati, è possibile utilizzare l'operazione "Requests an export for a given company". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: POST
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Request body:
{
"contract_id": null,
"export_type": "presences_stampings_xlsx",
"recipient_locale": "it",
"decimal_format": false,
"year": "2023",
"month": "1",
"subsidiary_id": null,
"team_id": null,
"async": false
}
Avendo dato il valore "false" al parametro "async", la risposta ottienuta è simile a quella dell'esempio.
Response example:
{
"document_type": "export",
"id": {document_id},
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"name": "limeworksrl-timbrature-gennaio-2023-20230213.xlsx",
"owner_id": {company_id},
"owner_type": "company"
}
Puoi ora utilizzare il valore di "document_id" ottenuto in risposta per scaricare l'export generato tramite l'operazione "Download export". Di seguito un esempio della richiesta.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Ottieni tramite API richieste e segnalazioni di assenza, straordinario, lavoro da remoto, cambio turno e cambio sede
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle richieste e segnalazioni di:
assenza (ferie, permessi, malattie, altre assenze)
straordinario
lavoro da remoto
cambio turno
cambio sede
relative a una persona che lavora per l'azienda e le rispettive informazioni.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Sei in possesso dell'ID del contratto (contract_id) della persona di cui vuoi ottenere le informazioni
Per ottenere l'elenco e le informazioni su richieste e segnalazioni, è possibile utilizzare l'operazione "Renders a list justification entries for a given contract id". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
L'elenco può essere ulteriormente filtrato con i seguenti parametri di query string:
status (approved, cancelled, ...)
type_id (identificativo della tipologia di giustificativo, può essere ottenuto con l'operazione "Renders a list justification types for a given company id")
⚠️ Con questa operazione vengono restituite tutte le richieste e segnalazioni della persona, a prescindere che la variazione sia o meno applicata al calendario (es: un'assenza per ferie non è applicata su un giorno di riposo, ma è comunque restituita dall'operazione). Per ottenere solo le variazioni applicate, vedi "Ottieni tramite API i dati "sintetici" del calendario presenze per un determinato periodo"
Ottieni tramite API i dati "sintetici" del calendario presenze per un determinato periodo
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco dei dati presenti sul calendario presenze di tutte le persone che lavorano per l'azienda in un determinato periodo. I dati includono:
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni su richieste e segnalazioni, è possibile utilizzare l'operazione descritta nel seguente esempio.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Per ogni persona e per ogni giorno del periodo selezionato, viene restituito un oggetto come quello nel seguente esempio che illustra una porzione della risposta ricevuta (un giorno di una delle persone).
A partire da questo oggetto, è possibile, ad esempio, ottenere le richieste o segnalazioni di straordinario della persona per quel giorno di calendario estraendo dall'array "entries" gli elementi che hanno come "type_label" il valore "extraordinary".
Response example (partial)
Response example (partial)
{
"company_id": "{company_id}",
"contract_id": "{contract_id}",
"day": "2023-09-12",
"duration": 480,
"entries": [
{
"additive": null,
"duration": null,
"duration_rounding": 1,
"end": "08:59:59",
"fixed_end": "09:00:00",
"flexible": false,
"id": null,
"last_update": null,
"presence": false,
"start": "00:00:00",
"status": null,
"type_id": null,
"type_label": null,
"type_name": null,
"workplace": {}
},
{
"additive": false,
"duration": 240,
"duration_rounding": 30,
"end": "12:59:59",
"fixed_end": "13:00:00",
"flexible": false,
"id": "{entity_id}",
"last_update": "2023-09-04T14:52:10+00:00",
"presence": false,
"start": "09:00:00",
"status": "approved",
"type_id": "{type_id}",
"type_label": "holiday",
"type_name": "Ferie",
"workplace": {}
},
{
"additive": null,
"duration": null,
"duration_rounding": 1,
"end": "13:59:59",
"fixed_end": "14:00:00",
"flexible": false,
"id": null,
"last_update": null,
"presence": false,
"start": "13:00:00",
"status": null,
"type_id": null,
"type_label": null,
"type_name": null,
"workplace": {}
},
{
"additive": false,
"duration": 240,
"duration_rounding": 30,
"end": "17:59:59",
"fixed_end": "18:00:00",
"flexible": false,
"id": "{entity_id}",
"last_update": "2023-09-04T14:52:10+00:00",
"presence": false,
"start": "14:00:00",
"status": "approved",
"type_id": "{type_id}",
"type_label": "holiday",
"type_name": "Ferie",
"workplace": {}
},
{
"additive": null,
"duration": null,
"duration_rounding": 1,
"end": "23:59:59",
"fixed_end": "00:00:00",
"flexible": false,
"id": null,
"last_update": null,
"presence": false,
"start": "18:00:00",
"status": null,
"type_id": null,
"type_label": null,
"type_name": null,
"workplace": {}
}
],
"has_mismatches": false,
"is_flexible": false,
"is_holiday": false,
"shift_name": "09:00 > 13:00 | 14:00 > 18:00",
"user_id": "{user_id}",
"workplace_ids": [
"{workplace_id}"
]
}
Ottieni tramite API le timbrature di una persona
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle timbrature di una persona che lavora per l'azienda e le rispettive informazioni.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Sei in possesso dell'ID del contratto (contract_id) della persona di cui vuoi ottenere le informazioni
Esistono diverse operazioni per ottenere le informazioni sulle timbrature effettuate:
"Daily Clock Records" per ottenere un elenco di timbrature effettuate da una persona in un determinato periodo, raggruppate per giorno
"Renders a denormalized list of timestamps" per ottenere un elenco "denormalizzato" di timbrature effettuate da una persona in un certo periodo
"Renders contract last record" per ottenere le informazioni sull'ultima timbratura effettuata da una persona
Di seguito un esempio della richiesta e dei relativi parametri per l'utilizzo dell'operazione "Daily Clock Records" per ottenere le timbrature effettuate da una persona tra l'1 e il 30 giugno 2023.
💡 Il report Timbrature mensili nell'app Fluida HR Suite utilizza la stessa operazione per mostrare le timbrature di una persona!
⚠️ Per stabilire l'orario di timbratura, devono essere considerati esclusivamente gli attributi "server_clock_at" e "clock_tz".
L'attributo "server_clock_at" indica l'orario di timbratura effettivo/certificato, espresso con timezone UTC (l'orario è stabilito dal server). L'attributo "clock_at" invece indica l'orario "rilevato" dall'applicazione nel momento in cui viene effettuata la timbratura, mostrato nella home page affianco al tasto di timbratura.
L'attributo "clock_at" è salvato esclusivamente per fini statistici, non è in alcun caso da considerare. In alcune condizioni (es. l'applicazione viene messa in background), i valori dei due attributi potrebbero differire e fare riferimento a "clock_at" potrebbe portare a risultati indesiderati.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Ottieni tramite API le timbrature eliminate
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle timbrature in stato eliminato e le rispettive informazioni.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere i dati sulle timbrature eliminate, è possibile utilizzare l'operazione "Renders a list of stampings for a given company id". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Il parametro "day" in query string è obbligatorio!
Aggiungere tramite API la timbratura dichiarata per una persona
Di seguito, un esempio di come utilizzare le API per aggiungere in modo programmatico una nuova timbratura dichiarata (senza validazione) per una persona.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Sei in possesso dell'ID del contratto (contract_id) della persona di cui vuoi ottenere le informazioni
Per creare una nuova timbratura senza validazione, è possibile utilizzare l'operazione "Records a user stamping clock". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: POST
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Request body:
{
"stamping": {
"user_id": "{user_id}",
"created_by": "{contract_id}",
"updated_by": "{contract_id}",
"contract_id": "{contract_id}",
"company_id": "{company_id}",
"subsidiary_id": null,
"team_ids": [
"{team_id}",
"{team_id}"
],
"badge_id": null,
"clock_id": null,
"clock_at": "2023-12-18T16:54:00+01:00",
"clock_tz": "Europe/Rome",
"clock_type": "manual",
"direction": "IN",
"notes": "Importata dal sistema X"
}
}
La risposta ricevuta contiene l'ID della timbratura.
Response example
Response example
{
"data": {
"approver_ids": [],
"badge_id": null,
"change_log": [
{
"changed_at": "2023-12-18T15:58:59Z",
"changed_by": "{contract_id}",
"changes": [],
"notes": "Importata dal sistema X",
"operation": "create"
}
],
"clock_at": "2023-12-18T16:54:00",
"clock_id": null,
"clock_type": "manual",
"clock_tz": "Europe/Rome",
"closed_at": null,
"closed_by": null,
"company_id": "{contract_id}",
"contract_id": "{contract_id}",
"contract_subsidiary_id": null,
"day": null,
"direction": "IN",
"id": "{clock_id}",
"notes": "Importata dal sistema X",
"overnight": null,
"server_clock_at": "2023-12-18T15:54:00Z",
"stamping_device_type": null,
"status": "recorded",
"subsidiary_id": null,
"team_ids": [
"{team_id}",
"{team_id}"
],
"user_id": "{user_id}"
}
} Funzionalità Nota spese
Le entità principali della funzionalità Nota spese sono Expense, ovvero spese sostenute da un lavoratore per conto dell'azienda, ed ExpenseReport, ovvero la nota spese in cui il lavoratore raggruppa le spese sostenute per trasmetterle all'azienda.
Un oggetto di tipo Expense è caratterizzato principalmente da:
riferimenti al contratto o utente (contract_id), alla categoria di spesa (expense_type_id), all'eventuale nota spese a cui la spesa è già stata associata (expense_report_id) e ad altre entità eventualmente collegate alla spesa
l'importo speso e quello da rimborsare, espressi in centesimi
la data in cui è stata sostenuta la spesa
L'elenco completo degli attributi degli oggetti è indicato nella documentazione del modello dati (schema) dell'entità Expense.
Un oggetto di tipo ExpenseReport è caratterizzato principalmente da:
riferimenti al contratto o utente (contract_id)
lo stato in cui la nota spese si trova
il totale speso e da rimborsare, espressi in centesimi
alcuni riferimenti temporali
L'elenco completo degli attributi degli oggetti è indicato nella documentazione del modello dati (schema) dell'entità ExpenseReport.
Ottieni tramite API l'elenco delle note spese di una persona
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco di tutte le note spese inserite da una persona.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID del contratto (contract_id) della persona di cui vuoi ottenere le informazioni
Per ottenere l'elenco e le informazioni sulle note spese, è possibile utilizzare l'operazione "List Expense Reports by Contract ID". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK ExpenseReports
Ottenere tramite API l'elenco delle note spese di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle note spese di un'azienda, con possibilità di filtrare per stato, data di competenza e data di modifica, utile nel caso di letture incrementali.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sulle tipologie di attività aziendali, è possibile utilizzare l'operazione "Renders a list of Expense Reports by Company ID" con i seguenti query params:
from_date: data YYYY-MM-dd,
to_date: data YYYY-MM-dd,
status: array
Se presente, filtra le note spese per gli stati contenuti nel parametro. Possibili valori:draft (bozza)
pending (attesa approvazione)
accepted (approvata)
rejected (rifiutata)
cancelled (annullata)
refunded (rimborsata)
Di seguito un esempio della richiesta e dei relativi parametri per ottenere le note spese di un'azienda con competenza tra l'1 aprile 2024 e il 31 marzo 2024 con stato "Approvata" oppure "Rimborsata".
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK ExpenseReports
Ottieni tramite API l'elenco delle spese di una nota spese
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco di tutte le spese associate ad una nota spese.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID della nota spese (expense_report_id)
Per ottenere l'elenco e le informazioni sulle spese di una nota spese, è possibile utilizzare l'operazione "Renders a list of Expenses by Expense Report ID". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK Expenses
Ottieni tramite API l'elenco delle spese sostenute da una persona in una determinata data
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco di tutte le spese sostenute da una determinata persona in una certa data.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID del contratto (contract_id) della persona di cui vuoi ottenere le informazioni
Per ottenere l'elenco e le informazioni sulle spese di una nota spese, è possibile utilizzare l'operazione "Renders a list of ExpensesCalendar by Contract ID and Date". Di seguito un esempio della richiesta e dei relativi parametri.
Request URL: https://api.fluida.io/api/v1/expense_reports/expenses/by_calendar/{contract_id}/YYYY-MM-dd
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK ExpensesCalendar
Ottieni tramite API l'elenco delle tipologie di spesa di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle tipologie di spesa di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Per ottenere l'elenco e le informazioni sulle tipologie di spesa aziendali, è possibile utilizzare l'operazione "Renders a list of Expense Types". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK ExpenseTypes
Funzionalità Rendicontazione attività
Le entità principali della funzionalità Rendicontazione attività in modalità "Avanzata" sono ActivityType, ovvero una tipologia di attività definita dall'azienda, e Activity, che rappresenta la singola attività rendicontata da un utente in un determinato giorno.
Un oggetto di tipo Activity è caratterizzato principalmente da:
riferimenti al contratto o utente (contract_id), al progetto o commessa (order_id) e al tipo di attività (activity_type_id)
durata rendicontata, espressa in minuti
durata prevista da rendicontare, espressa in minuti e ottenuta sulla base del calendario presenze (disponibile solo se è attiva la funzionalità presenze e l’utente ha un orario assegnato)
la data in cui è stata svolta l'attività
L'elenco completo degli attributi degli oggetti è indicato nella documentazione del modello dati (schema) dell'entità Activity e dell'entità ActivityType.
Aggiungi tramite API una nuova tipologia di attività aziendale
Di seguito, un esempio di come utilizzare le API per aggiungere in modo programmatico una nuova tipologia di attività aziendale (ActivityType).
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per creare una nuova tipologia di attività, è possibile utilizzare l'operazione "Creates an activity type". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: POST
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Request body example:
{
"activity_type": {
"name": "Activity Type A",
"ref_code": "A1",
"company_id": "{company_id}"
}
}Response example (201 Created):
{
"company_id": "{company_id}",
"disabled": false,
"id": "{activity_type_id}",
"name": "Activity Type A",
"ref_code": "A1",
"team_ids": []
}
Ottieni tramite API l'elenco delle tipologie di attività di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco delle tipologie di attività di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sulle tipologie di attività aziendali, è possibile utilizzare l'operazione "Renders a list of Activity Types with a specific Company ID". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK ActivityTypes
ℹ️ Il percorso indicato nella documentazione contiene un'imprecisione: fai riferimento all'URL della richiesta nell'esempio.
Ottieni tramite API l'elenco delle rendicontazioni di attività relative ad una specifica giornata per tutte le persone di un'azienda
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco di tutte le rendicontazioni attività relative ad una specifica data inserite da qualunque persona di un'azienda.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Per ottenere l'elenco e le informazioni sui progetti, è possibile utilizzare l'operazione "Returns activities of a specific company". Di seguito un esempio della richiesta e dei relativi parametri.
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Ottieni tramite API l'elenco delle rendicontazioni di attività di una persona relative ad una specifica giornata
Di seguito, un esempio di come utilizzare le API per ottenere in modo programmatico un elenco di tutte le rendicontazioni attività inserite da una persona relative ad una specifica data.
Prima di cominciare:
Sei in possesso di una chiave API autorizzata ad effettuare l'operazione
Sei in possesso dell'ID dell'azienda (company_id)
Sei in possesso dell'ID del contratto (contract_id) della persona di cui vuoi ottenere le informazioni
Per ottenere l'elenco e le informazioni sulle rendicontazioni attività, è possibile utilizzare l'operazione "List contract activities". Di seguito un esempio della richiesta e dei relativi parametri.
Request URL: https://api.fluida.io/api/v1/activities/activity/reported/{company}/{contract_id}/2023-04-18
Request method: GET
Request headers:
content-type: application/json
accept: */*
x-fluida-app-uuid: {api_key}
Response: 200 OK ActivityReport
A partire da questo oggetto, è possibile, ad esempio, decodificare tipi di attività, progetti e committenti attraverso il loro id.
Domande frequenti sulle API
Posso autenticarmi tramite OAuth 2.0?
L’autenticazione OAuth ad oggi è utilizzata esclusivamente dalle applicazioni ufficiali Fluida. Per realizzare integrazioni con sistemi terzi, è possibile autenticarsi esclusivamente tramite chiave API (ApiKey).
Tutti gli endpoint sono disponibili con autenticazione tramite chiave API?
La maggior parte delle operazioni (e dei relativi endpoint) possono essere utilizzati anche autenticandosi tramite APIKey. L'autenticazione OAuth 2.0 è l'unica consentita solo per alcune operazioni specifiche, come la creazione, lettura, modifica ed eliminazione di Chiavi API.
⚠️ Negli esempi del Developer Portal, per alcune operazioni OAuth2 è indicato come unico metodo di autenticazione supportato: contattaci se hai esigenza utilizzare questi endpoint, fornendoci il maggior numero di informazioni sull'integrazione che vuoi realizzare.
Posso inserire tramite API una timbratura certificata per una persona?
Tramite le API accessibili a terze parti (clienti / partner) è possibile solo inserire timbrature NON certificate.
Le app Fluida HR Suite (iOS e Android) e Kiosk by Fluida (Android / Station) utilizzano le API per inserire timbrature certificate, ma con un processo complesso e non pubblicamente condivisibile.