Listar todas as solicitações do sistema

Nesta página você encontrará informações para conseguir consultar e filtrar dados das solicitações, como na página de monitoramento de solicitações, utilizando API's

Como listar solicitações utilizando as API's do Zeev?

O Zeev oferece dois endpoints diferentes para obter os dados de monitoramento de uma instância.

1. Se você precisa de filtros simples, o método GET oferece uma maneira mais prática de realizar a consulta

2. De preferência ao POST para consultas com filtros complexos;

Para consultar dados de monitoramento uma instância de solicitação utilizando as API's do Zeev, siga os passos abaixo:

1. Autenticação: Primeiro obtenha um token de autenticação com permissão de realizar essa operação;

2. Enviar a Requisição para:

   1. Listar todas as solicitações do sistema (GET) se tiver uma menor complexidade de filtros;

   2. Listar todas as solicitações do sistema (POST) se desejar aplicar filtros mais complexos;

3. Paginar: Observe que a consulta à essa API retorna um número limitado de registros; para obter todos os dados, será necessário implementar um algoritmo de paginação;

4. Rate limit: Se for paginar os resultados, respeite os limites máximos de solicitações;

5. oData: opcionalmente, utilize regras oData para manipular o resultado da API. Essa API aceita $select

Filtros obrigatórios

As regras de obrigatoriedade de atributos do corpo de requisição do Zeev variam de acordo com alguns cenários. Confira a relação abaixo:

• instanceId é obrigatório

• OU startDateIntervalBegin e startDateIntervalEnd são obrigatórios

• OU endDateIntervalBegin e endDateIntervalEnd são obrigatórios

• OU lastTaskEndDateIntervalBegin e lastTaskEndDateIntervalEnd são obrigatórios

Observe que o filtro pelo número específico da solicitação é obrigatório, OU um filtro por intervalo de datas é obrigatório para listar diversas solicitações.

Como incluir a lista de tarefas pendentes e de tarefas concluídas junto as informações da solicitação?

Por padrão, essa consulta não traz a lista de tarefas pendentes e já concluídas. Para trazer essa informação, você deve instruir a chamada da API explicitamente que deseja essa informação. Para isso, são disponibilizados dois parâmetros:

• showPendingInstanceTasks=true Indica que você deseja que a lista com informações das tarefas atualmente pendentes na solicitação sejam mostradas.

• showFinishedInstanceTasks=true Indica que você deseja que a lista com informações das tarefas já concluídas na solicitação sejam mostradas.

Se estiver usando o método POST, esses dois parâmetros fazem parte do corpo JSON de requisição:

{
    showPendingInstanceTasks: true,
    showFinishedInstanceTasks: true
}

Como incluir a lista das pessoas atualmente responsáveis por uma tarefa da solicitação?

Para trazer essa informação, é preciso, primeiro, que o parâmetro showPendingInstanceTasks=true seja ativado. Ele irá trazer a lista das tarefas pendentes.

Então, você deve acrescentar o parâmetro showPendingAssignees=true . Esse parâmetro indica que você quer trazer junto o nome e identificação das pessoas responsáveis por cada tarefa pendente.

Se estiver usando o método POST, esses parâmetros fazem parte do corpo JSON de requisição:

{
    showPendingInstanceTasks: true,
    showFinishedInstanceTasks: true,
    showPendingAssignees: true
}

Como incluir valores de campos de formulário?

Por padrão, essa API não traz os valores de campos de formulário da solicitação. Para trazer essa informação, você precisa informar explicitamente o identificador dos campos de formulário que você deseja obter, usando o parâmetro formFieldNames. Por exemplo:

formFieldNames=nomeCompleto&formFieldNames=idade&formFieldNames=endereco

Se estiver usando o método POST, esse parâmetro é enviado na forma de um Array:

{
    formFieldNames: ["nomeCompleto", "idade", "endereco"]
}

Como saber o resultado de uma instância de solicitação?

Para saber o status de uma solicitação, verifique os campos active e flowResult no resultado da requisição e siga estes passos:

