Guida di Riferimento API Flowenti Robots

Restituisce i dati di contesto dell'organizzazione associata all'API Key rilasciata al robot prima di eseguire qualsiasi chiamata.

{
  "organizations": [
    {
      "id": 14299,
      "name": "robots snippet",
      "administrator": false,
      "subscriptionname": "",
      "hasmultipleuser": false,
      "creation": "2026-09-07T14:00:12.282+02:00",
      "deleted": false,
      "icon": null
    }
  ]
}

• organizationsElenco delle organizzazioni legate all'API key del robot: con un token robot ne contiene una sola.
• idID numerico dell'organizzazione: è il valore da usare come {idorganization} negli altri endpoint.
• nameNome visualizzato dell'organizzazione.
• administratortrue se il robot opera con permessi di amministratore dell'organizzazione.
• subscriptionnameNome del piano/abbonamento dell'organizzazione (può essere vuoto).
• hasmultipleusertrue se l'organizzazione ha più utenti associati.
• creationData/ora di creazione dell'organizzazione (ISO 8601).
• deletedtrue se l'organizzazione è stata eliminata (soft delete).
• iconIcona/logo dell'organizzazione (null se non impostato).

Scopri quali processi il robot è autorizzato ad avviare nell'organizzazione specificata.

{
  "possiblestart": [
    {
      "id": 21,
      "name": "",
      "idtype": 0,
      "idprocessmodel": 88,
      "processmodelname": "Gestione Ordini",
      "idswimlane": 1,
      "swimlanename": "Lane 1",
      "idorganization": 14207,
      "assignmentmode": 0,
      "userschema": "[]"
    }
  ]
}

• possiblestartElenco degli start event avviabili: ogni voce è un processo che il robot può istanziare.
• idID dello start event: è il valore da usare come {idevent} nell'avvio del processo.
• nameNome dell'evento di start (può essere vuoto).
• idtypeTipo di start event definito nel modello BPMN.
• idprocessmodelID del modello di processo (BPMN) a cui si riferisce l'operazione.
• processmodelnameNome del modello di processo (BPMN) a cui lo start event appartiene.
• idswimlaneID della lane (swimlane) assegnata alle attività del processo avviato.
• swimlanenameNome della lane associata.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• assignmentmodeModalità di assegnazione dei task definita sul modello (0 = assegnazione automatica dalla coda).
• userschemaSchema utenti ammessi (JSON serializzato) associato allo start event.

Istanzia un nuovo processo BPMN generando l'iniziale Token di avanzamento.

{
  "idprocessmodel": 88,
  "idorganization": 14207,
  "idevent": 21,
  "startdate": "2026-08-26T08:00:00Z",
  "enddate": null,
  "description": "Fattura #2026-0451",
  "descriptiondetail": "Emissione automatica da robot",
  "userdata": { "cliente": "Acme Spa" }
}

• idprocessmodelID del modello di processo (BPMN) a cui si riferisce l'operazione.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• ideventID dello start event del modello che istanzia il processo: si sceglie da /startevents/organizations/{idorganization}.
• startdateData/ora di avvio del processo in formato ISO 8601 (es. 2026-08-26T08:00:00Z).
• enddateData/ora di fine del processo; null finché il processo non viene chiuso.
• descriptionDescrizione breve del processo, visibile nell'interfaccia (es. Fattura #2026-0451).
• descriptiondetailDescrizione estesa opzionale con i dettagli operativi dell'istanza del processo.
• userdataOggetto con dati liberi legati all'istanza (es. cliente): persistenti per tutta la vita del processo.

{
  "process": {
    "id": 773019
  },
  "processtoken": {
    "id": 901,
    "state": 0
  },
  "previousprocesstoken": {
    "id": 901
  }
}

• processProcesso istanziato: il campo id è il riferimento globale da usare per la lettura degli allegati e le query sul processo.
• processtokenToken di avanzamento creato o spostato dall'operazione: è l'unità di lavoro che il robot guida nodo per nodo.
• idID del token di avanzamento: identificatore univoco dell'unità di lavoro.
• stateStato del token: 0 = in attesa (todo), 1 = in lavorazione (doing), 2 = completata (done).
• previousprocesstokenStato del token prima dell'operazione: utile per audit e per ricostruire la storia del processo.

