Anotações sobre integração OAuth com API RDStation Marketing para simples envio de leads para o RD através de um software externo.
Este artigo foi escrito em 17 de abril de 2020. As coisas podem ter mudado.
Aqui está a documentação oficial. Tive dificuldades de compreender diversos elementos. Minha maior dificuldade foi compreender o fluxo de autenticação. Não considero a documentação clara, mas o suporte foi excelente e rápido em responder minhas dúvidas.
OAuth
A RD utiliza OAuth. OAuth é um processo completo com diversas peças que cada implementação opta por esconder uma ou outra. Por exemplo, na integração com a RD, apesar de estar lá, você não lida diretamente com o OAuth Scope, exceto no cadastro via UI da APP de integração.
Tenha em mente antes de iniciar que a integração envolve três atores:
- A sua CONTA, ou seja, o seu acesso pago à toda a plataforma e base de leads do RD Marketing;
- A API que tem os serviços para cadastrar, alterar e converter leads;
- O APP DE INTEGRAÇÃO, que deverá ser criado e cadastrado no Market Place.
Com isso em mente, vamos começar.
Conceitos Básicos para Autenticação
A autenticação da RD não é simples como a maioria das integrações que utiliza algum tipo de token de API. Isso ocorre porque todas as integrações usam O Marketplace da RD e consequentemente, exige que o desenvolvedor crie uma APP externa para acessar os dados, uma APP da própria RD.
Eu perdi algum tempo porque nos dados de integração da CONTA tem lá um ID público de API e um ID secreto de API. IGNOREM, não serve para nada na integração atual, talvez seja vestígio de alguma versão antiga da API.
O caminho correto é primeiro acessar o menu da primeira imagem e criar um APP DE INTEGRAÇÃO no Market Place da RD.
Usei na categoria “Integrador” que me parece agrupar permissões que você precisará do APP, você terá que avaliar sua necessidade.
Não identifiquei onde eles documentam isso, mas me parece que essa categoria representa o conjunto de permissões o oAuth Scope que seu app estará usando.
Você terá que informar uma URL de callback. Para simplesmente conectar sua plataforma com a RD, essa url de callback será usada apenas uma vez em um processo manual (que vou explicar abaixo). Para gerar essa url use um serviço que te fornece uma URL de callback online na hora, como o https://webhook.site ou o https://beeceptor.com/.
Agora, vamos olhar o processo completo
Processo de Autenticação – Conseguindo o Código
Neste ponto você já entendeu que precisa ter a sua CONTA e um APP no Marketplace.
Você precisará de três dados para poder integrar seu software com a RD, são eles:
- Chave pública do APP;
- Chave secreta do APP;
- Código de permissão para o APP acessar a CONTA.
Os dois primeiros dados podem ser obtidos na página do APP no Marketplace, como na imagem abaixo:
Parar gerar o código você vai fazer uma requisição para uma página do RD, que vai exigir que você faça login e associe a sua conta com o APP. Quando você ativar essa associação com um OK padrão de auetnticação OAuth, aquela url de callback será acessada com um parâmetro, o code.
Assim, a URL que você deve usar para gerar o código é essa:
Após isso, sua URL de Callback receberá um retorno simples assim:
Pegue esse código: 73331499955222eeeee0cddd9c577d77.
Com estas três informações estamos prontos para avançar para automatização. este código expira em 1 hora, você só precisará dele para gerar o access_token, depois pode descartá-lo. Se no futuro você perder seu refresh token ou precisar revogar o acesso, terá que seguir este processo novamente e gerar um novo code para avançar na integração.
Processo de Autenticação – Conseguindo o Token de Acesso
Agora, nós vamos usar estas informações para obter um token de acesso. Esta parte do processo está bem documentada na documentação oficial e fica mais simples, vamos reproduzir aqui para apoiar o aprendizado:
O passo 1 é enviar uma requisição post para https://api.rd.services/auth/token:
O token de acesso tem validade de 24 horas. Você terá que gerar um novo sempre que ele expirar. Na documentação oficial há o exemplo de como gerar um novo token a partir do refreshtoken. De acordo com o suporte, o refeshtoken não expira, então, sempre que necessário você poderá usar ele, junto do ID público e ID secreto do APP para obter um novo token de acesso.
Como enviar um lead para a RD
Segue exemplo de criação de lead no RD. O token de acesso deve ser enviado como um header de autenticação bearer.
Você pode ver o lead cadastrado na RD de acordo com a imagem abaixo:
Referências de Código
- Um exemplo de código em PHP: https://gist.github.com/rcarvs/3082a8888f72886f995ae371bd56253d
- Um exemplo de código em Ruby: https://github.com/ResultadosDigitais/rdstation-ruby-client/blob/master/lib/rdstation/authentication.rb