API Zarc NM (SINM)

O SINM foi desenvolvido com o propósito de receber dados relacionados à glebas (ou talhões) produtivas e a partir dos dados recebidos, classificar a gleba de acordo com o seu nível de manejo, seguindo a metodologia de classificação publicada em 2022 pela Embrapa com o título "Níveis de manejo do solo para avaliação de riscos climáticos na cultura da soja." (DEBIASI, H.; MONTEIRO, J. E. B. de A.; FRANCHINI, J. C.; FARIAS, J. R. B.; CONTE, O.; CUNHA, G. R. da; MORAES, M. T. de; BALBINOT JUNIOR, A. A.; SILVA, F. A. M. da; EVANGELISTA, B. A.; MARAFON, A. C.).

Requisitos

Os principais requisitos que guiaram a construção da API são listados abaixo:

1. Aplicar todas as regras de cálculo da classificação de nível de manejo (níveis de 1 a 4) de forma flexível para que as regras possam ser alteradas de maneira simples, assim como novas regras possam ser incorporadas e/ou removidas.
2. As regras de cálculo precisam ser versionadas para que haja rastreabilidade entre classificações já realizadas e regras/parâmetros aplicados.
3. Os dados das glebas precisam ser geolocalizados, para que se possa criar mecanismos de verificação via monitoramento por imagens de satélite/drone.
4. Tanto os dados das glebas enviados para a API, quanto os dados de classif icação gerados pela aplicação das regras precisam ser armazenados em banco de dados para posterior consulta e auditoria.
5. Permitir que parceiros possam enviar dados automaticamente via sistemas/máquinas.
6. Os dados da gleba relacionados às características da gleba (propriedade, localização) ao histórico de cultivo (diversidade de culturas ao longo do tempo) e de operações de manejo realizadas serão enviados em um endpoint específico com permissão a um perfil de usuário (Operador de Contratos).
7. Os dados da gleba relacionados à análise de amostras de solo (variáveis químico, físico e orgânicas do solo) serão enviadas em um endpoint específico com permissão a um perfil de usuário (Operador de Análise de Solo).
8. Os dados da gleba relacionados ao sensoriamento remoto, tais como índices vegetativos, interpretação de culturas e datas de operações serão enviadas em um endpoint específico com permissão a um perfil de usuário (Operador de Sensoriamento Remoto).
9. O score final relacionado à classificação de nível de manejo de uma gleba será dado por um conjunto de regras definidas.
10. As consultas ao resultado de uma classificação de nível de manejo para uma gleba retornarão apenas o score final de classificação da gleba.

Principais atores interessados:

Arquitetura

Visão geral do SINM:

Visão Arquitetural do SINM:

Funcionamento

Para a utilização do SINM, primeiramente é necessário autenticar-se com usuário com credencias válidas e assim obter um token de acesso. Em posse do token de acesso e dentro de seu período de validade, as APIs podem ser acessadas. Abaixo, vamos ilustrar como se dá a autenticação e posteriormente o uso das APIs. Depois, na seção "Como usar", temos um passo a passo com templates e imagens de uso das APIs por meio da ferramenta Postman.

1. Autenticação

Envio das credenciais de acesso

Obtendo o token de acesso após validação das credencias

Enviando uma requisição ao SINM

Verificando a autenticidade e valdidade do token de acesso

Resposta da requisição enviada pela aplicação cliente

2. Envio de dados de identificação da gleba, histórico de cultivos e operaçõe de manejo

3. Envio de dados de amostras de solo

4. Envio de dados de sensoriamento remoto

5. Consulta à classificação final de nível de manejo

Como usar?

1. Autenticação de usuário

Para ter acesso ao SINM o usuário precisa estar autenticado. A autenticação é realizada via protocolo OpenId Connect (OIDC) usando o fluxo Password Credentials da especificação OAuth2. Para demonstrar como é realizado o processo de auntenticação e acesso aos endpoints do SINM , iremos utilizar a plataforma Postman.

Foi criado um arquivo JSON nomeado Endpoints_API_Zarc-NM_-_SEM_CREDENCIAIS.postman_collection.json, nesse arquivo há uma collection com os enpoints presentes no SINM. Para enviar requisições ao SINM, primeiramente baixe o arquivo Endpoints_API_Zarc-NM_-_SEM_CREDENCIAIS.postman_collection.json que encontra-se disponível para download emuploads/520f86487b713f763428a0180e2d33db/Endpoints_API_Zarc-NM_-_SEM_CREDENCIAIS.postman_collection.json, em seguida, faça a importação do arquivo no Postman. Para importar o arquivo no Postman, acesse a aba File (Cf. retângulo vermelho, Figura 1), em seguida, clique na opção Import... (Cf. retângulo amarelo, Figura 1).