Interroga il sistema per verificare l'esistenza di attività disponibili che il robot può prendere in carico.

{
  "waitingflownodes": [
    {
      "idprocesstoken": 901,
      "idflownode": 41,
      "designerid": "Task_EstrarreFatturePDF",
      "flownodename": "EstrarreFatturePDF",
      "idprocess": 773019,
      "idprocessmodel": 88,
      "idorganization": 14207,
      "processmodelname": "Gestione Ordini",
      "state": 0,
      "priority_name": "HIGH",
      "countcomments": 0,
      "countattachments": 2
    }
  ],
  "doingflownodes": []
}

• waitingflownodesTask in attesa (stato todo) che il robot può prendere in carico con nextstate/doing.
• doingflownodesTask attualmente in lavorazione (stato doing) dal robot.
• idprocesstokenID del token di avanzamento su cui operare nelle chiamate successive (nextstate, allegati, exit).
• idflownodeID del nodo attività: è il valore da usare come {idflownode} nel body di nextstate.
• designeridID alfanumerico del nodo nel diagramma BPMN (id XML del designer): serve per /exit/{designerid} nei gateway.
• flownodenameNome leggibile dell'attività così come disegnata nel modello BPMN.
• idprocessID del processo a cui il task appartiene: serve per la lettura degli allegati (/processes/{idprocess}/attachments/light).
• idprocessmodelID del modello di processo (BPMN) a cui si riferisce l'operazione.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• processmodelnameNome del modello di processo (BPMN) a cui lo start event appartiene.
• stateStato del token: 0 = in attesa (todo), 1 = in lavorazione (doing), 2 = completata (done).
• priority_namePriorità del task impostata sul modello (es. HIGH): guida l'ordine di elaborazione.
• countcommentsNumero di commenti presenti sul task (sola lettura).
• countattachmentsNumero di allegati già presenti sul task (sola lettura).

Notifica a Flowenti la presa in carico dell'attività da parte del robot, cambiando lo stato del token in

{
  "idflownode": 555,
  "iduserrobot": 17
}

• idflownodeID del nodo attività (flownode) a cui si riferisce l'azione: arriva nell'elenco waitingflownodes restituito dal polling.
• iduserrobotID dell'utente/robot che esegue l'operazione: è quello associato al token JWT del robot.

{
  "idtoken": 888111,
  "state": 1,
  "claimedAt": "2026-08-27T14:33:02Z",
  "iduserrobot": 17
}

• idtokenID del token che ha cambiato stato in seguito all'operazione.
• stateStato del token: 0 = in attesa (todo), 1 = in lavorazione (doing), 2 = completata (done).
• claimedAtData/ora della presa in carico (ISO 8601).
• iduserrobotID dell'utente/robot che esegue l'operazione: è quello associato al token JWT del robot.

Segnala il completamento con successo del task sul token e fa avanzare il flusso al nodo successivo.

{
  "idflownode": 555,
  "result": {
    "validated": true,
    "extractedFields": {
      "total": 1234.56,
      "vat": 258.86
    }
  }
}

• idflownodeID del nodo attività (flownode) a cui si riferisce l'azione: arriva nell'elenco waitingflownodes restituito dal polling.
• resultPayload di esito in formato libero con i dati prodotti dal task (es. campi estratti e validati): viene salvato nel processo e reso disponibile ai nodi successivi.

{
  "process": {
    "id": 1661721,
    "idprocessmodel": 27613,
    "idorganization": 14299,
    "state": 0
  },
  "processtoken": {
    "id": 35093744,
    "idprocess": 1661721,
    "idflownode": 38882,
    "flownodetype": 0,
    "iduser": 21976,
    "state": 2,
    "previous": 35093743,
    "created": "...",
    "startdoing": "...",
    "done": "..."
  },
  "previousprocesstoken": {
    "id": 35093743,
    "state": 2,
    "idflownode": 40414
  },
  "previousflownode": {
    "id": 40414,
    "designerid": "Activity_1",
    "name": "prima task"
  },
  "flownode": {
    "id": 38882,
    "designerid": "Event_1blr1wv",
    "idtype": 1
  },
  "sequenceflows": []
}

