Referência de ajuda da API Flowenti Robots

Retorna o contexto da organização associada à API Key emitida para o robô. Deve ser chamado antes de qualquer outra solicitação.

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

• organizationsLista das organizações ligadas à API key do robô: com um token de robô contém apenas uma.
• idID numérico da organização: é o valor a usar como {idorganization} nos outros endpoints.
• nameNome visível da organização.
• administratortrue se o robô opera com permissões de administrador da organização.
• subscriptionnameNome do plano/subscrição da organização (pode estar vazio).
• hasmultipleusertrue se a organização tem vários utilizadores associados.
• creationData/hora de criação da organização (ISO 8601).
• deletedtrue se a organização foi eliminada (soft delete).
• iconÍcone/logótipo da organização (null se não definido).

Descubra quais processos o robô está autorizado a iniciar na organização especificada.

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

• possiblestartLista de eventos de início disponíveis: cada entrada é um processo que o robô pode instanciar.
• idID do evento de início: é o valor a usar como {idevent} no arranque do processo.
• nameNome do evento de início (pode estar vazio).
• idtypeTipo de evento de início definido no modelo BPMN.
• idprocessmodelID do modelo de processo (BPMN) a que a operação se refere.
• processmodelnameNome do modelo de processo (BPMN) a que o evento de início pertence.
• idswimlaneID da lane (swimlane) atribuída às atividades do processo arrancado.
• swimlanenameNome da lane associada.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• assignmentmodeModo de atribuição de tarefas definido no modelo (0 = atribuição automática a partir da fila).
• userschemaEsquema de utilizadores admitidos (JSON serializado) associado ao evento de início.

Instancia um novo processo BPMN gerando o token inicial de avanço.

