Webservices para Uso na Plataforma 4biz
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 4biz.
Os Web Services foram criados no 4biz 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 4biz, é 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 platform.
- O atributo platform deve conter a identificação do site que está solicitando o serviço.
- 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.
- Os serviços de inclusão e 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 criados ou atualizados no 4biz a partir das informações enviadas na solicitação do Web Service.
✅ Regra: Todos os serviços REST criados no 4biz 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 4biz 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 (/servicerequestincident/create)
- Pré-condições: configurar os contratos, grupos, fluxos e permissões.
🖊 Nota: Para visualizar o título, o parâmetro 301 – Exibir título na solicitação serviço deverá estar habilitado.
O webservice apresentado abaixo cria um ticket para um usuário que possua cadastro no sistema.
Criando uma Requisição/Incidente:
/webmvc/servicerequestincident/createAlteraçã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:
/services/request/getByUserDetalhes do Ticket de um Solicitante (getById)
Detalhes da Requisição/Incidente:
/services/request/getByIdIncluir Ocorrência no Ticket (createOccurrence)
Inclui uma ocorrência em uma solicitação:
/services/request/createOccurrenceConsultar ocorrências do Ticket (listOccurrences)
Consultar informações das solicitações/incidentes:
/services/request/listOccurrencesListar tickets para atendimento
Esse webservice deve ser utilizado para listar os usuários que podem ser solicitantes na abertura de um ticket.
- Pré-condições: O solicitante deve estar vinculado à um grupo que tenha permissão de criar em um fluxo de trabalho.
Listar requisições/incidentes para atendimento:
/services/request/createOccurrence
/webmvc/servicerequestincident/searchTickets {
"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.
Para apenas gravar o ticket: webmvc/servicerequestincident/save
Para gravar e avançar o ticket: webmvc/servicerequestincident/nextReceber 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
Para ler essa documentação, é preciso estar logado na aplicação, e essa aplicação precisa estar na versão que possui esses webservices.
webmvc/ v1/unit
Método: GET
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 – Justificativa não encontradaReceber 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
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.
webmvc/v1/ticket/justification
Método: GET
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 – Justificativa não encontradaListar 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
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.
/webmvc/v1/ticket/{ticketId}/permissions
Método: GET
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 – Ticket not foundReceber 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
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.
webmvc/v1/ticket/{ticketId}/flow-actions
Método: GET
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 – Ticket não encontrado
Pós condição:
Para enviar a resposta selecionada na ação de usuário, utilize o webservice de Gravar e Avançar (webmvc/servicerequestincident/next)
Atributos:
"flowAction":
"reasonFlowAction":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
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
/webmvc/servicerequestincident/{serviceRequestIncidentId}/attachments
Método tipo: GET
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 - Ticket not foundRealizar download de anexos de um ticket
webmvc/servicerequestincident/{serviceRequestIncidentId}/attachments/{documentId}
Método tipo: GET
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 - Document or ticket not foundUpload anexos dos tickets
/webmvc/services/request/addAttachments Método tipo: POST
Pré Condição:
1. Verificar os parâmetros:
2. 44 - Diretório Upload repositório path (Ex.: Windows - C:/temp)
3. 278 - Tamanho máximo de arquivo, em bytes, para upload. Default[1073741824] = 1GB
4. 318 - Lista de extensões de arquivos que não poderão ser anexados (Para mais de uma extensão separar por ponto e vírgula)
5. 446 - Enviar anexos no e-mail de notificação do Ticket? (Ex.: S ou N - Default: 'N')
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
500 – Campos obrigatórios não informadosDeleta anexos dos tickets
/webmvc/v1/ticket/{ticketId}/attachments/{documentId}
Método tipo: DELETE
Possíveis Códigos de retorno
200 – Requisição efetuada com sucesso
401 - Invalid authentication token or user without access to the resource
404 - Ticket not found