Neste artigo, iremos abordar o tópico de Enumerações utilizadas em nossas APIs do Movidesk. Ao longo do artigo, trataremos sobre:
O que são ENUMS
ENUM é um nome dado para campos com “enumeração” na programação. Basicamente, são dados que associam um número a determinado valor de uma lista pré definida.
Um exemplo prático seria o campo de “origin”, da nossa API de Tickets, onde cada número representa uma origem:
Dessa forma, podemos nos organizar com maior facilidade quanto à escalabilidade e gestão de nosso sistema, dada a padronização que é fornecida pelo uso de Enumerações, pois garantimos que diferentes sistemas do Movi sempre irão ter uma mesma correlação de número <-> informação.
ENUMS utilizados nas APIs do Movidesk
Abaixo, segue tabela com os ENUMs existentes em nossas API’s, e seus respectivos tipos para utilização em filtros de consultas. Na esquerda, estará o tipo de dado respectivo ao ENUM que utilizamos, e na direita em quais campos das API’s do Movi o ENUM em questão é usado.
A API sempre estará em negrito na tabela abaixo. Se estiver escrito “tickets.type”, essa informação se refere ao atributo “type” da API de Tickets.
Caso esteja descrito como “timeAgreement.clients[n].profileType”, seria o campo “profileType”, dentro dos elementos da coleção de “clients”, da API de Contrato de Horas (timeAgreement), e assim em diante.
| Nome do ENUM | API.Campo |
|---|---|
| Movidesk.Core.Data.Enums.TicketType | tickets.type tickets.actions[n].type |
| Movidesk.Core.Data.Enums.TicketOrigin | tickets.origin tickets.actions[n].origin |
| Movidesk.Core.Data.Enums.PersonType | tickets.clients[n].personType tickets.slaSolutionChangedBy.personType tickets.createdBy.personType tickets.actions[n].timeAppointments[n].createdBy.personType tickets.actions[n].createdBy.personType tickets.clients[n].organization.personType timeAgreement.clients[n].personType timeAgreement.clients[n].organization.personType timeAgreementConsumption.clients[n].personType timeAgreementConsumption.clients[n].organization.personType timeAgreementConsumption.timeAppointments[n].createdBy.personType timeAgreementConsumption.expenses[n].createdBy.personType |
| Movidesk.Core.Data.Enums.ProfileType | tickets.clients[n].profileType tickets.slaSolutionChangedBy.profileType tickets.createdBy.profileType tickets.actions[n].timeAppointments[n].createdBy.profileType tickets.actions[n].createdBy.profileType tickets.clients[n].organization.profileType services.isVisible services.allowSelection timeAgreement.clients[n].profileType timeAgreement.clients[n].organization.profileType timeAgreementConsumption.clients[n].profileType timeAgreementConsumption.clients[n].organization.profileType timeAgreementConsumption.timeAppointments[n].createdBy.profileType timeAgreementConsumption.expenses[n].createdBy.profileType |
| Movidesk.Core.Data.Enums.SatisfactionSurveyModel | tickets.satisfactionSurveyResponses[n].satisfactionSurveyModel |
| Movidesk.Core.Data.Enums.SatisfactionSurveyNetPromoterScoreResponse | tickets.satisfactionSurveyResponses[n].satisfactionSurveyNetPromoterScoreResponse |
| Movidesk.Core.Data.Enums.SatisfactionSurveyPositiveNegativeResponse | tickets.satisfactionSurveyResponses[n].satisfactionSurveyPositiveNegativeResponse |
| Movidesk.Core.Data.Enums.SatisfactionSurveySmileyFacesResponse | tickets.satisfactionSurveyResponses[n].satisfactionSurveySmileyFacesResponse |
| Movidesk.Core.Data.Enums.AccessLevelTicketType | services.serviceForTicketType |
| Movidesk.Core.Data.Enums.DiscountType | timeAgreementConsumption.discountType |
Como utilizar os ENUMs em suas buscas da API
Agora que já sabemos o que são ENUMs, e onde eles são usados em nossas API’s, podemos partir para a utilização deles em filtros de consultas aos nossos sistemas.
Pegando um exemplo prático, se quisermos somente tickets com ações que foram criadas por um usuário do tipo “cliente”, podemos utilizar o campo de tickets.actions[n].createdBy.profileType, da API de Tickets.
Esse campo, como pode ser visto na tabela acima, é do tipo ENUM “Movidesk.Core.Data.Enums.ProfileType”. Nesse caso, se tentássemos com uma requisição como a consulta abaixo, teríamos um erro 400 (tratado neste artigo aqui):
https://api.movidesk.com/public/v1/tickets?token={{Token}}&$select=id&$filter=actions/any(action : action/createdBy/profileType eq 1)
Nesse caso, como abordado no artigo mencionado, a resolução é bem prática. Basta cobrirmos o “1” da nossa consulta com aspas simples, e antes dele, adicionarmos o nome do ENUM. Nesse caso, a consulta editada ficaria assim:
https://api.movidesk.com/public/v1/tickets?token={{Token}}&$select=id&$filter=actions/any(action : action/createdBy/profileType eq Movidesk.Core.Data.Enums.ProfileType'1')
Em negrito, e tom avermelhado, está a adição do tipo de ENUM do campo (conforme pode ser visto na tabela supracitada) e as aspas simples, ao redor do valor de enumeração que estamos buscando.
A mesma lógica deve ser utilizada para consultas de outros campos de ENUM de nossas API’s, sempre “envolvendo” a numeração desejada do ENUM por aspas simples, e antes da primeira aspa, adicionando o nome do ENUM que estamos buscando (que pode sempre ser validado na tabela deste artigo).