Seguidamente escolha a alternativa files e selecione o arquivo (Cf. retângulo vermelho, Figura 2).

Ao finalizar o processo de importação do arquivo, o Postman irá exebir na aba Collections a collection Endpoints API Zarcn-NM, informando que a importação ocorreu corretamente (Cf. retângulo vermelho, Figura 3). Após isso, clique na collection Endpoints API Zarcn-NM e acesse a aba Authorization (Cf. retângulo laranja, Figura 3), em seguida, na seção Configure New Token preencha com as suas credenciais de acesso os seguintes campos (Cf. retângulo amarelo, Figura 3):

• Client ID
• Client Secret
• Username
• Password

Os outros campos não devem serem alterados, pois eles já estão preenchidos com as informações necessárioas para o processo de autenticação. Após preencher os campos solicitados, clique no botão Get New Accesss Token, para autenticar e receber um token de acesso (Cf. retângulo amarelo, Figura 4).

Logo após, clique no botão Proceed (Cf. retângulo amarelo, Figura 5)

Por fim, clique no botão Use Token (Cf. retângulo amarelo, Figura 6). Depois de executar esses passos, o token recebido é habilitado possibiltando o usuário realizar requisições com acesso autenticado para ao SINM. Esses passos devem serem realizados apenas na collection Endpoints API Zarcn-NM, pois isso habilita o token em todos os endpoints presentes nessa collection. Adicionalmente, esse procedimento deve ser realizado todas as vezes que o token expirar.

2. Envio de dados da gleba/talhão

Dados da gleba/talhão (propriedade, glebas, culturas e manejos). Essas informações são necessárias para dar início ao processo de classificção da gleba/talhão, para a qual se deseja obter o nível de manejo. Após realizar o processo de autenticação descrito na Subseção Autenticação de usuário, use a plataforma Postman para enviar os dados da gleba/talhão. Para isso, clique em Dados da Gleba/Talhão , seguidamente em POST Glebas - Adicionar (Cf. retângulo rosa, Figura 7) e faça uma requisição HTTP utilizando o método POST para o SINM. (Cf. retângulo laranja, Figura 7).

Após o envio da solicitação, se todas as informações enviadas no cabeçalho e no corpo da requisição foram informadas corretamente (Cf. retângulos laranja e amarelo, Figura 7), o SINM retorna o código 201 Created - HTTP Status informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição e uma chave nomeada de chave da classificação de nível de manejo - chaveClassificacaoNM que deverá ser guardada (Cf. retângulo azul, Figura 7). Esta chave será a identificação usada para envio posterior dos dados de análise de solo, de geoprocessamento e de consulta ao nível de manejo calculado.

3. Envio de dados de análise de solo

Dados de análise de solo (do conjunto de amostras de solo). Essas informações são necessárias para dar continuidade no processo de classificação após cadastro da(s) gleba(s). Para enviar estes dados, o usuário deve estar autenticado (Cf. Subseção Autenticação de usuário) e precisa ter a chave chaveClassificacaoNM gerada com o cadastro da gleba na etapa anterior (Cf. retângulo azul, Figura 7).

Utilizando o Postman, o usuário enviará uma solicitação para o SINM passando a chave chaveClassificacaoNM. Para isso, clique em Dados de Laboratório , seguidamente em POST Amostras - Adicionar (Cf. retângulo rosa, Figura 8) e faça uma requisição HTTP utilizando o método POST para o SINM. (Cf. retângulo laranja, Figura 8).

Após o envio da solicitação, se todas as informações enviadas no cabeçalho e no corpo da requisição foram informadas corretamente (Cf. retângulos laranja e amarelo, Figura 8), o SINM retorna o código 201 Created - HTTP Status informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição (Cf. retângulo amarelo, Figura 8).

4. Envio de dados de sensoriamento remoto

Dados de sensoriamento remoto relacionados à gleba/talhão para a qual foi solicitada uma classificação de nível de manejo. Os dados de geoprocessamento serão necessários para validar as informações fornecidas pelo agente do contrato no processo de classificação das glebas/talhões. Para realizar o envio desses dados, o usuário deve estar autenticado (Cf. Subseção Autenticação de usuário) e precisa ter a chave chaveClassificacaoNM gerada com o cadastro da gleba na etapa anterior (Cf. retângulo azul, Figura 7).

