Autenticação da John Deere com a Leaf

Como se conectar à John Deere via API da Leaf.

Autenticação da John Deere com a Leaf

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. Let’s get to it!

(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 sua permissão da John Deere para acessar os endpoints
  • Passo 3: Obtenha os tokens de seus usuários da John Deere com a Leaf
  • Passo 4: Obtenha permissão para acessar os dados de seus usuários
  • Passo 5: 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.

Leaf, data infrastructure for agriculture

Clique em “My Applications” na barra horizontal:

Leaf, data infrastructure for agriculture

Então, clique em “Add Application” e crie uma nova aplicação.

Leaf, data infrastructure for agriculture

Uma vez criada, clique em “View Details”:

Leaf, data infrastructure for agriculture

Por último, obtenha um App ID e Secret:

Leaf, data infrastructure for agriculture

Perfeito! Agora você tem o seu App ID e Shared Secret da John Deere. Você os utilizará no próximo passo.

Passo 2: Obtenha sua permissão da John Deere para acessar os endpoints

Por padrão, a John Deere dá à sua aplicação acesso a uma quantidade limitada de endpoints, incluindo a habilidade de obter detalhes de campo e maquinário. Antes da Leaf poder buscar os dados de operações, você deve pedir permissão para a John Deere para acessar os endpoints. Na landing page da John Deere, https://developer.deere.com/, clique em “Contact Us”, no canto inferior. Lá, selecione “API Access Request”, e um formulário irá aparecer.

Leaf, data infrastructure for agriculture

Preencha com as informações necessárias do form, incluindo o Application Name & Client ID (opcionais) criados no passo 1. No campo Available APIs, insira Field Operations. Na seleção Description, por favor descreva o caso de negócio que necessita acesso às APIs. Você também pode pedir permissão para outras APIs baseadas nos dados que você precisa de integração. Envie o formulário para a John Deere.

A John Deere irá entrar em contato com você em breve para que você tenha acesso aos endpoints requisitados.

Lembre-se de criar uma nova solicitação para máquinas (Available APIs) se seu aplicativo também precisar de acesso aos dados da máquina.

Passo 3: 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:

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:

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 4: 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=yourRedirectUrl

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:

Leaf, data infrastructure for agriculture

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 5: 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,

  • Aqui você pode conseguir acesso ao seu token
  • Aqui você consegue criar um Leaf User

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:

E o seguinte JSON:

O valor padrão para clienEnvironment é STAGE. 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.

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.

Aqui está um link para o site da Leaf.

Ready to begin?

Get API Keys and Start Building Today!

Sign up for free account

Questions? Get in touch