Simova NFS API

Elaborado por Dalton Meira em 06/03/2020

Sumário
Apresentação

Etapas
Autenticação
Parâmetros
Requisições e Respostas
Sincronismo
Integração
Exemplo
Request
Response
Retorno de Imagem
Request
Response

Referência

-1-
Apresentação

O NFS permite a comunicação por API, sendo o ​sincronismo (entrada de dados NFS) e ​integração
(saída de dados do NFS) através de uma API usando ​JWT​ (Json Web Token).
Toda a lógica de negócio, no que se trata quais dados serão sincronizados (quais entidades vão vim
para o NFS) e integrados (quais entidades serão obtidas pelo sistema terceiro) é tratado com um analista da
Simova e depois é configurado a API.
A comunicação hoje sempre parte do lado do cliente, então quando é necessário enviar um dado para
o NFS o Sistema de Terceiro faz um request enviado as informações e a mesma coisa na hora que deseja
obter um dado, é feita uma chamada passando qual registro é buscado.

Etapas

Autenticação

A primeira etapa é a autenticação por um método ​POST para isso o usuário deve existir cadastrado
dentro do NFS, com isso é enviado usuário e senha, o retorno é um token que vai expirar em 15 minutos, se
antes desse tempo autenticar novamente é gerado um novo token, o antigo para de funcionar e também tem
o tempo 15 minutos.

-2-
 A url será o domínio do cliente mais /nfs/api/v1/auth​, supondo que o domínio seja
[Link], no final a chamada será:

[Link]

Parâmetros

Os parâmetros para autenticação são enviados como um ​Json Object [​ 1] de acordo com a ​tabela 1​.

Chave Obrigatório Descrição

nome Não Nome do usuário

user Sim E-mail válido do usuário

cadastrado no NFS

password Sim Password do usuário

empresa Sim
Tabela 1

Requisições e Respostas

Request

curl --request POST \

--url [Link] \
--header 'content-type: application/json' \
--data '{
"nome": "simova",
"user": "simova@[Link]",
"password": "simova123",
"empresa" : "Simova"
}'

Response

{
"type": "success",
"msg": "Token gerado com sucesso.",
"token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZHMuaC5zaW1vdmEuY2xvdWQiLCJuYW1lIjo

-3-
 ic2ltb3ZhLmFkbWluIiwiZW1haWwiOiJzaW1vdmEuYWRtaW5Ac2ltb3ZhLmNvbS5iciIsImZpbGlhbCI6IlB
BTE0iLCJsb2NhbCI6bnVsbCwiZXhwIjoiMjAyMC0wMy0wNiAwOToyNzowNyJ9.YLSMHvBRFv7JxREv
WyybmWmIrUf1vPBmksRTfs9xz+Q=",
"user": "[Link]@[Link]"
}

A chave ​token​ será usada no restante dos sincronismo e integração de dados.

Sincronismo

No sincronismo todas as chamadas são feitas por meio do método ​POST e no corpo é enviado um
Json Array ​[2]​.

O token sempre é enviado no header.

Request

curl --request POST \

--url [Link] \
--header 'authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZHMuaC5zaW1vdmEuY2xvdWQiLCJuYW1lIjoi
c2ltb3ZhLmFkbWluIiwiZW1haWwiOiJzaW1vdmEuYWRtaW5Ac2ltb3ZhLmNvbS5iciIsImZpbGlhbCI6IlB
BTE0iLCJsb2NhbCI6bnVsbCwiZXhwIjoiMjAyMC0wMy0wNiAwOToyNzowNyJ9.YLSMHvBRFv7JxREv
WyybmWmIrUf1vPBmksRTfs9xz+Q= \
--data '[
{
"CodigoEmpresa": "Teste",
"CodigoCliente": "00001548789",

-4-
 "Nome": "Cliente Teste",
"Tipo": "Física",
"CpfCnpj": "123456654654",
"NomeEndereco": "",
"Numero": "sn
"Complemento": "",
"Bairro": "",
"Cidade": "",
"UF": "SP"
}
]'

Response

[
{
"type": "success",
"msg": "Cadastro de Cliente inserido com sucesso",
"field": "",
"id": "6"
}
]

O retorno também é um ​json array​, porque pode ser sincronizado mais de um dado de uma vez, logo é
enviado também a resposta para cada na seguinte estrutura.

Chave Valor Descrição

type success/error/validation Para cada tipo de mensagem é

enviado um HTTP Status Code
diferente, mais detalhes na ​tabela
2.2

msg Customizada A mensagem é retornada de

acordo com seu type veja na
tabela 2.2

field Chave No caso são enviadas as chaves

que estão com erro ou inválidas

id Identificador único no NFS Este é o identificador único criado

no NFS, é muito importante para
dados que devem ser integrados.

-5-
Tabela 2.1​ - Retorno Mensagem

Type Mensagem HTTP Status Code

success Cadastro de Cliente inserido com 200

sucesso

Cadastro de Cliente atualizado

com sucesso

error Erro ao atualizar os dados de 400

Cliente

Erro ao inserir dados de Cliente

validation Campo Obrigatório 401

Cadastro de Estado com valor