• processProcesso istanziato: il campo id è il riferimento globale da usare per la lettura degli allegati e le query sul processo.
• processtokenToken di avanzamento creato o spostato dall'operazione: è l'unità di lavoro che il robot guida nodo per nodo.
• idID del token di avanzamento: identificatore univoco dell'unità di lavoro.
• idprocessID del processo a cui il token appartiene.
• idflownodeID del nodo (attività o evento) su cui il token si trova.
• flownodetypeTipo di nodo (0 = evento, 1 = attività, ...).
• iduserID dell'utente/robot che ha in carico il token (0 se in coda).
• stateStato del token: 0 = in attesa (todo), 1 = in lavorazione (doing), 2 = completata (done).
• previousID del token precedente nella storia del processo.
• createdData/ora di creazione del token (ISO 8601).
• startdoingData/ora di presa in carico; null finché il token non passa a doing.
• doneData/ora di completamento; null finché il token non passa a done.
• previousprocesstokenStato del token prima dell'operazione: utile per audit e per ricostruire la storia del processo.
• previousflownodeNodo da cui il token proviene prima dell'operazione.
• flownodeNodo (attività o evento) su cui si trova ora il token.
• sequenceflowsFlussi di sequenza raggiungibili dal nodo corrente: non vuoto quando servono decisioni successive.

Annulla l'ultima azione del robot sull'attività (undo): riporta lo stato del token da In lavorazione (Doing, 1) a In attesa (ToDo, 0), restituendo il task alla coda di quelli disponibili. È l'unico meccanismo di recupero oggi supportato — non esistono nextstate/error, failed o abort — da usare quando il runtime del robot non riesce a portare a termine l'attività.

{
  "process": {
    "id": 1,
    "idorganization": 1,
    "idprocessmodel": 1,
    "startdate": "...",
    "enddate": null,
    "userdata": "{}"
  },
  "processtoken": {
    "id": 2,
    "idprocess": 1,
    "idflownode": 7,
    "flownodetype": 1,
    "iduser": 2,
    "state": 0,
    "previous": 0,
    "created": "...",
    "startdoing": null,
    "done": null
  },
  "flownode": {
    "id": 7,
    "name": "Attività 1",
    "designerid": "Activity_1"
  },
  "previousflownode": {
    "id": 6,
    "name": "Evento",
    "designerid": "StartEvent_1"
  },
  "previousprocesstoken": {
    "id": 1,
    "state": 2,
    "idflownode": 6,
    "flownodetype": 0,
    "iduser": 2,
    "previous": 0
  }
}

• processProcesso istanziato: il campo id è il riferimento globale da usare per la lettura degli allegati e le query sul processo.
• processtokenToken di avanzamento creato o spostato dall'operazione: è l'unità di lavoro che il robot guida nodo per nodo.
• idID del token di avanzamento: identificatore univoco dell'unità di lavoro.
• idprocessID del processo a cui il token appartiene.
• idflownodeID del nodo (attività o evento) su cui il token si trova.
• flownodetypeTipo di nodo (0 = evento, 1 = attività, ...).
• iduserID dell'utente/robot che ha in carico il token (0 se in coda).
• stateStato del token: 0 = in attesa (todo), 1 = in lavorazione (doing), 2 = completata (done).
• previousID del token precedente nella storia del processo.
• createdData/ora di creazione del token (ISO 8601).
• startdoingData/ora di presa in carico; null finché il token non passa a doing.
• doneData/ora di completamento; null finché il token non passa a done.
• flownodeNodo (attività o evento) su cui si trova ora il token.
• previousflownodeNodo da cui il token proviene prima dell'operazione.
• previousprocesstokenStato del token prima dell'operazione: utile per audit e per ricostruire la storia del processo.

Selezione dell'uscita specifica dal gateway quando il flusso BPMN incontra una decisione condizionale o un ramo di scelta guidato dal robot.

{
  "reason": "validated_by_robot",
  "metadata": {
    "validationScore": 0.97
  }
}

• reasonEtichetta libera che documenta il motivo della scelta del ramo del gateway (es. validated_by_robot).
• metadataOggetto opzionale con dati aggiuntivi sulla decisione presa (es. punteggio di validazione).

