Sobre API RD Station

Submitted by kaleu on Fri, 04/17/2020 - 20:45
Uma imagem com um notebook e um outro bloco escrito "API"

Anotações sobre integração OAuth com API RDStation Marketing para simples envio de leads para o RD através de um software externo.

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.

Image removed.

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.

Image removed.

O caminho correto é primeiro acessar o menu da primeira imagem e criar um APP DE INTEGRAÇÃO no Market Place da RD.

Image removed.

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/.

Image removed.

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:

Image removed.

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:

https://api.rd.services/auth/dialog?client_id=#{client_id}&redirect_url=#{redirect_url}

Após isso, sua URL de Callback receberá um retorno simples assim:

https://webhook.site/b5fe5796-1111-XXXX-YYYY-a4444444ff44?code=73331499955222eeeee0cddd9c577d77

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:

Image removed.

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.

Image removed.

Você pode ver o lead cadastrado na RD de acordo com a imagem abaixo:

Image removed.

Próximos passos

Em breve vou complementar com:

  • O que acontece quando o lead já existe;
  • Envio de campos customizados na criação do lead;
  • Inclusão do lead em um funil;
  • Registro de conversão de venda.

Referências de Código

Tags