igual a SP não encontrado!
Tabela 2.2 ​- Tipos de mensagens

Integração

Na integração é feito um GET a partir o Id que é enviado o sincronismo o mesmo deve ser retornado
quando quer se obter as informações de volta para o sistema de terceiro.

-6-
A url é ​/nfs/api/v1/integration/{entidade}

entidade​: é configurado a partir da necessidade do cliente

Exemplo

Supondo que foi feito um sincronismo de Ordem de Serviço, que é a entidade ​os​, e o ID gerado no
SmartOS é 10.

Request

curl --request GET \

--url [Link] \
--header 'authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJuZnMubG9jYWwiLCJuYW1lIjoic2ltb3ZhLmFkb
WluIiwiZW1haWwiOiJzaW1vdmEuYWRtaW5Ac2ltb3ZhLmNvbS5iciIsImZpbGlhbCI6IlBBTE0iLCJsb2N
hbCI6bnVsbCwiZXhwIjoiMjAyMC0wMS0yNyAxNjowNDozNSJ9.R+i2r7D9MTVHPND62I636hW5rOSn
N+\/L\/s6GoGzKV3Y=' \
--header 'content-type: application/json' \
--data '{
"id": "10"
}'

Response

[
{
"CodigoEmpresa": "Simova",
"FilialOS": "1",
"StatusOS": "Encerrada",
"IDStatusOS": "3",
"Equipamento": [
{
"Chassi": "312321312",
"Horimetro": "100",
"IdImagemChassi": "",
"IdImagemHorimetro": "1",
"DataLeitura": "2019-11-28 15:21:01"
}

-7-
 ],
"Dtac": [
{
"PecaCausadora": "1231312"
}
],
"AptHorasTrabalhadas": [
{
"SeqServico": "001-0002-0000",
"CodigoParada": "",
"DescParada": "",
"TipoApontamento": 1,
"CodigoEmpresaTec": "PALM",
"FlagServicoManual": "0",
"DataInicialApontamento": "2019-12-26 16:09:14",
"DataFinalApontamento": "2019-12-26 17:09:21",
"TempoApontado": "120",
"CodigoTecnico": "5"
},
{
"SeqServico": "",
"CodigoParada": "1",
"DescParada": "À DISPOSIÇÃO",
"TipoApontamento": 2,
"CodigoEmpresaTec": "Simova",
"FlagServicoManual": "1",
"DataInicialApontamento": "2019-12-26 16:09:14",
"DataFinalApontamento": "2019-12-26 17:09:21",
"TempoApontado": "120",
"CodigoTecnico": "5"
}
],
"PecasAplicacas": [
{
"CodigoPeca": "DIV538",
"QuantidadeAplicada": "0"
},
{
"CodigoPeca": "84565924",
"QuantidadeAplicada": "0"
}
]
}

-8-
 ]

Nisso é enviada todas informações da OS que estão configuradas para retorno, que geralmente é o
Apontamento de Horas Trabalhadas, Peças usadas na OS e etc. Um destaque especial é para quando
retorno é uma imagem que é enviado um id de sua entidade para não deixar o JSON de retorno grande.

Retorno de Imagem

Quando é configurado para retornar uma imagem em seu retorno é enviado o ID de onde ela existe e
sua chamada deve ser feita em uma requisição separada, por exemplo, no último exemplo de uma integração
de OS (lembrando que integração é quando a informação é gerada no SmartOS e obtida pelo Sistema
Terceiro) na chave ​Equipamento​ é enviado

"IdImagemChassi": "",
"IdImagemHorimetro": "1",

Isso quer dizer que tem uma imagem de horímetro com id igual a 1 e para obter essa imagem é feito
um novo request passando no body um json com o IdImagemHorimetro.

Request

curl --request GET \

--url [Link] \
--header 'authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJuZnMubG9jYWwiLCJuYW1lIjoic2ltb3ZhLmFkbWluIiwiZ
W1haWwiOiJzaW1vdmEuYWRtaW5Ac2ltb3ZhLmNvbS5iciIsImZpbGlhbCI6IlBBTE0iLCJsb2NhbCI6bnVsbCwi
ZXhwIjoiMjAyMC0wMS0yNyAxNjowNDozNSJ9.R+i2r7D9MTVHPND62I636hW5rOSnN+\/L\/s6GoGzKV3Y=' \
--header 'content-type: application/json' \
--data '
{
"IdImagemHorimetro" : "1"
}
'

Observação​: A entidade ​apontamento_equipamento é combinada e configurada pelo time do NFS, mas no

casos é onde existe essa imagem.

Response

-9-
[
{
"ImagemChassi": "",
"ImagemHorimetro": "imagine_aqui_base64_imagem"
}
]

No caso não deve existir uma ​ImagemChassi​, porém, se existir iria ser passado seu valor e no
retorno iria vir junto seu base64.

Referência
[1]​ Json Object - Na autenticação é usada a seguintes estrutura para enviar as informações:

{
“chave”: “valor”
}

[2]​ Json Array - No sincronismo de dados é usado a seguinte estrutura para enviar as informações:

[
{
“chave1”:”valor1”
},
{
“chave2”: “valor2”
}
]

- 10 -