Este documento tem o propósito de fornecer orientações a respeito dos Web Services disponibilizados para integração com o Gerenciamento de Serviço do CITSmart.
Os Web Services foram criados no CITSmart para inclusão, atualização, consulta e cancelamento de solicitações de serviço (incidentes e requisições).
Antes de começar
Antes de se utilizar qualquer operação REST do CITSmart, é necessário que o usuário esteja autenticado.
A autenticação é feita através da operação REST login na URL /services/login, que recebe um objeto CtLogin contendo os atributos userName, password e mediatype.
A operação login retorna um valor alfanumérico no atributo SessionID. Este mesmo SessionID deve ser utilizado nas outras chamadas REST. O objeto retornado contém o código e descrição do erro em caso de problemas na execução da operação login.
O usuário autenticado compõe a chave para sincronização dos dados, quando o atributo synchronize tiver o valor true.
O serviço de atualização de solicitações contam com o atributo synchronize. Quando este atributo for true, o cadastro de usuário e o catálogo serviços serão automaticamente atualizados no CITSmart a partir das informações enviadas na solicitação do WebService.
REGRA: Todos os serviços REST criados no CITSmart recebem um objeto de entrada e retornam um objeto. Em caso de erro, o objeto de retorno contém o código e a descrição do erro. Quando não houver erro, além dos atributos definidos para cada serviço, o objeto de retorno contém a data e hora de execução e o id da operação. O CITSmart garante que toda solicitação é registrada na sua base de dados e um ID da operação é retornado para o solicitante, mesmo em caso de erro.
Ações
Criar um ticket (request_create)
Pré-condições: configurar os contratos, grupos, fluxos e permissões.
Criando uma Requisição/Incidente
URL
Atributos de entrada
Atributos de Saída
JSON
{"Synchronize":true,"sourceRequest":{"numberOrigin":"9999","type":"R","userID":" 61 84460708 "," email ":" [email protected] "," department ":" Department of the So-and-so "," name ":" So-and-so "}," description ":" REST v3 "," service ":{" name ":" SERVICE.TEST.1 "," category ":{" name ":" Category 1 "}}," contractID ":" 1 "," urgency ":"H","impact":"H"}}
Supondo que no atributo platform no login foi informado "usuário" e considerando o atributo synchronize igual a true, o 4biz irá:- Verificar se existe um DE-PARA do contrato 1 para o "usuário";- Incluir o solicitante no cadastro de usuários, caso não exista na base;- Incluir o serviço no catálogo de serviços do contrato 1, caso não exista na base e registrar o DE-PARA de serviços para o cliente;- Incluir a solicitação com número de origem 9999;- Registrar o DE-PARA da solicitação de origem 9999 para o cliente.
Alteração de Informações de um Ticket (create)
Alterando informação de Requisição/Incidente
URL
Atributos de entrada
Atributos de Saída
JSON
{"Synchronize":true,"request":{"numberOrigin":"9999","userID":"ciclano.de.tal","contact":{"phoneNumber":"61 84460709","email""Cyclone","name":"Cyclone of such"},"description":"Inclusion of request using REST v3 - Changed","[email protected]","department""Service":{"name":"SERVICO.TESTE.2","category":{"name":"Category 2"}}}}
Supondo que no atributo platform no login foi informado "usuário" e considerando o atributo synchronize igual a true, o 4biz irá:
Incluir o solicitante no cadastro de usuários, caso não exista na base;
Incluir o serviço no catálogo de serviços do contrato 1, caso não exista na base e registrar o DE-PARA de serviços para o cliente;
Alterar o solicitante e serviço da solicitação com número de origem 9999.
Objeto da classe CtOcurrence containing:
number - número do evento na 4biz.
numberOrigin - número da ocorrência no sistema de origem.
description - descrição da ocorrência.
date - data do registro da ocorrência.
Hour - hora para registrar a ocorrência no formato HH:MM.
userID - identificação do usuário responsável por registrar a ocorrência.
origin - origem da ocorrência. Valores possíveis: EMAIL, FONE_FAX, VOICE_MAIL, PERSONALLY, OTHERS.
category - categoria da ocorrência. Valores possibles: Creation, Monitoring, Update, Diagnosis, Investigation, Memo, Information, Return, Symptom, Outline, Executing, Exchanging, Reclaiming, Reclassification, Schedule, Suspend, Reopen, Targeting, Sharing, Cancellation Task, HomeSLA, SuspendedSLA, Approval, ReactivationSLA
elapsedTime - tempo gasto (para categoria do tipo de execução)
reason – motivo da ocorrência.
task - tarefa associada com a ocorrência, contendo:
number - número da tarefa.
name - nome da tarefa.
startDateTime - hora e data inicial.
endDateTime - hora e data da execução.
status - status da tarefa, contendo:
code - código da localização.
name - nome da situação.
userId - login do usuário responsável pela execução da tarefa.
Listar tickets para atendimento
Esse webservice deve ser utilizado para listar os usuários que podem ser solicitantes na abertura de um ticket.
O solicitante deve estar vinculado à um grupo que tenha permissão de criar em um fluxo de trabalho.
Esse webservice deve ser utilizado para retornar os tickets para atendimento dos analistas.
Pré-condições: Possuir acesso ao sistema e permissão de execução no fluxo de trabalho.
Gravar ticket em atendimento
URL
Possíveis códigos de retorno
Atributos de entrada
Atributos de saída
JSON
{"status":"SUCCESS","code":"200","message":"Request processed successfully","payload":{"idGrupoAtual":171,"idTarefa":8809,"idStatus":1,"status":"In Progress","dataHoraInicio":"2020-09-10 11:58:28 AM BRT","dataHoraInicioSLA":"2020-09-10 11:58:29 AM BRT","dataHoraLimite":"2020-09-10 17:08:00 PM BRT","dataHoraSolicitacao":"2020-09-10 11:58:28 AM BRT","descricao":"<div>test</div>","idCategoriaSolucao":13,"idCausaIncidente":7,"idContrato":52,"idServico":670,"idSolicitacaoServico":5712,"idSolicitante":456,"idUnidade":2,"impacto":"A","resposta":"Teste de Gravação via webservice","siglaGrupo":"LEVEL1","tarefa":"Answer Ticket","urgencia":"A","idUsuarioResponsavelAtual":254,"nomeGrupoAtual":"Level 1","solicitanteVip":false}}
Receber Unidades
Esse webservice deve ser utilizado para retornar as unidades ativas existentes no sistema para seleção na criação de um ticket.
Pré-condições: Esse webservice sofre alteração de resultados caso o parâmetro 61 - Vincula contratos a unidade (Ex.: S ou N) esteja ativo.
Para ler essa documentação, o usuário precisa estar logado na aplicação, e essa aplicação precisa estar na versão que possui esses webservices.
Listar tickets para atendimento
URL
Atributos de entrada
Atributos de saída
• "id" – Resposta que retorna o número do ticket;
• “tipo” - Resposta que retorna o tipo de demanda, ou seja, se é uma Requisição (R), Incidente (I) ou Procedimento(P);
• "nomePrioridade" – Resposta que retorna o nome da Prioridade dada ao ticket;
• “solicitacao” – Resposta que retorna a descrição da atividade solicitada;
• “tarefa” – Resposta que retorna a tarefa do fluxo que se encontra o ticket;
• “status” – Resposta que retorna a situação da tarefa do ticket listado;
• “dataLimite” – Resposta que retorna a data e a hora de encerramento da solicitação de serviço conforme o SLA e calendário vinculado a atividadexcontrato
• “statusFluxoNome” - Resposta que retorna a situação do SLA, podendo ser: Normal, A Vencer, Vencido, Suspenso.
Exemplo de resposta válida do webservice
"code": "200",
"message": "Request processed successfully",
"payload":{
"initialNumber": 1,
"lastPage": 1.0,
"finalNumber": 20,
"totalRequests": 168,
"result":
[
"id": 1251,
"tipo": "Incidente",
"nomePrioridade": "Medium",
"solicitacao": "Serviço de Incidente",
"tarefa": "Atender solicitacao",
"status": "NORMAL",
"dataLimite": "2020-06-09 09:18:00 AM UTC"
]
}
Receber ações de usuário em um ticket
Esse webservice deve ser utilizado para retornar as ações de usuário desenhadas em um fluxo de trabalho.
Pré-condições: O usuário que é passado no webservice precisa possuir acesso ao sistema.
O usuário que é passado no webservice deve possuir permissão de execução no fluxo de trabalho;
Para ler essa documentação, o usuário precisa estar logado na aplicação, e essa aplicação precisa estar na versão que possui esses webservices.
Receber ações de usuário em um ticket
URL
Atributos de entrada
Atributos de saída
• "id: Código da ação de fluxo cadastrada no desenho de fluxo;
• Name: Nome da ação de fluxo;
• Description: Descrição da ação de fluxo;
• requiresReason: Informa se o motivo é obrigatório, existe duas respostas para esse atributo:
o True: Quando o motivo for obrigatório;
o False: Quando o motivo não for obrigatório;
• approvalActionId: Retorna o código da resposta de aprovação;
• ticketStatusId: Retorna o código da situação do ticket;
{
"status": "SUCCESS",
"code": "200",
"message": "Request processed successfully",
"payload": [
{
"id": 1302,
"name": "ApproveTicket",
"description": "Approve Ticket",
"requiresReason": false,
"approvalActionId": 1,
"ticketStatusId": 1
},
{
"id": 1304,
"name": "DenyTicket",
"description": "Deny Ticket",
"requiresReason": false,
"approvalActionId": 2,
"ticketStatusId": 3
}
]
}
Listar anexos dos tickets
Esse webservice deve ser utilizado para retornar a lista dos anexos de um tickets para atendimento dos analistas.
Pré-condições: O usuário que é passado no webservice precisa possuir acesso ao sistema.
Para ler essa documentação, o usuário precisa estar logado na aplicação, e essa aplicação precisa estar na versão que possui esses webservices.
Observação: Esse documento contém todos os webservices necessários para anexo que inclui:
Listar anexos de um ticket;
Realizar download do anexo;
Anexar documento ao ticket (upload);
Deletar anexo do ticket
Listar anexos dos tickets
URL
Atributos de entrada
Atributos de saída
• "id" – Resposta que retorna o código do anexo contido no ticket;
• “name” - Resposta que retorna a descrição do anexo;
• "extension" – Resposta que retorna a extensão do anexo;
Exemplo de resposta válida do webservice
{
"status": "SUCCESS",
"code": "200",
"message": "Request processed successfully",
"payload": [
{
"id": 2253,
"name": "ei_1598697802049.png.png",
"extension": "png"
},
{
"id": 2252,
"name": "ei_1598697788434.jpg.jpg",
"extension": "jpg"
},
{
"id": 2251,
"name": "ei_1598697777801.jpg.jpg",
"extension": "jpg"
}
]
}
Realizar download de anexos de um ticket
Realizar download de anexos de um ticket
URL
Atributos de entrada
Atributos de saída
O próprio anexo
Exemplo de resposta válida do webservice
{
Não se aplica
}
Upload anexos dos tickets
Upload anexos dos tickets
URL
Atributos de entrada
Atributos de saída
• dateTime: Atributo obrigatório que indica data e hora de execução;
• dateTimeMilliseconds: Hora em milissegundos;
• operationID: Número da operação que foi realizada;
• error: Atributo obrigatório que indica se houve erro durante a execução do webservice;
Exemplo de resposta válida do webservice
{
"dateTime": "2020-05-19 14:56:00",
"dateTimeMilliseconds": 1589910960717,
"operationID": 603,
"error": null
}
Deleta anexos dos tickets
Deleta anexos dos tickets
URL
Atributos de entrada
Atributos de saída
{
Não se aplica
}
Exemplo de resposta válida do webservice
{
"status": "SUCCESS",
"code": "200",
}
Filtrar conhecimento
Deleta anexos dos tickets
URL
Atributos de entrada
Atributos de saída
• " status " – Resposta que retorna o status do serviço ;
• “code” - Resposta com o código de retorno;
• " message " – Resposta que apresenta a mensagem do código de retorno;
• “payload” – Resposta que apresenta: idBaseConhecimento e título;
Exemplo de resposta válida do webservice
{
"status": "SUCCESS",
"code": "200",
"message": "Request processed successfully",
"payload": [
{
"idBaseConhecimento": 555,
"titulo": "Applications instalation"
}
Detalhar Conhecimento, Listar anexos e Visualizar a quantidade de like e dislike do conhecimento
• authentication-token: Atributo obrigatório que recebe o código de autenticação do login
• knowledgeBaseId: Atributo que recebe o número do ticket
Exemplo de entrada no webservice
{
" authentication-token: ": " eyJhbGciOiJIUzUxMiJ9.eyJleHAiOjE2MDgxNDk2MjcsIm5hbWUiOiJDbGllbnRPbmUiLCJjb250cm9sIjoiN2IyMjY5NzAyMjNhMjIzMTM4MzkyZTM2MmUzMzM1MmUzMjMwMzIyMjJjMjI2ODZmNzM3NDIyM2EyMjMxMzgzOTJlMzYyZTMzMzUyZTMyMzAzMjIyN2QiLCJpc3N1ZWRBdCI6MTYwODE0NjAyNzIzNCwibG9jYWxlIjoiZW4iLCJjbGllbnRfaWQiOiJ1bmtub3duIiwidGltZW91dCI6MzYwMCwidXNlcm5hbWUiOiJjbGllbnQwMSJ9.zEfN_lP00Hgtp5ojWtMuIiqinxxnKs9VZY28tEPQskGUbYdIb9GXH33sjPYxrD-v9BRocDuDZoi7M6uMleGefQ",
}
Enviar like e Dislike
Deleta anexos dos tickets
URL
Atributos de entrada
• authentication-token: Atributo obrigatório que recebe o código de autenticação do login
• knowledgeBaseId: Atributo que recebe o número do ticket
• type: Atributo que recebe o tipo de voto
Exemplo de entrada no webservice
{
" authentication-token: ": " eyJhbGciOiJIUzUxMiJ9.eyJleHAiOjE2MDgxNDk2MjcsIm5hbWUiOiJDbGllbnRPbmUiLCJjb250cm9sIjoiN2IyMjY5NzAyMjNhMjIzMTM4MzkyZTM2MmUzMzM1MmUzMjMwMzIyMjJjMjI2ODZmNzM3NDIyM2EyMjMxMzgzOTJlMzYyZTMzMzUyZTMyMzAzMjIyN2QiLCJpc3N1ZWRBdCI6MTYwODE0NjAyNzIzNCwibG9jYWxlIjoiZW4iLCJjbGllbnRfaWQiOiJ1bmtub3duIiwidGltZW91dCI6MzYwMCwidXNlcm5hbWUiOiJjbGllbnQwMSJ9.zEfN_lP00Hgtp5ojWtMuIiqinxxnKs9VZY28tEPQskGUbYdIb9GXH33sjPYxrD-v9BRocDuDZoi7M6uMleGefQ",
}