Neste post, vamos explorar como integrar a API da RDStation em uma aplicação Ruby utilizando o cliente oficial rdstation-ruby-client. Este guia abordará desde a instalação da gem até a configuração e uso de diferentes funcionalidades, como autenticação, manipulação de contatos, eventos e muito mais.

Como utilizar RDStation Ruby Client ?

Instalação

gem 'rdstation-ruby-client'

Para começar, adicione a seguinte linha ao seu Gemfile:

Depois execute o comando para instalar a gem através do bundler:

$ bundle install

Caso prefira instalar a gem manualmente, utilize o comando:

gem install rdstation-ruby-client

Agora, com a configuração da gem pronta no seu projeto, vamos gerar e adicionar suas credenciais.

Configuração

Antes de utilizar a API, é necessário configurar as credenciais client_id e client_secret, que podem ser obtidas no portal de desenvolvedores da RDStation.

Primeiro, crie um arquivo no diretório config/initializers chamado rdstation.rb. Em seguida, adicione a seguinte configuração a esse arquivo para inicializar a integração corretamente.

Adicione as suas credenciais:

RDStation.configure do |config|
 config.client_id = 'SEU_CLIENT_ID'
 config.client_secret = 'SEU_CLIENT_SECRET'
end

Como funciona a Autenticação?

Ao criar o seu aplicativo na RD Station App Store você receberá as duas credenciais. Essas credenciais são utilizadas para gerar um codigo, que autoriza a conexão do aplicativo a uma conta específica na RD Station.

URL de Autenticação

Para autenticar um usuário, você deve primeiro gerar a URL de autenticação:

• O objetivo dessa etapa é autorizar o aplicativo a se conectar com a conta desejada da RD Station.

rdstation_authentication = RDStation::Authentication.new
redirect_url = 'https://suaapp.org/auth/callback'
rdstation_authentication.auth_url(redirect_url)

Gerar Access Token e Refresh Token

Depois que o usuário autorizar o acesso na URL de autenticação, um código será retornado para sua aplicação. Com esse código, você poderá gerar o access_token e o refresh_token:

rdstation_authentication = RDStation::Authentication.new
rdstation_authentication.authenticate(CODE)

# => { 'access_token' => '54321', 'expires_in' => 86_400, 'refresh_token' => 'refresh' }

Uma vez que os tokens tenham sido gerados, o access_token será utilizado nas requisições para autorizar as trocas de informações via API.

Também é possível configurar um callback para que, quando ocorrer a renovação do token, ele seja atualizado automaticamente pela aplicação para uso futuro:

No exemplo abaixo, estamos utilizando Redis para armazenar e manter as credenciais atualizadas.

RDStation.configure do |config|
  config.on_access_token_refresh do |authorization|
    new_access_token = authorization.access_token
    new_refresh_token = authorization.refresh_token

    $redis.hmset("credentials", "access_token", new_access_token,
                               "refresh_token", new_refresh_token)
  end
end

Manipulação de Contatos (LEADS)

Obter Contato por UUID

Para buscar um contato específico através do UUID, utilize:

client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.contacts.by_uuid('uuid')

Obter Contato por Email

Da mesma forma, você pode buscar um contato utilizando seu email:

client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
client.contacts.by_email('[email protected]')

Atualizar Contato

Para atualizar as propriedades de um contato, utilize:

contact_info = { name: "George Pires" }
client.contacts.update('uuid', contact_info)

Upsert de Contato

Com a operação de UPSERT, com esse método você consegue atualizar as propriedades de um Contato ou criar um novo Contato na Base de Leads:

contact_info = { name: "George Pires" }
identifier = "email"
identifier_value = "[email protected]"

client.contacts.upsert(identifier, identifier_value, contact_info)

Criar eventos de conversão

Estrutura de um evento padrão:

{
  event_type: "TYPE EVENT",
  event_family: "CDP",
  payload: {
   ...
  }
}

Para enviar um novo evento para a API, utilize:

payload = {}  # payload do evento
client.events.create(payload)

Evento de conversão padrão

{
  event_type: "CONVERSION",
  event_family: "CDP",
  payload: {
    conversion_identifier: "Conversão exemplo",
    email: "[email protected]",
  },
}

Também podemos criar e adicionar campos personalizados aos eventos:

🚨 Deve ser preenchido seguindo a estrutura: cf_nome_do_campo

{
  event_type: "CONVERSION",
  event_family: "CDP",
  payload: {
    conversion_identifier: "Venda",
    email: "[email protected]",
    cf_razao_social: @pedido.razao_social,
    cf_cnpj: @pedido.cnpj,
    cf_status_do_pedido: @pedido.status,
    cf_tipo_de_pagamento: @pedido.tipo_pagamento,
    cf_valor_total: @pedido.valor_total,
  },
}

No exemplo acima, foram criados 5 campos personalizados para enviar um evento de conversão com a identificação “Venda”.

O payload contém:

• conversion_identifier: identifica o tipo de conversão como “Venda”.
• email: e-mail do cliente (nesse exemplo, “[email protected]”).
• cf_razao_social: a razão social associada ao pedido.
• cf_cnpj: o CNPJ do cliente.
• cf_status_do_pedido: o status atual do pedido.
• cf_tipo_de_pagamento: o tipo de pagamento usado.
• cf_valor_total: o valor total do pedido.

Esses dados personalizados ajudam a rastrear e armazenar informações detalhadas sobre a conversão de vendas.

Eventos de Fechamento de Pedido

Responsável por descrever o comportamento de um contato no processo de compra de produtos em um E-commerce.

🚨Esse tipo de evento não aceita Campos Personalizados.

{
  event_type: "ORDER_PLACED",
  event_family: "CDP",
  payload: {
    name: "George Pires"
    email: "[email protected]",
    cf_order_id: "ID do pedido",
    cf_order_total_items: 5,
    cf_order_status: "Status do pedido",
    cf_order_payment_method: "Cartão de crédito",
    cf_order_payment_amount: 200,
  },
}

Considerações

Este guia fornece uma visão geral da integração com a API da RDStation usando o RDStation Ruby Client.

Essa gem é especialmente útil para empresas que utilizam a RDStation como parte de sua estratégia de marketing digital e precisam automatizar processos ou integrar dados de marketing com outras ferramentas, ou sistemas.

Referências

• Gem – RDStation Ruby Client
• Documentação API RD Station
• Batch de Eventos
• Ruby API wrapper for RD Station