Neste post, iremos demonstrar como realizar o fluxo de autorização da Climate FieldView para possibilitar a integração com a Leaf, ou seja, obter autorização para acessar os dados presentes na Climate FieldView de seus usuários através da API da Leaf. Vamos lá!
(Click here for the translation in English.)
Sumário
- Passo 0: Criar uma conta de desenvolvedor com a Climate FieldView, obter as credenciais da sua aplicação e verificar seus escopos
- Passo 1: Gerar os tokens de autorização Climate FieldView de seus usuários com a Leaf.
- Passo 2: Adicionar as credenciais da Climate FieldView a Leaf.
Fique sabendo que este tutorial apresenta um passo a passo da integração entre a Climate Field View e a Leaf. A maioria desses passos apresentados aqui serão realizados apenas uma vez, o que significa que as requisições futuras serão muito mais fáceis e rápidas.
Passo 0: Criar uma conta de Desenvolvedor com a Climate FieldView e adquirir as credenciais de sua aplicação.
(Caso possua uma conta de desenvolvedor com Climate FieldView, pode pular esse passo)
Para iniciar o processo de configurar sua conta de desenvolvedor Climate FieldView, você pode se registrar neste link.
Depois de aprovado pela Climate FieldView, você receberá um clientId, clientSecret e API Key.
Nota: Antes de prosseguir, recomendamos que envie um e-mail para developer@climate.com e verifique se você possui os escopos corretos... "asHarvested:read", "asPlanted:read", "asApplied:read", "fields:read", "resourceOwners:read", "farmOrganizations:read"
Passo 1: Obter os tokens Climate FieldView de seus usuários com a Leaf.
Para obter o token de seus usuários, a fim de acessar os dados provindos da Climate FieldView, sua aplicação deve seguir o fluxo OAuth da Climate FieldView. Você precisará redirecionar o usuário para uma URL personalizada, em que apresentará ao usuário a opção de autorizar o acesso de sua aplicação aos dados dele.
Para obter a URL deste passo da autenticação, envie um POST para:
https://cfv-oauth2-helper.withleaf.io/url
Com o seguinte JSON:
{
"client_id": "Your client ID",
"redirect_uri": "Your company URL"
}
Se você preferir, também pode incluir o parâmetro pass_through, para informar o state desejado após a autenticação.
A Leaf irá criar uma URL contendo o número mínimo de escopos (permissões) necessários para trazer Talhões, Fazendas e Operações. A Leaf também suporta o upload de talhões, prescrições, dados de solo e GeoTiff. Caso prefira o acesso a estes recursos extras, adicione o atributo "scope" ao corpo da requisição, incluindo os escopos básicos e os escopos extras, como fields:write, rx:write, soil:write e imagery:write. O corpo de requisição para gerar a URL com escopos extras deve ser como o exemplo abaixo:
{
"client_id": "Your client ID",
"scope": [
"asHarvested:read",
"asPlanted:read",
"asApplied:read",
"fields:read",
"resourceOwners:read",
"farmOrganizations:read",
"fields:write",
"rx:write",
"soil:write",
"imagery:write"
],
"redirect_uri": "Your app's redirect URL"
}
Um detalhe importante é que o uso dos escopos para recursos extras (fields:write, rx:write, soil:write e imagery:write) requerem permissões adicionais junto à Climate FieldView. Garanta que você tenha permissão para o uso destes escopos antes de gerar a URL, em caso negativo contate a Climate FieldView.
A Leaf irá retornar uma URL que você deverá direcionar ao seu usuário, para que ele possa autorizar o acesso aos seus dados e posteriormente ser redirecionado para sua aplicação. Note que após a autenticação a Climate FieldView irá redirecionar o seu usuário para a "redirect_uri" informada no payload e junto com essa URL também enviará um código, o qual você precisará fazer uma requisição para adquirir os tokens do seu usuário.
Adquirir os tokens do usuário
Uma vez que o usuário loga no link da web criado por você para a Climate FieldView, ele irá autorizar que sua aplicação acesse os dados dele e será redirecionado para a "redirect_uri" definida por você, com o código. Então, sua aplicação usará este código presente na URL de resposta para que os tokens sejam adquiridos.
Enviar um POST para
https://api.climate.com/
api/oauth/token
Com o seguinte header:
Authorization: Basic base64(clientId:
clientSecret)
Este passo requer que você codifique o “clientId:clientSecret” (o seu clientId e clientSecret do primeiro passo, separados por “:”) para base64. A maioria das linguagens de programação irá possibilitar uma maneira de codificar um texto para base64, mas caso queira fazer manualmente basta acessar este site:
Também inclua o seguinte corpo na requisição (x-www-form-urlencoded):
"code": "The code received on the last step",
"redirect_uri": "Your app's redirect URL (same as last step)",
"grant_type": "authorization_code"
Um JSON contendo os tokens será retornado, e você poderá adicioná-los à Leaf como sendo as credenciais da Climate FieldView.
Nota: A Leaf irá gerenciar todo e qualquer token, garantindo que os mesmos sempre estejam atualizados e válidos.
Passo 2: Adicione suas credenciais da Climate FieldView à Leaf
A API da Leaf utiliza uma abstração chamada Leaf User para armazenar as credenciais e organizar os dados para cada obtentor de dados individualmente. Na maioria dos casos, o Leaf User será o fazendeiro ou o consultor que tem acesso a fonte de dados dentro do FMIS do maquinário (ex.: plataformas John Deere Operations Center ou Climate FieldView).
A API da Leaf deve, então, ser iniciada com as credenciais da Climate FieldView para que seja possível acessar e padronizar os dados provindos da Climate FieldView. Para enviar suas credenciais para a Leaf, você irá precisar se autenticar com a Leaf para obter o seu Leaf Token, e possuir um Leaf User criado para associar à esta credencial. Se você não sabe como fazê-lo, aqui mostramos como ter acesso ao seu token e aqui como você pode criar um Leaf User.
Agora, vincule suas credenciais ao Leaf User criado.
Envie um POST para
https://api.withleaf.io/
services/usermanagement/
api/users/yourLeafUserId/
climate-field-view-credentials
Com o seguinte header:
Authorization: Bearer
e o seguinte corpo JSON:
{
"clientId": "Your client ID",
"clientSecret": "Your client secret",
"apiKey": "Your api key",
"refreshToken": "The refresh token received on the last step"
}
Excelente!
Agora a Leaf começará a trazer os seus dados agrícolas da Climate FieldView. Você pode agora consultar os seus dados padronizados pela Leaf.
Desenvolvedores de Software utilizam a API da Leaf para construir e escalar uma vasta gama de produtos, incluindo a otimização de ferramentas agrícolas, empréstimos, financiamentos baseados em resultados, mercados de terra e insumos, recomendações agronômicas, aplicativos de rastreabilidade, manutenção preditiva de equipamentos e muito mais.