1. Verifique se a solicitação está ativa:

   • Se a propriedade active for true, a solicitação está "Em andamento".

2. Quando a solicitação não está mais ativa (active é false):

   • Use o valor da propriedade flowResult para o status da solicitação.

[
    //Solicitação em andamento
    {
        "id": 10023,
        "masterInstanceId": null,
        "starterInstanceId": null,
        "requestName": "[API] - Exemplos de uso v. 1",
        "reportLink": "https://seu_dominio.do.zeev/2.0/audit?c=YcJ6Q4dIKU%2FJqd1DDab2JISTPWhElmIzmD1ATDmYetS3G1InNFs%2F%2F4WtD5%2FYVBEQeG3Bk2%2FG6aEUWWVNXoNV%2B9nvMgqylZARoIktsIEx9tk%3D",
        "confirmationCode": "2LOFYZ",
        "uid": "5e4eef27-c962-429b-8839-6db162e38a95",
        "simulation": false,
        "active": true, // em andamento
        "flowResult": "",
        "flowResultId": 3,
        "startDateTime": "2024-08-06T15:43:34",
        "endDateTime": null,
        "cancelUserId": null,
        "lastFinishedTaskDateTime": "2024-08-06T15:43:34",
        "leadTimeInDays": null,
        "flow": {
            "id": 2590,
            "uid": "7a14be33-361b-4bde-a5e0-e2174d947cc1",
            "name": "[API] - Exemplos de uso",
            "version": 1
        },
        "service": null,
        "formFields": [],
        "requester": {
            "id": 2075,
            "name": "Alan Cooper",
            "email": "[email protected]",
            "username": "[email protected]",
            "team": null,
            "position": null
        },
        "instanceTasks": null
    },
    // Solicitação concluída
     {
        "id": 10023,
        "masterInstanceId": null,
        "starterInstanceId": null,
        "requestName": "[API] - Exemplos de uso v. 1",
        "reportLink": "https://seu_dominio.do.zeev/2.0/audit?c=YcJ6Q4dIKU%2FJqd1DDab2JISTPWhElmIzmD1ATDmYetS3G1InNFs%2F%2F4WtD5%2FYVBEQeG3Bk2%2FG6aEUWWVNXoNV%2B9nvMgqylZARoIktsIEx9tk%3D",
        "confirmationCode": "2LOFYZ",
        "uid": "5e4eef27-c962-429b-8839-6db162e38a95",
        "simulation": false,
        "active": false, //Não está mais em andamento
        "flowResult": "Concluído", // Status da solicitação
        "flowResultId": 3,
        "startDateTime": "2024-08-06T15:43:34",
        "endDateTime": "2024-08-06T15:45:34",
        "cancelUserId": null,
        "lastFinishedTaskDateTime": "2024-08-06T15:45:34",
        "leadTimeInDays": 0.00,
        "flow": {
            "id": 2590,
            "uid": "7a14be33-361b-4bde-a5e0-e2174d947cc1",
            "name": "[API] - Exemplos de uso",
            "version": 1
        },
        "service": null,
        "formFields": [],
        "requester": {
            "id": 2075,
            "name": "Alan Cooper",
            "email": "[email protected]",
            "username": "[email protected]",
            "team": null,
            "position": null
        },
        "instanceTasks": null
    }
]

Listar todas instâncias de solicitações que a pessoa relacionada ao token possui permissão de consultar de acordo com filtros (Auth)

get

Parâmetros de consulta

startDateIntervalBeginstring · date-timeOpcional

Data de início do intervalo de solicitação

startDateIntervalEndstring · date-timeOpcional

Data de fim do intervalo de solicitação

endDateIntervalBeginstring · date-timeOpcional

Data de início do intervalo de fim da solicitação

endDateIntervalEndstring · date-timeOpcional

Data de fim do intervalo de fim da solicitação

lastTaskEndDateIntervalBeginstring · date-timeOpcional

Data de início do intervalo de última tarefa finalizada

lastTaskEndDateIntervalEndstring · date-timeOpcional

Data de fim do intervalo de última tarefa finalizada

simulationbooleanOpcional