{
  "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 do modelo de processo (BPMN) a que a operação se refere.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• ideventID do evento de início do modelo que instancia o processo: escolher em /startevents/organizations/{idorganization}.
• startdateData/hora de início do processo em formato ISO 8601 (ex. 2026-08-26T08:00:00Z).
• enddateData/hora de fim do processo; null até o processo ser encerrado.
• descriptionDescrição breve do processo, visível na interface (ex. Fatura #2026-0451).
• descriptiondetailDescrição alargada opcional com os detalhes operativos da instância do processo.
• userdataObjeto com dados livres ligados à instância (ex. cliente): persistentes durante toda a vida do processo.

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

• processProcesso instanciado: o campo id é a referência global para a leitura de anexos e consultas ao processo.
• processtokenToken de avanço criado ou movido pela operação: é a unidade de trabalho que o robô conduz nó a nó.
• idID do token de avanço: identificador único da unidade de trabalho.
• stateEstado do token: 0 = à espera (todo), 1 = em execução (doing), 2 = concluída (done).
• previousprocesstokenEstado do token antes da operação: útil para auditoria e para reconstruir o histórico do processo.

Consulta o sistema para verificar a existência de tarefas disponíveis que o robô pode assumir.

{
  "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": []
}

• waitingflownodesTarefas à espera (estado todo) que o robô pode assumir com nextstate/doing.
• doingflownodesTarefas atualmente em execução (estado doing) pelo robô.
• idprocesstokenID do token de avanço sobre o qual operar nas chamadas seguintes (nextstate, anexos, exit).
• idflownodeID do nó de atividade: é o valor a usar como {idflownode} no body de nextstate.
• designeridID alfanumérico do nó no diagrama BPMN (id XML do designer): necessário para /exit/{designerid} nos gateways.
• flownodenameNome legível da atividade tal como desenhada no modelo BPMN.
• idprocessID do processo a que a tarefa pertence: necessário para a leitura de anexos (/processes/{idprocess}/attachments/light).
• idprocessmodelID do modelo de processo (BPMN) a que a operação se refere.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• processmodelnameNome do modelo de processo (BPMN) a que o evento de início pertence.
• stateEstado do token: 0 = à espera (todo), 1 = em execução (doing), 2 = concluída (done).
• priority_namePrioridade da tarefa definida no modelo (ex. HIGH): guia a ordem de processamento.
• countcommentsNúmero de comentários presentes na tarefa (apenas leitura).
• countattachmentsNúmero de anexos já presentes na tarefa (apenas leitura).

Notifica à Flowenti a tomada da tarefa pelo robô, mudando o estado do token para

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

• idflownodeID do nó de atividade (flownode) a que a ação se refere: chega na lista waitingflownodes devolvida pelo polling.
• iduserrobotID do utilizador/robô que executa a operação: o associado ao token JWT do robô.

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

• idtokenID do token cujo estado mudou em resultado da operação.
• stateEstado do token: 0 = à espera (todo), 1 = em execução (doing), 2 = concluída (done).
• claimedAtData/hora da assunção da tarefa (ISO 8601).
• iduserrobotID do utilizador/robô que executa a operação: o associado ao token JWT do robô.

Marca a conclusão bem-sucedida da tarefa e avança o fluxo para o próximo nó.

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

• idflownodeID do nó de atividade (flownode) a que a ação se refere: chega na lista waitingflownodes devolvida pelo polling.
• resultPayload de resultado em formato livre com os dados produzidos pela tarefa (ex. campos extraídos): é guardado no processo e fica disponível para os nós seguintes.

{
  "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 instanciado: o campo id é a referência global para a leitura de anexos e consultas ao processo.
• processtokenToken de avanço criado ou movido pela operação: é a unidade de trabalho que o robô conduz nó a nó.
• idID do token de avanço: identificador único da unidade de trabalho.
• idprocessID do processo a que o token pertence.
• idflownodeID do nó (atividade ou evento) em que o token se encontra.
• flownodetypeTipo de nó (0 = evento, 1 = atividade, ...).
• iduserID do utilizador/robô que tem o token a seu cargo (0 se em fila).
• stateEstado do token: 0 = à espera (todo), 1 = em execução (doing), 2 = concluída (done).
• previousID do token anterior no histórico do processo.
• createdData/hora de criação do token (ISO 8601).
• startdoingData/hora de assunção da tarefa; null até o token passar a doing.
• doneData/hora de conclusão; null até o token passar a done.
• previousprocesstokenEstado do token antes da operação: útil para auditoria e para reconstruir o histórico do processo.
• previousflownodeNó de onde o token provém antes da operação.
• flownodeNó (atividade ou evento) em que o token se encontra agora.
• sequenceflowsFluxos de sequência alcançáveis a partir do nó atual: não vazio quando são necessárias decisões subsequentes.

Anula a última ação do robô na tarefa (undo): traz o estado do token de Em execução (Doing, 1) de volta para Em espera (ToDo, 0) e devolve a tarefa à fila das disponíveis. É o único mecanismo de recuperação hoje suportado — não existem nextstate/error, failed ou abort — para usar quando o runtime do robô não consegue completar a atividade.

{
  "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 instanciado: o campo id é a referência global para a leitura de anexos e consultas ao processo.
• processtokenToken de avanço criado ou movido pela operação: é a unidade de trabalho que o robô conduz nó a nó.
• idID do token de avanço: identificador único da unidade de trabalho.
• idprocessID do processo a que o token pertence.
• idflownodeID do nó (atividade ou evento) em que o token se encontra.
• flownodetypeTipo de nó (0 = evento, 1 = atividade, ...).
• iduserID do utilizador/robô que tem o token a seu cargo (0 se em fila).
• stateEstado do token: 0 = à espera (todo), 1 = em execução (doing), 2 = concluída (done).
• previousID do token anterior no histórico do processo.
• createdData/hora de criação do token (ISO 8601).
• startdoingData/hora de assunção da tarefa; null até o token passar a doing.
• doneData/hora de conclusão; null até o token passar a done.
• flownodeNó (atividade ou evento) em que o token se encontra agora.
• previousflownodeNó de onde o token provém antes da operação.
• previousprocesstokenEstado do token antes da operação: útil para auditoria e para reconstruir o histórico do processo.

Seleciona a saída específica do gateway quando o fluxo BPMN encontra uma decisão condicional ou um ramo guiado pelo robô.

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

• reasonEtiqueta livre que documenta o motivo da escolha do ramo do gateway (ex. validated_by_robot).
• metadataObjeto opcional com dados adicionais sobre a decisão (ex. pontuação de validação).

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

• idtokenID do token cujo estado mudou em resultado da operação.
• selectedExitNome da saída do gateway selecionada pelo robô.
• designeridID alfanumérico do nó no diagrama BPMN (id XML do designer): necessário para /exit/{designerid} nos gateways.
• advancedAtData/hora do avanço (ISO 8601).

Envia um arquivo/documento anexado ao nó atual do processo (usa

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

• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• filenameNome do ficheiro com extensão, tal como deve constar no anexo.
• cloudlinkURL cloud alternativo ao upload binário: se preenchido, o anexo aponta para um recurso remoto em vez do blob.
• idtypeTipo de anexo (idtype): identificador da categoria de ficheiro gerida pela plataforma.
• descriptionDescrição breve do processo, visível na interface (ex. Fatura #2026-0451).
• blobConteúdo do ficheiro codificado em base64; size é o tamanho em bytes.
• sizeTamanho do ficheiro em bytes, coerente com o conteúdo do blob.

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

• idattachmentID do anexo criado: a referenciar em eventuais operações seguintes.
• idprocesstokenID do token de avanço sobre o qual operar nas chamadas seguintes (nextstate, anexos, exit).
• filenameNome do ficheiro com extensão, tal como deve constar no anexo.
• sizeTamanho do ficheiro em bytes, coerente com o conteúdo do blob.
• uploadedAtData/hora do upload (ISO 8601).

Lê a lista leve de todos os anexos do processo (usa

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

• attachmentsLista dos anexos do processo: uma entrada por cada ficheiro carregado.
• idID do anexo.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• filenameNome do ficheiro com extensão, tal como deve constar no anexo.
• descriptionDescrição do anexo (vazia se não fornecida no upload).
• idtypeTipo de anexo (idtype): identificador da categoria de ficheiro gerida pela plataforma.
• cloudlinkURL cloud alternativo ao upload binário: se preenchido, o anexo aponta para um recurso remoto em vez do blob.
• creationData/hora de criação do anexo (ISO 8601).
• iduserID do utilizador que carregou o anexo (0 para os robôs).
• usernameNome de utilizador de quem carregou o anexo (vazio para os robôs).
• activitynameNome da atividade (nó BPMN) a que o anexo está associado.

Variante de /tasks/doing filtrada por organização. Devolve as tarefas Doing do robô atual para uma única organização.

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

• doingflownodesTarefas atualmente em execução (estado doing) pelo robô.
• idprocesstokenID do token de avanço sobre o qual operar nas chamadas seguintes (nextstate, anexos, exit).
• idprocessID do processo a que a tarefa pertence: necessário para a leitura de anexos (/processes/{idprocess}/attachments/light).
• idflownodeID do nó de atividade: é o valor a usar como {idflownode} no body de nextstate.
• flownodenameNome legível da atividade tal como desenhada no modelo BPMN.
• priority_namePrioridade da tarefa definida no modelo (ex. HIGH): guia a ordem de processamento.

Descoberta global de todos os eventos de início disponíveis para o robô em todas as organizações. 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": "..."
    }
  ]
}

• possiblestartLista de eventos de início disponíveis: cada entrada é um processo que o robô pode instanciar.
• idID do evento de início: é o valor a usar como {idevent} no arranque do processo.
• nameNome do evento de início (pode estar vazio).
• idtypeTipo de evento de início definido no modelo BPMN.
• idprocessmodelID do modelo de processo (BPMN) a que a operação se refere.
• processmodelnameNome do modelo de processo (BPMN) a que o evento de início pertence.
• idswimlaneID da lane (swimlane) atribuída às atividades do processo arrancado.
• swimlanenameNome da lane associada.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• assignmentmodeModo de atribuição de tarefas definido no modelo (0 = atribuição automática a partir da fila).
• userschemaEsquema de utilizadores admitidos (JSON serializado) associado ao evento de início.

Recupera a configuração JSON do robô para a organização e o modelo de processo indicados. Usada em bootstrap para ler parâmetros de driver, endpoints remotos, credenciais de integração.

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

• idID da linha de configuração.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• idrobotID do robô a que os dados se referem.
• idprocessmodelID do modelo de processo (BPMN) a que a operação se refere.
• linkedtoReferência interna de ligação (normalmente vazia).
• datajsonConfiguração e parâmetros runtime do robô em JSON livre: lida em bootstrap e interpretada pelo robô.

Lista as organizações associadas ao robô atual com as respetivas tags (urgente, rotina, batch, etc.). Útil para encaminhar a tarefa à organização correta antes de a assumir.

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

• idrobotID do robô a que os dados se referem.
• organizationsLista das organizações ligadas à API key do robô: com um token de robô contém apenas uma.
• idID numérico da organização: é o valor a usar como {idorganization} nos outros endpoints.
• nameNome visível da organização.
• tagsTags associadas à organização (ex. urgente, rotina, batch).
• tags.idID da tag.
• tags.nameNome da tag (ex. urgente).
• tags.idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• tags.colorCor da tag em formato hex (ex. #ff0000).

Definições por-robô para uma organização e modelo de processo específicos. O query param `idprocessmodel` é obrigatório: sem ele, o servidor procura a linha ao nível da organização (idprocessmodel is null), que normalmente não existe. Inclui o payload datajson com os parâmetros runtime do robô.

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

• idID da linha de configuração.
• idorganizationID da organização onde a operação é executada: a mesma associada à API key (JWT) do robô.
• idrobotID do robô a que os dados se referem.
• idprocessmodelID do modelo de processo (BPMN) a que a operação se refere.
• linkedtoReferência interna de ligação (normalmente vazia).
• datajsonConfiguração e parâmetros runtime do robô em JSON livre: lida em bootstrap e interpretada pelo robô.
• propertiesMapa nome → {type, value} com os parâmetros runtime do robô.