Minha primeira aplicação

Para seguir este tutorial, você precisará ter instalado:

Utilizamos o Git na versão 2.20.1 e o Node.js na versão 12.3.1, mas recomendamos sempre utilizar as versões estáveis mais atualizadas.

Conteúdos

→Introdução
→Configuração do projeto
→Crie uma aplicação no Mercado Livre
→Início do desenvolvimento
→Deploy para o Heroku
→Ajustes no Mercado Livre
→Configurações de rota
→Atualizações


Introdução

Nesse tutorial, estaremos construindo uma aplicação integrada com o Mercado Livre e protegida por senha para podermos publicar itens e recuperar itens publicados.

Para facilitar nosso trabalho, estaremos utilizando a SDK do Mercado Livre para Node.js (clique aqui para visitar a página de ferramentas do Mercado Livre).

Tela de login

Formulário de envio de itens

Listagem de itens


Configuração do projeto

Para iniciar o projeto, clique aqui e faça download dos arquivos e diretórios.

Abra a ferramenta de linha de comando no diretório do seu projeto e rode o comando npm install, para instalar as dependências do projeto. Utilizamos as seguinte dependências:

  • mercadolibre: esse é o SDK do Mercado Livre, que irá auxiliar/facilitar o desenvolvimento da nossa integração.
  • express: facilitará o desenvolvimento da nossa aplicação em Node.js.
  • ejs: irá trabalhar com o express e servirá como view engine para criarmos nossos templates.
  • dotenv: permitirá inserir variáveis de ambiente definidos em um arquivo .env no nosso código local.
  • multer: facilitará o upload de arquivos (que usaremos para a disponibilização de fotos para o Mercado Livre).
  • helmet: criará uma camada de proteção para sua aplicação Node.js.
  • cookie-session: será responsável pelo gerenciamento dos dados de session (para validar um usuário logado, por exemplo).

Crie uma aplicação no Mercado Livre

Você já tem um projeto em Node.js, porém precisamos criar uma aplicação dentro do Mercado Livre para trabalhar com a integração. Para fazer isso:

  1. Acesse o nosso DevCenter.
  2. Clique em "Criar nova aplicação".
  3. Preencha com todos os dados obrigatórios. Em "URI de redirect", preencha com a raiz do domínio:
  4. Nota:
    É importante que esse campo seja preenchido com uma URL própria, válida e que esteja configurada para receber notificações.


  5. Em "Tópicos", você pode selecionar os tópicos que você tem interesse em receber notificações, e em "URL de retornos de chamada de notificação", configuramos uma rota para receber notificações sobre os tópicos.



  6. O Mercado Livre irá fazer requisições para essa rota sempre que ocorrer algo relevante dentre os tópicos selecionados. Para mais informações, dê uma olhada na documentação de notificações. Salve o projeto e você será redirecionado à página inicial, na qual sua aplicação estará listada. Você pode ver o ID e a Secret Key que sua aplicação expôs. Com esse valores, podemos começar a nossa integração.
 

Lembre-se de que "localhost" é uma URL provisória que será substituída assim que fizermos o deploy.

Início do desenvolvimento

Agora que você tem o projeto instalado e uma aplicação criada no Mercado Livre, crie um arquivo com o nome .env, que servirá para inserirmos nossas variáveis de informação sensível no código sem precisarmos compartilhar em plataformas de controle de versão e colaboração de código (como GitHub, GitLab, Bitbucket, etc.).

Copie o conteúdo de dentro do arquivo .env.example, cole no arquivo que você acabou de criar e preencha com as variáveis. Você deve obter um resultado como o seguinte:

 CLIENT_ID={O ID da sua aplicação no Mercado Livre}
 CLIENT_SECRET={A key da sua aplicação no Mercado Livre}
 REDIRECT_URI=http://localhost:3000 SYS_PWD={A senha que você quer uso no seu sistema}     

Sua aplicação está pronta para uso local! Na sua ferramenta de linha de comando, rode o comando npm start e acesse a URL http://localhost:3000. Agora que temos nossa aplicação rodando, podemos continuar para a fase de deploy.

 

Você pode parar a execução a qualquer momento pressionando as teclas Ctrl+C.

Deploy para o Heroku

O Heroku é uma plataforma como um serviço (PaaS) que suporta diversas linguagens e permite que desenvolvedores construam e subam suas aplicações para a nuvem.

Para fazer o deploy para o Heroku, primeiro precisamos saber a versão do Node.js com a qual estamos trabalhando. Rode o comando node --version na sua ferramenta de linha de comando e copie os números que aparecerem.