Indicador se devem ser pesquisadas simulações

activebooleanOpcional

Indicador se devem ser pesquisas somente instâncias em andamento

instanceIdinteger · int32Opcional

Número identificador da instância de solicitação

flowIdinteger · int32Opcional

Número identificador do processo

flowUidstring · uuidOpcional

Código padrão GUID único do processo

serviceIdinteger · int32Opcional

Número identificador do serviço

serviceUidstring · uuidOpcional

Código padrão GUID único do serviço

allowOpenUrlsForFilesInFormbooleanOpcional

Indicador se deve ser listado a URL aberta dos arquivos no(s) formulário(s)

requesterUsernamestringOpcional

Username da pessoa solicitante

formFieldNamesstring[]Opcional

Lista de identificadores de campos do formulário que devem ser retornados na consulta

showPendingInstanceTasksbooleanOpcional

Indicador se devem ser listadas as tarefas pendentes

showFinishedInstanceTasksbooleanOpcional

Indicador se devem ser listadas as tarefas concluídas

showPendingAssigneesbooleanOpcional

Indicador se devem ser listadas os responsáveis por tarefas pendentes

recordsPerPageinteger · int32 · mín: 1 · máx: 100Opcional

Número máximo de registros por página

pageNumberinteger · int32 · mín: 1 · máx: 1000000Opcional

Número da página de registros

useCachebooleanOpcional

Indicador se deve ser utilizado cache

taskIdinteger · int32Opcional

Código de tarefa que será pesquisado

requesterTeamIdinteger · int32Opcional

Código do time do requisitante

currentRequesterTeamIdinteger · int32Opcional

Código do time do responsável atual

responsibleAppTeamIdinteger · int32Opcional

Código do time do responsável pelo aplicativo

taskStatusstringOpcional

Filtro para tarefa configurada, podem ser utilizados: - 'Current' = Em andamento nesta tarefa; - 'Passed' = Solicitação já passou alguma vez pela tarefa; - 'Unavailable' = Solicitação não passou nenhuma vez pela tarefa.

Respostas

200

Sucesso

application/jsontext/jsontext/xml

400

Solicitação ou dados da solicitação são inválidas

application/jsontext/jsontext/xml

401

Pessoa não autorizada

application/jsontext/jsontext/xml

403

Pessoa não tem permissão de executar essa operação

application/jsontext/jsontext/xml

404

O registro não foi encontrado

application/jsontext/jsontext/xml

429

Muitas requisições em um determinado período de tempo

application/jsontext/jsontext/xml

500

Ocorreu algum erro interno no servidor

application/jsontext/jsontext/xml

get

/api/2/instances/report

HTTPcURLJavaScriptPython

