O que este endpoint faz
Este endpoint permite que através de uma requisição seja possível consultar, incluir e editar solicitações de serviço.
Você pode usar caso desejar integrar com uma aplicação terceira, principalmente para abrir as solicitações em casos específicos, como em soluções MES (Manufacturing Execution System).
Pré-requisitos
Conta ativa no Keepfy;
Usuário com perfil administrador para realizar a configuração;
Configurar sistema para receber mensagem.
Configurações necessárias
Em 'Minha Conta', acesse a opção 'Integração';
Clique em sobre a seção de integração 'Equipamento';
Verifique se não há uma integração 'Custom' habilitada, ela pode conter o endpoint de solicitação. Caso não tenha, clique em 'Nova Integração'.
No passo 1, nomeie sua integração. Este campo é livre, mas recomendamos que você escolha um nome que caracterize o processo desejado.
No passo 2, crie um grupo de filiais. Ou seja, você pode organizar o recebimento de mensagens por grupos de filiais e a configuração escolhida estará atrelada aquele grupo, com diferenças entre códigos de empresa e filial que serão vistos no passo 4.
No passo 3, atente-se aos metadados escolhidos. Clique em 'Novo Metadado', dê um nome para caracterizar e selecione o endpoint desejado, no contexto desde exemplo, escolha Solicitação de Serviço.
Ainda no passo 3 veja que ao escolher o endpoint de Solicitação de Serviço campos padrão são carregados. Campos internos são aqueles em que formatos vamos identificar e receber, campos externos podem ser alterados conforme a requisição do cliente, porém é importante manter a correlação correta conforme a mensagem de requisição enviada e o processo desejado. Mais detalhes sobre os campos serão apresentados em 'Dicionário de campos';
Para fins didáticos, neste momento, faremos a alteração de alguns campos com novas chaves:
Desta forma, a requisição deve estar de acordo com as chaves - veremos abaixo em 'exemplo prático';
Confirme e prossiga para o último passo;
No último passo, onde são listadas as filiais, informe o código da empresa e da filial para facilitar a identificação conforme a necessidade de passagem de parâmetros. Não esqueça de salvar a edição.
Ao avançar a configuração estará terminada e pronta para ser utilizada.
Exemplos práticos
Abaixo apresentamos alguns exemplos práticos para facilitar o entendimento referente ao uso.
1 - Consulta de Solicitações de Serviço (GET)
A requisição deve ser enviada para: https://api.keepfy.com/v1/servicerequest
O tipo de autenticação é 'Basic authorization', isso é, usuário e senha Keepfy com acesso a leitura de solicitações de serviço. Portanto, um solicitante como tem acesso restrito a suas SSs pode não ver toda a consulta.
Informe os parâmetros obrigatórios: companyId e branchId, conforme configurados;
A execução deve retornar mensagem semelhante a abaixo. Exemplo de requisição feita com o software Insomnia:
É possível passar filtros através dos parâmetros, como por exemplo, situation (situações conforme listados na seção abaixo opções de parâmetros). No exemplo abaixo fazemos a busca por situação de SSs distribuídas.
2 - Inclusão de Solicitações de Serviço (POST)
O link de requisição e autenticação se mantém, porém agora será necessário informar no corpo da mensagem (body)
Informe os parâmetros obrigatórios: companyId e branchId, conforme configurados;
No exemplo abaixo, estamos passando a mensagem conforme as chaves definidas na configuração, item 8 da seção 'Configurações necessárias';
O retorno de sucesso deve conter os dados da solicitação que foi criada:
Os dados de retorno também vão corresponder aos campos externos anteriormente configurados.
3 - Edição de Solicitações de Serviço (POST)
Nossa edição também segue o método post devido a regras de integração com sistemas de parceiros.
Para realizar uma edição é necessário informar o código da solicitação desejada no corpo da requisição;
No exemplo abaixo, estamos passando a mensagem conforme as chaves definidas na configuração, item 8 da seção 'Configurações necessárias'. Assim como o código para que a alteração aconteça;
Dicionário de campos
Chaves internas
Correspondência Sistema | Valor |
Identificador interno da SS | id |
Fim da Parada | resumedAt |
Identificador interno do Equipamento | equipmentId |
Início da Parada | stoppedAt |
Ocorrência | description |
Prioridade | priority |
Identificação (Equipamento) | equipmentTag |
Código da SS | code |
Situação | situation |
Opções de parâmetros
Situation (Situação)
Correspondência Sistema | Valor |
Em análise | awaiting-analysis |
Distribuída | distributed |
Aguardando OS | distributed-with-so |
Satisfação | satisfaction |
Finalizada | finished |
Priority (Prioridade)
Correspondência Sistema | Valor |
Emergencial | emergency |
Alta | high |
Média | medium |
Baixa | low |
É importante lembrar que solicitações não distribuídas não possuem prioridade.
Referência técnica
Metadados: são dados que descrevem outros dados, fornecendo contexto e informações como origem, formato, significado e uso para facilitar sua organização, busca e compreensão