2.O que mudou

2.1 Atualização da API de Solicitações

Para integração com o IoT Hub, a API de Solicitações sofreu algumas modificações na operação CRIA e CANCELA. Desse modo, alguns campos foram renomeados, adicionados, removidos ou o tipo do dado alterado. O presente tópico descreve como deve desenvolver a atualização para nova versão da API. Para mais detalhes das operações, acesse Criar Solicitação e Cancelar Solicitação

Operação "CRIA" (Versão Antiga)

Na versão anterior da requisição, o endpoint era:

Versão Antiga
Endpoint: /guia/ocorrencia/[CLIENTE]
Método: POST

Em que tinhamos como parâmetro da URL o identificador do cliente. Ainda mais, tinhamos o seguinte modelo do corpo do JSON de envio para operação CRIA.

{
  "id_protocolo":"", 
  "operacao":"cria", 
  "usuario":"",
  "senha":"", 
  "num_protocolo":"",
  "cod_servico":"", 
  "endereco_ocorrencia":"", 
  "ponto_referencia":"", 
  "num_ocorrencia":"", 
  "nome_solicitante ":"", 
  "telefone_solicitante":"", 
  "bairro_ocorrencia ":"", 
  "cep_ocorrencia":"", 
  "tipo_ocorrencia_original":"",
  "município_ocorrencia":"", 
  "sigla_uf_ocorrencia":"",
  "origem":"",
  "id_tipo_origem_ocorrencia': "",
  "id_parque_servico":"",
  "descricao":"", 
  "num_plaqueta":"",
  "lat_long":"",
  "justificativa":"",
  "checkbox_maioridade":"",
  "data_nascimento":""
}

Os campos presentes no corpo do JSON utilizados para antiga versão são descritos e exemplificados abaixo:

id_protocolo: String de identificação do protocolo.

operacao: String da descrição do código da operação que será executada pelo serviço. Entre as opções para este parâmetro temos: cria, altera, cancela, encerra, lista e consulta.

usuario: String referente ao usuário da requisição. Com uso de basic authentication este campo pode ser vazio.

senha: String referente a senha da requisição. Com uso de basic authentication este campo pode ser vazio.

num_protocolo: String que irá representar o protocolo da solicitação que será criada.

cod_servico: Valor numérico referente ao código do tipo de serviço que gerou a criação da solicitação. Um código de serviço é vinculado com o código de um tipo de ocorrência. Os valores dos códigos de serviço e tipo ocorrência podem variar entre as instâncias.

endereco_ocorrencia: String com a descrição do endereço do local que gerou a solicitação.

ponto_referencia: String de descrição do ponto de referência ligado ao endereço da ocorrência criada.

num_ocorrencia: Valor numérico referente ao número da ocorrência originada na solicitação.

nome_solicitante: String com o nome do solicitante que originou a ocorrência.

telefone_solicitante: String do telefone do solicitante que originou a ocorrência.

bairro_ocorrencia: String com o bairro do endereço que originou a solicitação.

cep_ocorrencia: String com o CEP do endereço que originou a solicitação.

tipo_ocorrencia_original: Valor numérico referente ao número da ocorrência original

municipio_ocorrencia: String com o Município do local da solicitação.

sigla_uf_ocorrencia: String com a sigla correspondente ao estado do local onde ocorreu a solicitação.

origem: String do código do tipo de origem da ocorrência externa.

id_tipo_origem_ocorrencia: Valor numérico referente ao código do tipo da ocorrência de origem da solicitação

id_parque_servico: Valor numérico do identificador do parque de serviço relacionado ao ponto que originou a solicitação.

descricao: String referente a descrição do motivo da criação da solicitação.

num_plaqueta: String referente ao valor do campo de identificação da plaqueta do ponto vinculado a solicitação.

lat_long: Latitude e longitude em formato decimal do ponto que originou a solicitação (ex: -3.15563, 3.60056).

justificativa: String de descrição do motivo do encerramento da solicitação.

checkbox_maioridade: Valor numérico (0 ou 1) correspondente a maioridade ou não do reclamante, 1 para maioridade e 0 para não.

data_nascimento: String de descrição da data de nascimento do reclamante.

E tinhamos como retorno o seguinte JSON (201 - Created):

{
  "id_demanda": 1,
  "operacao": "cria",
  "data_recebido": 1711217789710,
  "status": "ok"
}

Operação "CRIA" (Versão Nova)

Após a atualização da requisição, o endpoint para operação CRIA é:

Versão Nova
Endpoint: /vendors/m2m/clients/{idInstance}/tickets
Método: POST

A qual temos como parâmetro da URL o identificador da instância.

Para a atual versão, na questão do JSON de envio, além da tradução dos nomes dos campos para o inglês, os seguintes campos foram removidos:

operacao

usuario

senha

tipo_ocorrencia_original

lat_long

Além disso, os seguintes campos foram adicionados:

latitude

longitude