GET /api/2/instances/report HTTP/1.1
Host: seu_endereco.do.zeev
Accept: */*

[
  {
    "id": 1,
    "masterInstanceId": 1,
    "starterInstanceId": 1,
    "requestName": "text",
    "reportLink": "text",
    "confirmationCode": "text",
    "uid": "00000000-0000-0000-0000-000000000000",
    "simulation": true,
    "active": true,
    "flowResult": "text",
    "flowResultId": 1,
    "startDateTime": "2026-02-04T01:14:56.507Z",
    "endDateTime": "2026-02-04T01:14:56.507Z",
    "cancelUserId": 1,
    "lastFinishedTaskDateTime": "2026-02-04T01:14:56.507Z",
    "leadTimeInDays": 1,
    "flow": {
      "id": 1,
      "uid": "00000000-0000-0000-0000-000000000000",
      "name": "text",
      "version": 1
    },
    "service": {
      "id": 1,
      "uid": "00000000-0000-0000-0000-000000000000",
      "name": "text"
    },
    "formFields": [
      {
        "id": 1,
        "name": "text",
        "value": "text",
        "openUrl": "text",
        "row": 1
      }
    ],
    "requester": {
      "id": 1,
      "name": "text",
      "email": "text",
      "username": "text",
      "team": {
        "id": 1,
        "name": "text",
        "code": "text"
      },
      "position": {
        "id": 1,
        "name": "text",
        "code": "text"
      }
    },
    "instanceTasks": [
      {
        "id": 1,
        "subprocessId": 1,
        "startDateTime": "2026-02-04T01:14:56.507Z",
        "endDateTime": "2026-02-04T01:14:56.507Z",
        "expectedEndDateTime": "2026-02-04T01:14:56.507Z",
        "leadTimeInDays": 1,
        "onTime": true,
        "active": true,
        "result": "text",
        "alias": "text",
        "task": {
          "id": 1,
          "name": "text",
          "type": "text",
          "businessHours": true,
          "timeout": 1
        },
        "executor": {
          "userId": 1,
          "name": "text",
          "email": "text",
          "username": "text"
        },
        "assignees": [
          {
            "id": 1,
            "userId": 1,
            "name": "text",
            "email": "text",
            "username": "text",
            "team": {
              "id": 1,
              "name": "text",
              "code": "text"
            },
            "position": {
              "id": 1,
              "name": "text",
              "code": "text"
            }
          }
        ]
      }
    ]
  }
]

A URL aberta gerada em allowOpenUrlsForFilesInForm tem prazo de validade de 5min.

Exemplo de requisição Get para o endpoint Listar todas as solicitações do sistema

Node.js

let instanceId = 1234;
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer TOKEN_DO_USUARIO");

const requestOptions = {
  method: "GET",
  headers: myHeaders
};

try {
  const response = await fetch($`https://seu_endereco.do.zeev/api/2/instances/report?instanceId=${instanceId}`, requestOptions);
  const result = await response.json();
  console.log(result)
} catch (error) {
  console.error(error);
};

Listar todas instâncias de solicitações que a pessoa relacionada ao token possui permissão de consultar de acordo com filtros (Auth)

post

Corpo

application/json

startDateIntervalBeginstring · date-timeOpcional

Data de início do intervalo de solicitação

startDateIntervalEndstring · date-timeOpcional

Data de fim do intervalo de solicitação

endDateIntervalBeginstring · date-timeOpcional

Data de início do intervalo de fim da solicitação

endDateIntervalEndstring · date-timeOpcional

Data de fim do intervalo de fim da solicitação

lastTaskEndDateIntervalBeginstring · date-timeOpcional

Data de início do intervalo de última tarefa finalizada

lastTaskEndDateIntervalEndstring · date-timeOpcional

Data de fim do intervalo de última tarefa finalizada

simulationbooleanOpcional

Indicador se devem ser pesquisadas simulações

activebooleanOpcional

Indicador se devem ser pesquisas somente instâncias em andamento

instanceIdinteger · int32Opcional

Número identificador da instância de solicitação

flowIdinteger · int32Opcional

Número identificador do processo

flowUidstring · uuidOpcional

Código padrão GUID único do processo

Example: 00000000-0000-0000-0000-000000000000

serviceIdinteger · int32Opcional

Número identificador do serviço

serviceUidstring · uuidOpcional

Código padrão GUID único do serviço

Example: 00000000-0000-0000-0000-000000000000

mobileEnabledOnlybooleanOpcional

Indicador se devem ser listados somente processos habilitados para mobile

allowOpenUrlsForFilesInFormbooleanOpcional

Indicador se deve ser listado a URL aberta dos arquivos no(s) formulário(s)

requesterUsernamestringOpcional

Username da pessoa solicitante

formFieldNamesstring[]Opcional

Lista de identificadores de campos do formulário que devem ser retornados na consulta

showPendingInstanceTasksbooleanOpcional

Indicador se devem ser listadas as tarefas pendentes

showFinishedInstanceTasksbooleanOpcional

Indicador se devem ser listadas as tarefas concluídas

showPendingAssigneesbooleanOpcional

Indicador se devem ser listadas os responsáveis por tarefas pendentes

recordsPerPageinteger · int32 · mín: 1 · máx: 100Opcional

Número máximo de registros por página

pageNumberinteger · int32 · mín: 1 · máx: 1000000Opcional

Número da página de registros

useCachebooleanOpcional

Indicador se deve ser utilizado cache

taskIdinteger · int32Opcional

Código de tarefa que será pesquisado

requesterTeamIdinteger · int32Opcional

Código do time do requisitante

currentRequesterTeamIdinteger · int32Opcional

Código do time do responsável atual

responsibleAppTeamIdinteger · int32Opcional

Código do time do responsável pelo aplicativo

taskStatusstringOpcional

Filtro para tarefa configurada, podem ser utilizados: - 'Current' = Em andamento nesta tarefa; - 'Passed' = Solicitação já passou alguma vez pela tarefa; - 'Unavailable' = Solicitação não passou nenhuma vez pela tarefa.

Respostas

200

Sucesso

application/jsontext/jsontext/xml

400

Solicitação ou dados da solicitação são inválidas

application/jsontext/jsontext/xml

401

Pessoa não autorizada

application/jsontext/jsontext/xml

403

Pessoa não tem permissão de executar essa operação

application/jsontext/jsontext/xml

404

O registro não foi encontrado

application/jsontext/jsontext/xml

429

Muitas requisições em um determinado período de tempo

application/jsontext/jsontext/xml

500

Ocorreu algum erro interno no servidor

application/jsontext/jsontext/xml

post

/api/2/instances/report

HTTPcURLJavaScriptPython

POST /api/2/instances/report HTTP/1.1
Host: seu_endereco.do.zeev
Content-Type: application/json
Accept: */*
Content-Length: 1040