{
  "idtoken": 888111,
  "selectedExit": "approve",
  "designerid": "Gateway_approve_01",
  "advancedAt": "2026-08-27T14:34:01Z"
}

• idtokenID del token che ha cambiato stato in seguito all'operazione.
• selectedExitNome dell'uscita del gateway selezionata dal robot.
• designeridID alfanumerico del nodo nel diagramma BPMN (id XML del designer): serve per /exit/{designerid} nei gateway.
• advancedAtData/ora dell'avanzamento (ISO 8601).

Carica un file/documento allegato agganciandolo al nodo corrente del processo (utilizza

{
  "idorganization": 14207,
  "filename": "fattura_2026.pdf",
  "cloudlink": "",
  "idtype": 1,
  "description": "Fattura 2026",
  "blob": "<base64 del file>",
  "size": 24576
}

• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• filenameNome del file con estensione, così come deve risultare nell'allegato.
• cloudlinkURL cloud alternativo all'upload binario: se valorizzato, l'allegato punta a una risorsa remota invece del blob.
• idtypeTipo di allegato (idtype): identificatore della categoria del file gestita dalla piattaforma.
• descriptionDescrizione breve del processo, visibile nell'interfaccia (es. Fattura #2026-0451).
• blobContenuto del file codificato in base64; size è la dimensione in byte.
• sizeDimensione del file in byte, coerente con il contenuto del blob.

{
  "idattachment": 7890,
  "idprocesstoken": 888111,
  "filename": "fattura_2026.pdf",
  "size": 24576,
  "uploadedAt": "2026-08-27T14:34:10Z"
}

• idattachmentID dell'allegato creato: da riferire in eventuali operazioni successive.
• idprocesstokenID del token di avanzamento su cui operare nelle chiamate successive (nextstate, allegati, exit).
• filenameNome del file con estensione, così come deve risultare nell'allegato.
• sizeDimensione del file in byte, coerente con il contenuto del blob.
• uploadedAtData/ora dell'upload (ISO 8601).

Legge l'elenco leggero di tutti gli allegati associati al processo (utilizza

{
  "attachments": [
    {
      "id": 7890,
      "idorganization": 1,
      "filename": "invoice-98765.pdf",
      "description": "",
      "idtype": 1,
      "cloudlink": "",
      "creation": "2026-09-09T14:34:10Z",
      "iduser": 0,
      "username": "",
      "activityname": "acct1"
    }
  ]
}

• attachmentsElenco degli allegati del processo: un elemento per ogni file caricato.
• idID dell'allegato.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• filenameNome del file con estensione, così come deve risultare nell'allegato.
• descriptionDescrizione dell'allegato (vuota se non fornita all'upload).
• idtypeTipo di allegato (idtype): identificatore della categoria del file gestita dalla piattaforma.
• cloudlinkURL cloud alternativo all'upload binario: se valorizzato, l'allegato punta a una risorsa remota invece del blob.
• creationData/ora di creazione dell'allegato (ISO 8601).
• iduserID dell'utente che ha caricato l'allegato (0 per i robot).
• usernameNome utente di chi ha caricato l'allegato (vuoto per i robot).
• activitynameNome dell'attività (nodo BPMN) a cui l'allegato è agganciato.

Variante di /tasks/doing filtrata per organizzazione. Restituisce i task Doing del robot corrente per una singola organizzazione.

{
  "doingflownodes": [
    {
      "idprocesstoken": 1,
      "idprocess": 1,
      "idflownode": 7,
      "flownodename": "Attività 1",
      "priority_name": "Alta"
    }
  ]
}

• doingflownodesTask attualmente in lavorazione (stato doing) dal robot.
• idprocesstokenID del token di avanzamento su cui operare nelle chiamate successive (nextstate, allegati, exit).
• idprocessID del processo a cui il task appartiene: serve per la lettura degli allegati (/processes/{idprocess}/attachments/light).
• idflownodeID del nodo attività: è il valore da usare come {idflownode} nel body di nextstate.
• flownodenameNome leggibile dell'attività così come disegnata nel modello BPMN.
• priority_namePriorità del task impostata sul modello (es. HIGH): guida l'ordine di elaborazione.

