Neste post, mostraremos como é fácil realizar o fluxo de autorização da John Deere com a Leaf. Ou seja, obter autorização para acessar os dados dos seus usuários disponíveis na John Deere através da API da Leaf. Faremos algumas chamadas à Leaf, todos os endpoints podem ser encontrados em nossos docs e na Postman Collection.
(Click here for the translation in English.)
Sumário
- Passo 0: Criar uma conta de desenvolvedor na John Deere
- Passo 1: Obtenha suas credenciais de desenvolvedor da John Deere
- Passo 2: Obtenha os tokens de seus usuários da John Deere com a Leaf
- Passo 3: Obtenha permissão para acessar os dados de seus usuários
- Passo 4: Adicione as credenciais da John Deere à Leaf
Este tutorial é um passo a passo completo. A maioria dos passos apresentados serão realizados apenas uma vez, fazendo com que as próximas solicitações sejam muito mais fáceis e rápidas.
Passo 0: Criar uma conta de desenvolvedor na John Deere
(Se você já tem uma conta de desenvolvedor na John Deere, pode pular este passo)
Criar uma conta de desenvolvedor na John Deere é um processo bem simples e automático, basta se cadastrar neste link.
Depois disso, você terá criado uma conta de desenvolvedor e poderá seguir para o próximo passo deste tutorial.
Passo 1: Obtenha suas credenciais de desenvolvedor da John Deere
Ao final deste passo, você terá obtido:
- seu App ID e Shared Secret
Obtenha seu App ID e Shared Secret da John Deere
Primeiro, você deve acessar sua conta de desenvolvedor da John Deere. Para isso, acesse https://developer.deere.com/, e clique em Sign In (canto superior direito) e faça o log in.
Clique em “My Applications” na barra horizontal:
Em seguida, clique em "Create Application" e crie um novo aplicativo.
Preencha os dados de acordo com a sua empresa:
E agora, você selecionará as APIs que devem ter acesso permitido. Selecione Field Operations e Webhook. Caso seu aplicativo exija outros dados, selecione as APIs apropriadas nesta etapa.
Estes são os acessos necessários para cada produto Leaf:
| Leaf | John Deere API access |
|---|---|
Base |
Organizations, Webhook |
Field Boundary |
Clients, Farm, Field, Boundaries |
Machine Files/Field Operations |
Field Operations, Files |
Beta > Prescriptions |
Files |
Beta > Assets > Machines |
Machines |
Beta > Assets > Implements |
Implements |
Beta > Assets > Operators |
Operators |
Beta > Input database (JD products) |
Products |
Por último, obtenha um App ID e Secret:
A John Deere irá entrar em contato com você em breve para que você tenha acesso aos endpoints requisitados.
Passo 2: Obtenha os tokens de seus usuários da John Deere com a Leaf
Para obter os tokens dos seus usuários para acessar os dados da John Deere, sua aplicação deve passar pelo fluxo OAuth da John Deere. Primeiro, você precisa redirecionar o usuário para uma URL customizada que é a página que a John Deere dará ao usuário a opção de autorizar o acesso aos seus dados.
Para obter a URL para esse passo de autenticação, faça uma requisição POST para
https://johndeere-oauth2-helper.withleaf.io/get_url
Com o seguinte JSON:
{
"clientKey": "Your John Deere app ID",
"clientSecret": "Your John Deere app Secret",
"clientRedirectUrl": "Your app's URL"
}
A Leaf retornará uma URL para qual você enviará seu usuário, onde ele pode autorizar o acesso aos seus dados e serem redirecionados para a sua aplicação. Note que a John Deere irá redirecionar o seu usuário para “clientRedirectUrl” e também enviará um código que você precisará para fazer uma requisição final, e obter os tokens de seus usuários. A clientRedirectUrl deve ser estabelecida nas configurações da sua aplicação.
Obtenha os tokens de seus usuários
Agora, a última coisa necessária são os tokens de seus usuários. Uma vez que eles logarem no link do site da John Deere que você criou, eles irão autorizar sua aplicação a acessar os dados deles e serão redirecionados de volta para a “clientRedirectUrl” que você estabeleceu. Então, sua aplicação usará a URL de resposta para obter os tokens de seus usuários. É só enviar uma requisição POST para
https://johndeere-oauth2-helper.withleaf.io/
get_token
Com o seguinte JSON:
{
"clientKey": "Your John Deere app ID",
"clientSecret": "Your John Deere app Secret",
"responseUrl": "The URL John Deere redirected the user to"
"clientRedirectUrl": "Your app's URL"
}
Um JSON contendo os tokens (“accessToken” e “refreshToken”) retornará, e você poderá adicioná-los à Leaf como credenciais da John Deere.
Nota: A Leaf gerenciará todos os tokens, garantindo que estejam sempre atualizados e validados.
Passo 3: Obtenha permissão para acessar os dados de seus usuários
Agora que os usuários estão conectados à sua aplicação, os usuários devem permitir que você acesse os dados deles. Para isso, os redirecione para a seguinte URL:
https://connections.deere
.com/connections/
yourJohnDeereAppId/
select-organizations?
redirect_uri=your
RedirectUrl
Substitua os campos que requerem URLs com a sua ID da aplicação da John Deere e a url de redirecionamento da sua aplicação. A URL de redirecionamento não precisa ser a mesma usada nos passos anteriores, contanto que também esteja estabelecida na configuração da sua aplicação. Seus usuários serão redirecionados para a seguinte tela:
Nesta tela, os usuários selecionarão as organizações que querem compartilhar dados com você, clique no botão para que fique verde, e salve. A Leaf poderá apenas buscar dados de organizações autorizadas. Depois disso, os usuários serão redirecionados para a URL de redirecionamento específica.
Passo 4: Adicione as credenciais da John Deere à Leaf
A API da Leaf usa uma abstração chamada Leaf User para armazenar credenciais e organizar dados para cada proprietário de dados individualmente. Na maioria dos casos, o Leaf User será o fazendeiro ou consultor que tem acesso à fonte de dados dentro das FMIS das empresas de maquinários (ex.: John Deere Operations Center ou a plataforma da Climate Field View).
A API da Leaf deve, então, ser iniciada com as suas credenciais da John Deere para poder acessar e padronizar os dados da John Deere. Para enviar suas credenciais para a Leaf, você deve acessar seu token da Leaf, e já ter criado um Leaf User. Se você não sabe como fazer isso,
Nota: O mesmo Leaf User pode ser indexado a vários provedores, para que você possa consultar dados de todos os provedores que aquele Leaf User tem acesso ao mesmo tempo.
Agora, indexe suas credenciais ao Leaf User que você criou. Faça uma requisição POST para
https://api.withleaf.io/
services/usermanagement/
api/users/yourLeafUserId/
john-deere-credentials
Com o seguinte Header:
Authorization: Bearer { {yourLeafToken} }
E o seguinte JSON:
{
"clientKey": "Your John Deere app ID",
"clientSecret": "Your John Deere app Secret",
"refreshToken": "The Refresh Token from the last step"
"clientEnvironment": "The environment to use with this credential"
}
O valor padrão para clienEnvironment é STAGE conhecido como Sandbox pela John Deere. Para você ter uma credencial ativa com clientEnvironment sendo PRODUCTION, sua aplicação deve ter permissões de produção da John Deere, caso contrário você não poderá utilizar estas credenciais. Para obter permissões de produção, você pode seguir o tutorial da John Deere.
Você deve seguir as diretrizes de uso do ambiente STAGE/Sandbox da John Deere, isso evitará que sua aplicação seja revogada e permitirá uma posterior transição para produção sem maiores problemas:
- Ter apenas uma conta de teste (1 Leaf API Owner);
- A aplicação não deve estar conectada a mais de cinco organizações (Leaf users);
- A aplicação não poderá fazer mais de 150.000 requisições por mês à API (Leaf cuidará disto);
- A aplicação não deverá ficar no ambiente de sandbox por mais de 18 meses.
Excelente!
Agora a Leaf começará a buscar seus dados agrícolas da John Deere. Você pode agora consultar a Leaf para obter seus dados padronizados.
Desenvolvedores de software usam a API da Leaf para construir e escalar uma ampla gama de produtos, incluindo ferramentas de otimização de fazendas, financiamento baseado em resultados, mercados de terras e insumos, recomendações agronômicas, aplicações de rastreamento, manutenção preditiva de equipamentos e mais.