{
  "appCode": "XkasdjlmexlW2902_",
  "startDateIntervalBegin": "2020-01-31T00:00:00",
  "startDateIntervalEnd": "2020-12-31T23:59:59",
  "endDateIntervalBegin": "2020-01-31T00:00:00",
  "endDateIntervalEnd": "2020-01-31T00:00:00",
  "lastTaskEndDateIntervalBegin": "2020-01-31T00:00:00",
  "lastTaskEndDateIntervalEnd": "2020-01-31T00:00:00",
  "simulation": false,
  "active": true,
  "instanceId": 1000,
  "flowId": 100,
  "serviceId": 200,
  "mobileEnabledOnly": false,
  "allowOpenUrlsForFilesInForm": false,
  "requesterUsername": "steve.jobs",
  "formFieldNames": [
    "razaoSocial",
    "cidade",
    "uf"
  ],
  "formFieldsFilter": [
    {
      "name": "tipoPagamento",
      "operator": "=",
      "value": "Cartão de crédito"
    }
  ],
  "showPendingInstanceTasks": false,
  "showFinishedInstanceTasks": false,
  "showPendingAssignees": false,
  "recordsPerPage": 10,
  "pageNumber": 1,
  "useCache": true,
  "taskId": 0,
  "requesterTeamId": 0,
  "currentRequesterTeamId": 0,
  "responsibleAppTeamId": 0,
  "taskStatus": "Current = (Em andamento nesta tarefa) | Passed = (Solicitação já passou alguma vez pela tarefa) | Unavailable = (Solicitação não passou nenhuma vez pela tarefa)"
}

