Webservices para uso na plataforma CITSmart

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

    {"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

    {"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.

Alteração da situação de um Ticket (updateStatus)

Alteração da situação de um Incidente/Requisição

       {"numberOrigin": "9999",
       "status": {"code": "Suspended",
       "details": "Integration Testing"}}

Consultar Tickets do Solicitante (getByUser)

Consultando Incidentes e Requisições do Solicitante

    {"userID": "john elliot ",
    "startDate": "2015-09-16T03:00:00.000Z",
    "endDate": "2015-09-19T03:00:00.000Z"}

Detalhes do Ticket de um Solicitante (getById)

Detalhes da Requisição/Incidente

    {"numberOrigin":"9999"}

Incluir Ocorrência no Ticket (createOccurrence)

Inclui uma ocorrência em uma solicitação

        {"requestNumberOrigin": "9999",
        "occurrence": {"description": "Occurrence test","category": {"code": "Workaround solution"},
        "date": "2015-08-20T03:00:00.000Z",
        "hour": "2219"}}

Consultar ocorrências do Ticket (listOccurrences)

Consultar informações das solicitações/incidentes

    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.

Listar requisições/incidentes para atendimento

    {
	    "status": "SUCCESS",
	    "code": "200",
	    "message": "Request processed successfully",
	    "payload": [
	        {
	            "id": 904,
	            "name": "Lucas Novais",
	            "email": "[email protected]",
	            "unit": {
	                "id": 1,
	                "name": "Default",
	                "places": [
	                    {
	                        "id": 1,
	                        "name": "Brasilia"
	                    }
	                ]
	            },
	            "phone": "(676) 76868-7687"
	        }
	    ]
	}

Gravar ticket em atendimento

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

    {
    	"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.

A documentação de desenvolvimento está no Swagger

Exemplo: https://presentation02.citsmartcloud.com/4biz/webmvc/swagger-ui.html#/

Para ler essa documentação, é preciso estar logado na aplicação, e essa aplicação precisa estar na versão que possui esses webservices.

Receber Unidades

    •	id:  Retorna o código da unidade;
    •	name: Retorna a descrição da unidade;
    Exemplo de saída no webservice
    {
        "status": "SUCCESS",
        "code": "200",
        "message": "Request processed successfully",
        "payload": [
            {
                "id": 52,
                "name": "---Human Resourcer"
            }
        ]
    }

Receber justificativa de suspensão

Esse webservice deve ser utilizado para retornar as justificativas de suspensão cadastradas e ativas no sistema.

Pré-condições: O usuário que é passado no webservice deve possuir permissão de suspender no fluxo de trabalho;

A documentação de desenvolvimento está no Swagger

Exemplo: https://presentation02.citsmartcloud.com/4biz/webmvc/swagger-ui.html#/

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 justificativa de suspensão

    •	id:  Retorna o código da Justificativa de suspensão;
    •	description: Retorna a descrição da Justificativa de suspensão
    Exemplo de saída no webservice
    {
        "status": "SUCCESS",
        "code": "200",
        "message": "Request processed successfully",
        "payload": [
            {
                "id": 1,
                "description": "Default"
            }
        ]
    }

Listar tickets para atendimento

Esse webservice deve ser utilizado para retornar as opções permitidas no fluxo em um determinado grupo.

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 no fluxo de trabalho;

A documentação de desenvolvimento está no Swagger

Exemplo: https://presentation02.citsmartcloud.com/4biz/webmvc/swagger-ui.html#/

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

    •	"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;

A documentação de desenvolvimento está no Swagger

Exemplo: https://presentation02.citsmartcloud.com/4biz/webmvc/swagger-ui.html#/

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

    •	"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.

A documentação de desenvolvimento está no Swagger

Exemplo: https://presentation02.citsmartcloud.com/4biz/webmvc/swagger-ui.html#/

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

    •	"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

    O próprio anexo
    Exemplo de resposta válida do webservice
    {
        Não se aplica   
    }

Upload anexos dos tickets

    •	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

        {
    Não se aplica
    }
    Exemplo de resposta válida do webservice
    {
        "status": "SUCCESS",
        "code": "200",
    }

Filtrar conhecimento

Deleta anexos dos tickets

    •	" 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

Deleta anexos dos tickets

    •	" 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: título, contente, version, totalLike, totalUnlike, liked, unliked, userCreated, lastPublicationDate, userUpdated, attachments
    Exemplo de resposta válida do webservice
    {
        "status": "SUCCESS",
        "code": "200",
        "message": "Request processed successfully",
        "payload": {
            "title": "Applications instalation",
            "content": "<p>Applications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalation</p>\n",
            "version": "1.0",
            "totalLike": 1,
            "totalUnlike": 0,
            "liked": false,
            "unliked": false,
            "userCreated": "Consultant",
            "lastPublicationDate": "2020-04-01 06:22:14 AM BRT",
            "userUpdated": "Vinny Gravito",
            "attachments": [
                {
                    "id": 606,
                    "name": "App instalation.pdf",
                    "extension": "pdf"
                }
            ]
        }
    }

Download de anexos

Deleta anexos dos tickets

        •	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

        •	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",
            }