Abra o arquivo package.json e, no final do arquivo, modifique a propriedade "engines" para que tenha os números da sua versão.

Feito isso, você precisará instalar o CLI do Heroku. Você pode fazer isso acessando a página do Heroku e fazendo o download.

Utilizaremos o Git para enviar o projeto ao Heroku. Rode o comando git init. Depois, rode o comando git add . e, por último, o comando git commit -m "first commit". Você pode trocar a mensagem "first commit" por qualquer mensagem que desejar.

Para criar sua aplicação no Heroku, siga os seguintes passos:

  1. Faça login no Heroku através do comando heroku login.
  2. Quando estiver logado, rode o comando heroku create my-meli-application. Você pode trocar "my-meli-application" pelo nome que quiser dar a sua aplicação. Para mais informações, cheque a documentação do Heroku.
  3. Para subir os arquivos ao servidor do Heroku, rode o comando git push heroku master. As variáveis do arquivo .env não devem subir diretamente ao servidor. Existe um modo de criar variáveis de configuração direto pela linha de comando. Rode os comandos:
    • heroku config:set CLIENT_ID={ID DA APLICAÇÃO NO MERCADO LIVRE}
    • heroku config:set CLIENT_SECRET={SECRET KEY DA APLICAÇÃO NO MERCADO LIVRE}
    • heroku config:set REDIRECT_URI=https://{NOME-DA-APLICAÇÃO}.herokuapp.com
    • heroku config:set SYS_PWD={SENHA QUE VOCÊ UTILIZARÁ NO SISTEMA}

E, por fim, para ver sua aplicação funcionando, rode o comando heroku open.


Ajustes no Mercado Livre

Agora que você publicou sua primeira integração, a URL já não é mais "localhost". Precisamos voltar ao DevCenter do Mercado Livre para realizar os ajustes necessários.

  1. Acesse novamente nosso DevCenter.
  2. Clique nos três pontos e depois em "editar", para editar a aplicação:


  3. Modifique a "URI de redirect" para a nova URL fornecida pelo Heroku (essa URL deve ser a mesma atribuída nas variáveis de configuração).


  4. Modifique, também, a "URL de retornos de chamada de notificação":


Configurações de rota

Para você entender melhor o sistema de rotas dessa pequena integração, vamos preparar uma tela de listagem de itens.

Abra o arquivo app.js e adicione o seguinte trecho de código antes de module.exports = app:

app.get('/posts', validateToken, async (req, res) => {
   try {
     const meliObject = new MeliObject(res.locals.access_token);
     const user = await meliObject.get('/users/me');
     const items = (await meliObject.get(`/users/${user.id}/items/search`)).results || [];
     if (items.length) {
       const result = [];
       const promises = items.map(item_id => meliObject.get(`/items/${item_id}`));
       for await (item of promises) {
         result.push(item);
       }
       res.render('posts', { items: result });
     } else {
       res.status(404).send('no items were found :(');
     }
   } catch(err) {
     console.log('Something went wrong', err);
     res.status(500).send(`Error! ${err}`);
   }
 });

A linha de código res.render('posts', { items: result }) diz para o código renderizar uma página chamada posts.ejs no diretório views.

Crie essa página posts.ejs no diretório views e acrescente o seguinte código:

 <!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <meta http-equiv="X-UA-Compatible" content="ie=edge">
   <title>Posts - My Meli Application</title>
   <link rel="stylesheet" type="text/css" href="/css/style.css" />
 </head>
 <body>
   <div class="container">
     <div class="items-list">
       <% for (item of items) { %>
         <a target="_blank" rel="noopener noreferrer nofollow" href="<%= item.permalink %>">
           <div>
             <img src="<%= item.secure_thumbnail %>" />
             <h3><%= item.title %></h3>
           </div>
         </a>
       <% } %>
     </div>
   </div>
 </body>
 </html>     

Atualizações

Conforme você implementa novas funcionalidades na sua integração, você precisará subir as atualizações para o Heroku.

Para fazer isso, basta repetir alguns dos passos que fizemos anteriormente:

  1. Rode o comando git add . para adicionar os arquivos em stage.
  2. Rode o comando git commit -m "adiciona tela de listagem de itens". Você pode trocar a mensagem para o que achar melhor, mas é recomendável manter sempre uma mensagem curta, limpa e bem relacionada às alterações feitas.
  3. Para subir os arquivos e reiniciar o servidor, rode o comando git push heroku master.
ou registre-se para receber as últimas notícias sobre nossa API