[
  {
    "id": 1,
    "masterInstanceId": 1,
    "starterInstanceId": 1,
    "requestName": "text",
    "reportLink": "text",
    "confirmationCode": "text",
    "uid": "00000000-0000-0000-0000-000000000000",
    "simulation": true,
    "active": true,
    "flowResult": "text",
    "flowResultId": 1,
    "startDateTime": "2026-02-04T01:14:56.507Z",
    "endDateTime": "2026-02-04T01:14:56.507Z",
    "cancelUserId": 1,
    "lastFinishedTaskDateTime": "2026-02-04T01:14:56.507Z",
    "leadTimeInDays": 1,
    "flow": {
      "id": 1,
      "uid": "00000000-0000-0000-0000-000000000000",
      "name": "text",
      "version": 1
    },
    "service": {
      "id": 1,
      "uid": "00000000-0000-0000-0000-000000000000",
      "name": "text"
    },
    "formFields": [
      {
        "id": 1,
        "name": "text",
        "value": "text",
        "openUrl": "text",
        "row": 1
      }
    ],
    "requester": {
      "id": 1,
      "name": "text",
      "email": "text",
      "username": "text",
      "team": {
        "id": 1,
        "name": "text",
        "code": "text"
      },
      "position": {
        "id": 1,
        "name": "text",
        "code": "text"
      }
    },
    "instanceTasks": [
      {
        "id": 1,
        "subprocessId": 1,
        "startDateTime": "2026-02-04T01:14:56.507Z",
        "endDateTime": "2026-02-04T01:14:56.507Z",
        "expectedEndDateTime": "2026-02-04T01:14:56.507Z",
        "leadTimeInDays": 1,
        "onTime": true,
        "active": true,
        "result": "text",
        "alias": "text",
        "task": {
          "id": 1,
          "name": "text",
          "type": "text",
          "businessHours": true,
          "timeout": 1
        },
        "executor": {
          "userId": 1,
          "name": "text",
          "email": "text",
          "username": "text"
        },
        "assignees": [
          {
            "id": 1,
            "userId": 1,
            "name": "text",
            "email": "text",
            "username": "text",
            "team": {
              "id": 1,
              "name": "text",
              "code": "text"
            },
            "position": {
              "id": 1,
              "name": "text",
              "code": "text"
            }
          }
        ]
      }
    ]
  }
]

Exemplos de requisição para o endpoint Listar todas as solicitações do sistema

Node.js

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer TOKEN_DO_USUARIO");

const raw = JSON.stringify({
  "startDateIntervalBegin": "2020-01-31T00:00:00",
  "startDateIntervalEnd": "2020-12-31T23:59:59",
  "endDateIntervalBegin": "2020-01-31T00:00:00",
  "endDateIntervalEnd": "2020-01-31T00:00:00",
  "lastTaskEndDateIntervalBegin": "2020-01-31T00:00:00",
  "lastTaskEndDateIntervalEnd": "2020-01-31T00:00:00",
  "simulation": false,
  "active": true,
  "instanceId": 1000,
  "flowId": 100,
  "serviceId": 200,
  "mobileEnabledOnly": false,
  "allowOpenUrlsForFilesInForm": false,
  "requesterUsername": "steve.jobs",
  "formFieldNames": [
    "razaoSocial",
    "cidade",
    "uf"
  ],
  "formFieldsFilter": [
    {
      "name": "tipoPagamento",
      "operator": "=", //deve estar preenchido exatamente com o valor
      "value": "Cartão de crédito"
    },
    {
      "name": "valor",
      "operator": ">", //deve ser maior que o valor
      "value": "500"
    },
    {
      "name": "parcelas",
      "operator": "<", //deve ser menor que o valor
      "value": "12"
    },
    {
      "name": "nomeCliente",
      "operator": "like", //deve conter o valor
      "value": "pedro"
    },
    {
      "name": "idadeCliente",
      "operator": "<>", //deve ser diferente do valor
      "value": "18"
    },
    {
      "name":"cidade",
      "operator":"not like", //Não deve conter o valor
      "value":"São"
    }
  ],
  "showPendingInstanceTasks": false,
  "showFinishedInstanceTasks": false,
  "showPendingAssignees": false,
  "recordsPerPage": 10,
  "pageNumber": 1,
  "useCache": true,
  "taskId": 0,
  "requesterTeamId": 0,
  "currentRequesterTeamId": 0,
  "responsibleAppTeamId": 0,
  "taskStatus": "Current = (Em andamento nesta tarefa) | Passed = (Solicitação já passou alguma vez pela tarefa) | Unavailable = (Solicitação não passou nenhuma vez pela tarefa)"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw
};

try {
  const response = await fetch("https://seu_endereco.do.zeev/api/2/instances/report", requestOptions);
  const result = await response.json();
  console.log(result)
} catch (error) {
  console.error(error);
};

---

Links relacionados

• O que é preciso para fazer integrações do Zeev para outros sistemas?

• Como autenticar nas APIs do Zeev

• Como controlar o volume máximo de requisições à APIs

• Como acessar o Swagger / OpenAPI

• Como filtrar e monitorar solicitações