Discovery globale di tutti gli start event disponibili per il robot su tutte le organizzazioni. Alternativa cross-org a /startevents/organizations/{id}.

{
  "possiblestart": [
    {
      "id": 1,
      "name": "StartEvent_1",
      "idtype": 0,
      "idprocessmodel": 1,
      "processmodelname": "Modello A",
      "idswimlane": 1,
      "swimlanename": "Lane 1",
      "idorganization": 1,
      "assignmentmode": 1,
      "userschema": "..."
    }
  ]
}

• possiblestartElenco degli start event avviabili: ogni voce è un processo che il robot può istanziare.
• idID dello start event: è il valore da usare come {idevent} nell'avvio del processo.
• nameNome dell'evento di start (può essere vuoto).
• idtypeTipo di start event definito nel modello BPMN.
• idprocessmodelID del modello di processo (BPMN) a cui si riferisce l'operazione.
• processmodelnameNome del modello di processo (BPMN) a cui lo start event appartiene.
• idswimlaneID della lane (swimlane) assegnata alle attività del processo avviato.
• swimlanenameNome della lane associata.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• assignmentmodeModalità di assegnazione dei task definita sul modello (0 = assegnazione automatica dalla coda).
• userschemaSchema utenti ammessi (JSON serializzato) associato allo start event.

Recupera la configurazione JSON del robot per l'organizzazione e il processo modello indicati. Usata in bootstrap per leggere parametri driver, endpoint remoti, credenziali di integrazione.

{
  "id": 1,
  "idorganization": 1,
  "idrobot": 1,
  "idprocessmodel": 1,
  "linkedto": "",
  "datajson": {
    "chiave": "valore"
  }
}

• idID della riga di configurazione.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• idrobotID del robot a cui si riferiscono i dati.
• idprocessmodelID del modello di processo (BPMN) a cui si riferisce l'operazione.
• linkedtoRiferimento interno di collegamento (in genere vuoto).
• datajsonConfigurazione e parametri runtime del robot in formato JSON libero: letta in bootstrap e interpretata dal robot.

Elenca le organizzazioni associate al robot corrente con i relativi tag (urgente, routine, batch, ecc.). Utile per instradare il task all'organizzazione corretta prima di prendere in carico.

{
  "idrobot": 1,
  "organizations": [
    {
      "id": 1,
      "name": "Org1",
      "tags": [
        {
          "id": 1,
          "name": "urgente",
          "idorganization": 1,
          "color": "#ff0000"
        }
      ]
    }
  ]
}

• idrobotID del robot a cui si riferiscono i dati.
• organizationsElenco delle organizzazioni legate all'API key del robot: con un token robot ne contiene una sola.
• idID numerico dell'organizzazione: è il valore da usare come {idorganization} negli altri endpoint.
• nameNome visualizzato dell'organizzazione.
• tagsTag associati all'organizzazione (es. urgente, routine, batch).
• tags.idID del tag.
• tags.nameNome del tag (es. urgente).
• tags.idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• tags.colorColore del tag in formato hex (es. #ff0000).

Settings per-robot per una specifica organizzazione e modello di processo. Il query param `idprocessmodel` è richiesto: senza, il server cerca la riga org-level (idprocessmodel is null) che di norma non esiste. Include il payload `datajson` con i parametri runtime del robot.

{
  "id": 1,
  "idorganization": 1,
  "idrobot": 1,
  "idprocessmodel": null,
  "linkedto": "",
  "datajson": {
    "properties": {
      "campo1 ssss": {
        "type": "...",
        "value": "Test"
      }
    }
  }
}

• idID della riga di configurazione.
• idorganizationID dell'organizzazione in cui viene eseguita l'operazione: coincide con quella associata all'API key (JWT) del robot.
• idrobotID del robot a cui si riferiscono i dati.
• idprocessmodelID del modello di processo (BPMN) a cui si riferisce l'operazione.
• linkedtoRiferimento interno di collegamento (in genere vuoto).
• datajsonConfigurazione e parametri runtime del robot in formato JSON libero: letta in bootstrap e interpretata dal robot.
• propertiesMappa nome → {type, value} con i parametri runtime del robot.