Após a tradução, os campos são:

Versão Antiga	Versão nova
origem	cod_external_ticket_origin
id_tipo_origem_ocorrencia	ticket_origin_type_id
id_protocolo	id_external_protocol *
num_protocolo	external_protocol
cod_servico	service_code
justificativa	justification
descricao	description
id_parque_servico	id_worksite
sigla_uf_ocorrencia	state_abbreviation
município_ocorrencia	municipality
bairro_ocorrencia	neighborhood
endereco_ocorrencia	address
num_ocorrencia	address_number
cep_ocorrencia	zip_code
ponto_referencia	reference_point
nome_solicitante	reporter
telefone_solicitante	reporter_phone
data_nascimento	reporter_birth_date
num_plaqueta	nameplate_num
checkbox_maioridade	age_majority_checkbox

Observação: Os campos anotados com "*" tiveram o tipo do dado modificado.

Desse modo, o novo corpo do JSON que será enviado para o processo de requisição segue o modelo abaixo:

{
  "cod_external_ticket_origin": "tg",
  "ticket_origin_type_id": 1,
  "id_external_protocol": 1,
  "external_protocol": "string",
  "service_code": "string",
  "justification": "string",
  "description": "string",
  "id_worksite": 1,
  "state_abbreviation": "AC",
  "municipality": "string",
  "neighborhood": "string",
  "address": "string",
  "address_number": 0,
  "zip_code": "65903-350",
  "latitude": "45.123",
  "longitude": "76.486",
  "reference_point": "string",
  "reporter": "string",
  "reporter_phone": "84968718020",
  "reporter_birth_date": "01/01/1900",
  "nameplate_num": "string",
  "age_majority_checkbox": 1

Os campos presentes no corpo do JSON utilizados para nova versão são descritos e exemplificados abaixo:

cod_external_ticket_origin: String do código do tipo de origem da ocorrência externa.

ticket_origin_type_id: Valor numérico referente ao código do tipo da ocorrência de origem da solicitação

id_external_protocol: Valor numérico da identificação do protocolo.

external_protocol: String que irá representar o protocolo da solicitação que será criada.

service_code: Valor numérico referente ao código do tipo de serviço que gerou a criação da solicitação. Um código de serviço é vinculado com o código de um tipo de ocorrência. Os valores dos códigos de serviço e tipo ocorrência podem variar entre as instâncias.

justification: String de descrição do motivo do encerramento da solicitação.

description: String referente a descrição do motivo da criação da solicitação.

id_worksite: Valor numérico do identificador do parque de serviço relacionado ao ponto que originou a solicitação.

state_abbreviation: String com a sigla correspondente ao estado do local onde ocorreu a solicitação.

municipality: String com o Município do local da solicitação.

neighborhood: String com o bairro do endereço que originou a solicitação.

address: String com a descrição do endereço do local que gerou a solicitação.

address_number: Valor numérico referente ao número da ocorrência originada na solicitação.

zip_code: String com o CEP do endereço que originou a solicitação.

latitude: String com a latitude do ponto de serviço.

longitude: String com a longitude do ponto de serviço.

reference_point: String de descrição do ponto de referência ligado ao endereço da ocorrência criada.

reporter: String com o nome do solicitante que originou a ocorrência.

reporter_phone: String do telefone do solicitante que originou a ocorrência.

reporter_birth_date: String de descrição da data de nascimento do reclamante.

nameplate_num: String referente ao valor do campo de identificação da plaqueta do ponto vinculado a solicitação.

age_majority_checkbox: Valor numérico (0 ou 1) correspondente a maioridade ou não do reclamante, 1 para maioridade e 0 para não.

Note que os campos do JSON de resposta não foram alterados. A seguir há um exemplo do corpo de resposta (201 - Created):

{
    "id_demanda": 1459812,
    "operacao": "cria",
    "data_recebido": 1734616582555,
    "status": "ok"
}

Operação "CANCELA" (Versão Antiga)

Na versão anterior da requisição, o endpoint era:

Versão Antiga
Endpoint: /guia/ocorrencia/[CLIENTE]
Método: POST

Em que tinhamos como parâmetro da URL o identificador do cliente. O corpo do JSON de envio para operação CANCELA seguia o seguinte modelo:

{
  "usuario":"", 
  "senha":"", 
  "operacao":"cancela", 
  "origem":"",
  "id_protocolo":"", 
  "justificativa":""
}

Para a antiga versão, relembremos que os campos presentes utilizados possuem os seguintes significados:

usuario: String referente ao usuário da requisição. Com uso de basic authentication este campo pode ser vazio.

senha: String referente a senha da requisição. Com uso de basic authentication este campo pode ser vazio.

operacao: String da descrição do código da operação que será executada pelo serviço. Entre as opções para este parâmetro temos: cria, altera, cancela, lista e consulta.

origem: String referente ao código do tipo de origem da ocorrência externa.

id_protocolo: String de identificação do protocolo.

justificativa: String de descrição do motivo do encerramento da solicitação.

A requisição possuia como retorno o seguinte modelo (201 - Created):

{
  "operacao": "cancela",
  "id_protocolo": 1,
  "data_recebido": 171122323080,
  "status": "ok"
}

Operação "CANCELA" (Versão Nova)

A nova versão do endpoint para operação CANCELA possui o seguinte formato:

Versão Nova
Endpoint: /vendors/m2m/clients/{idInstance}/tickets
Método: DELETE

Em que temos como parâmetro o identificador da instância.

Na questão do JSON de envio, a atual versão também teve os nomes dos campos traduzidos para o inglês, além disso, os seguintes campos foram removidos:

usuario

senha

operacao

A tradução dos antigos campos que ainda pertencem ao corpo JSON são:

Versão Antiga	Versão nova
origem	cod_external_ticket_origin
id_protocolo	id_external_protocol *
justificativa	justification

Observação: Os campos anotados com "*" tiverem o tipo do dado modificado.

Logo, a nova versão do JSON de envio possui o seguinte modelo:

{
  "cod_external_ticket_origin": "tg",
  "id_external_protocol": 1,
  "justification": "string"
}

A exemplificação dos campos presentes no corpo JSON da nova versão está a seguir:

cod_external_ticket_origin: String referente ao código do tipo de origem da ocorrência externa.

id_external_protocol: Valor numérico da identificação do protocolo.

justification: String de descrição do motivo do encerramento da solicitação.

Note que os campos do JSON de resposta não foram alterados, a seguir há um exemplo Corpo da Resposta (200 - OK):

{
    "operacao": "cancela",
    "id_protocolo": 1,
    "data_recebido": 1734616702536,
    "status": "ok"
}

2.2 Atualização no fluxo de atualização de pontos com NOX

Esta presente versão da integração sofreu uma alteração no fluxo de atualização de pontos com NOX. Anteriormente o fluxo funcionava através de uma rotina executada periodicamente. Por meio de um método de polling, detectava mudanças nos dados relevantes à integração com cada um dos pontos IP válidos, a fim de atualizar o cadastro na API da M2M. A detecção das alterações era feita por meio do rastreamento de seu histórico, usando um snapshot dos pontos.

O antigo fluxo de atualização está descrito pelo diagrama abaixo. As etapas que estão em azul claro se referem as operações descritas em
Operações de Saída

A atual versão remove a necessidade de periodicamente executar a rotina para verificar os pontos IP com NOX alterados. No momento, qualquer alteração ocorrida no sistema Exati é enviada para o IoT Hub, que então consulta o Ponto de IP na API da M2M, obtendo o estado atual do cadastro na M2M. Assim, são comparadas as alterações ocorridas no sistema Exati com os atuais valores retornados pela M2M e, de acordo com o tipo de alteração, é disparada uma das requisições possíveis para a API da M2M (criar Ponto IP, trocar Nox, remover ou substituir Nox).

A nova versão do fluxo de atualização está descrito pelo diagrama abaixo. As etapas que estão em azul claro referem as operações descritas em Operações de Saída.

Fluxo de atualização de pontos com NOX.jpg

2.3 Adição de endpoints

Na nova versão da integração, foram implementadas as operações Atualizar Atributos de Dispositivos e Atualizar Atributos de um Dispositivo. Essas funcionalidades foram desenvolvidas para simplificar o envio, pela M2M, de dados como localização GPS e consumo energético medidos pelos dispositivos, permitindo que os usuários visualizem essas informações diretamente no Sistema da Exati.

Para mais detalhes sobre essas operações, consulte a seção Operações de Entrada e localize as operações mencionadas.

2.4 Possibilidade de múltiplos dispositivos para um mesmo Ponto de IP

A integração atual, utilizada exclusivamente em Petrolina, é limitada a um dispositivo por ponto de IP. No entanto, com a integração nativa do IoT Hub ao sistema da Exati e suas novas funcionalidades, tornou-se possível instalar mais de um dispositivo em um único ponto de iluminação.

Atualmente, a API da M2M permite apenas a integração de cadastro por ponto de IP, associando um único Nox. Para viabilizar a integração de múltiplos dispositivos em um mesmo ponto de iluminação, é necessário que a M2M faça uma das seguintes ações:

Modificar a API existente para suportar essa funcionalidade; ou

Disponibilizar uma interface já existente que permita operar com múltiplos Nox em um único ponto, possibilitando assim a implementação da integração.

2.1 Atualização da API de Solicitações#

Operação "CRIA" (Versão Antiga)#

Operação "CRIA" (Versão Nova)#

Operação "CANCELA" (Versão Antiga)#

Operação "CANCELA" (Versão Nova)#

2.2 Atualização no fluxo de atualização de pontos com NOX#

2.3 Adição de endpoints#

2.4 Possibilidade de múltiplos dispositivos para um mesmo Ponto de IP#