Utilizando o Postman, o usuário enviará uma solicitação para o SINM passando a chave chaveClassificacaoNM. Para isso, clique em Dados de Sensoriamento Remoto , seguidamente em POST Monitoramentos - Adicionar (Cf. retângulo rosa, Figura 9) e faça uma requisição HTTP utilizando o método POST para o SINM. (Cf. retângulo laranja, Figura 9).

Após o envio da solicitação, se todas as informações enviadas no cabeçalho e no corpo da requisição foram informadas corretamente (Cf. retângulos laranja e amarelo, Figura 9), o SINM retorna o código 201 Created - HTTP Status informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição (Cf. retângulo amarelo, Figura 9). Além disso, logo após o envio desses dados, é realizado o cálculo da classificação de nível de manejo para a gleba/talhão referente a chave informada. E o usuário pode consultar o resultado da classifição no SINM(Cf. Subseção Classificação nível manejo).

2. Classificação nível manejo

Uma vez que o registro dos dados obrigatórios tenha sido finalizado e o cálculo da classificação tenha ocorrido, é possível consultar a classificação do nível de manejo de uma determinada gleba/talhão no SINM. Para a consulta, o usuário deve estar autenticado (Cf. Subseção Autenticação de usuário) e precisa ter a chave chaveClassificacaoNM gerada com o cadastro de uma determinada gleba/talhão (Cf. retângulo azul, Figura 7).

Utilizando o Postman, o usuário enviará uma solicitação para o SINM passando a chave chaveClassificacaoNM. Para isso, clique em Classificação Nível Manejo , seguidamente em GET Classificações - Buscar (Cf. retângulo vermelho, Figura 10) e faça uma requisição HTTP utilizando o método GET para o SINM. (Cf. retângulo laranja, Figura 10).

Após o envio da solicitação, se todas as informações enviadas no cabeçalho da requisição foram informadas corretamente (Cf. retângulo laranja, Figura 10) , o SINM retorna o código 200 OK - HTTP Status informando que o recurso foi encontrado. No corpo da resposta é retornada a chave da classificação (chaveClassificacaoNM), o score final (nível de manejo), a data e hora em que foi realizado o cálculo da classificação e uma lista de inconsistências (tipo, descrição e a data e hora do registro das inconsistências), se houver dados inconsistentes. (Cf. retângulo amarelo, Figura 10). Se o usuário tentar consultar o resultado de uma classificação que ainda não foi finalizada, o SINM retorna o código 404 Not Found - HTTP Status indicando que o recurso foi encontrado e uma mensagem informando qual ou quais dado(s) estão faltando para finalizar o cálculo de classificação de nível de manejo.

6. Lista de culturas

Para enviar os dados de uma determinada gleba/talhao (Cf. Subseção Envio de dados da gleba/talhão), é preciso informar as culturas cultivadas na gleba/talhão durante o período de três anos. Essa informação é adicionada no campo código, do objeto cultura presente na lista de producoes que compõe os dados da gleba/talhão (Cf. retângulo amarelo, Figura 7).

Para auxiliar o usuário na hora de adicionar essa informação, o SINM disponibiliza uma lista com os nomes e códigos das culturas que ele aceita. Utilizando o Postman, o usuário enviará uma requisição para o SINM solicitando a lista de culturas. Para isso, clique em Culturas , seguidamente em GET Culturas - Listar (Cf. retângulo rosa, Figura 11) e faça uma requisição HTTP utilizando o método GET para o SINM. (Cf. retângulo laranja, Figura 11).

Após o envio da solicitação, se todas as informações enviadas no cabeçalho da requisição foram informadas corretamente (Cf. retângulo laranja, Figura 11), o SINM retorna o código 200 OK - HTTP Status informando que o recurso foi encontrado. No corpo da resposta é retornada a lista contendo todos os nomes e códigos das culturas (Cf. retângulo amarelo, Figura 11).

Dados contidos no template da collection disponibilazada

Para cada endpoint do SINM, disponibilizamos uma collection do Postman, foi criado um template com dados simulados, com a finalidade apenas de testar o envio de dados e também exemplificar os dados e os tipos de dados que o SINM recebe.

Links úteis

Documentação Swagger da API - Ambiente Homologação e Testes

Documentação Swagger da API - Ambiente Produção

Collection do Postamn

E-mail da equipe Embrapa