Autenticação APIs RD Station
Fala, Dev! Você sabe como utilizar as APIs da plataforma RDStation?
Fique tranquilo, que neste post explicaremos passo a passo, construindo uma integração do zero!
O primeiro passo é atendermos os pré-requisitos:
Conta no RD Station
Precisamos de uma conta na plataforma RD Station, afinal, a API coleta e manipula dados de uma conta na plataforma.
Pode-se utilizar a conta de um cliente ou criar uma conta trial aqui.
Se a sua integração for pública, você pode solicitar uma conta de testes aqui.
Aplicativo
Precisamos criar um aplicativo na appstore do RDStation.
Para criar esse aplicativo, precisa usar uma conta da plataforma que será responsável por esse aplicativo. Ou seja, você como techpartner, deverá ter uma conta sua no RDStation.
Para criar um aplicativo, basta logar na appstore com sua conta e clicar para criar um novo aplicativo, preenchendo os seguintes campos:
Nome: Qual será o nome do seu aplicativo?
Tipo: Seu aplicativo será privado ou público?
Categoria: Seu aplicativo se encaixa em qual categoria? Integração com CRM? Produtividade?
Idiomas do aplicativo: Seu aplicativo estará disponível para quais linguagens?
Site da empresa: Qual o site da empresa responsável pelo aplicativo?
Urls de callback: Seu aplicativo precisará ter pelo menos uma url de callback. Esta URL será utilizada no processo de autenticação.
Mais detalhes da criação do aplicativo neste tutorial da nossa seção de ajuda.
Conta na plataforma do parceiro
Estamos falando de uma integração entre 2 sistemas. Logo, além da conta na plataforma da RD Station, você precisará de uma conta na plataforma que se integrará.
Por exemplo: para utilizar uma integração com a Pluga, você precisará de uma conta na plataforma da Pluga.
Requisitos atendidos? Bora para prática!
Criando URL de autorização
Para criar esta URL, precisaremos do client_id e da URL de callback cadastradas no seu aplicativo da appstore.
Nota: A URL de callback é uma rota desenvolvida e de responsabilidade do techpartner.
Tendo essas informações, conseguimos criar a URL seguindo esse padrão:
https://api.rd.services/auth/dialog?client_id=[CLIENT_ID_APP]&redirect_uri=[URL_CALLBACK_APP]
Utilizando o aplicativo de exemplo, ficaria desta forma:
Este será o link que deverá ser disponibilizado para os clientes que desejam integrar a sua plataforma com o RDStation.
Usuário autorizando o aplicativo
Seu aplicativo está configurado e você possui a url de integração. Bora testar?
Basta abrir a url de integração criada anteriormente, que abrirá uma tela para que o usuário do RD Station autorize seu aplicativo a acessar os seus dados da plataforma.
Neste cenário, estou logado no usuário Renan Porto; onde este deseja integrar com meu aplicativo. Esta tela permitirá que o usuário se conecte ao seu aplicativo.
Clicando em conectar, o usuário será redirecionado para a sua URL de callback:
Note que será enviado como query string um parâmetro chamado CODE, que seu aplicativo deverá salvar para utilizar na geração do primeiro token.
Nesta tela, é sugerido fazer um aviso para o cliente informando que a integração foi feita com sucesso!
Gerando o primeiro token
Usuário está integrado com seu sistema! Legal! Mas.. e aí? Quando o usuário criar um novo lead no seu sistema e você deseja criar esse lead no RD Station, como você pode fazer?
Primeiramente, temos que entender que a autorização das APIs do RD Station são feitas via tokens. O parâmetro CODE enviado anteriormente para a sua URL de callback permitirá gerar o primeiro token de acesso de seu aplicativo à conta do usuário do RD Station.
Para gerar o primeiro token, você precisará — além do CODE — do cliente_id e do client_secret do seu aplicativo. Esta informação pode ser vista no passo “Criando URL de autorização”.
Basta fazer a requisição abaixo, para gerar o primeiro token:
curl --request POST \
--url 'https://api.rd.services/auth/token' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"client_id": "6b5f1e9a-4d58-4fee-a17b-b31fca15500d",
"client_secret": "2d3585f2ceba402e82d41c3a12fee3f2",
"code": "7d63c19de92d87e44608f6e40169e106"
}
'O retorno será algo como:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9",
"expires_in": 86400,
"refresh_token": "ctald8r3GFg85IIwVBalBVlg1Hh8cJ1KNinAO78uwl0"
}*O access_token será uma string maior do que a do exemplo. Diminuímos para ficar didático.
Com este token, terás a autorização para utilizar todas as APIs disponibilizadas pelo RDStation (verificar disponibilidade da API por plano), conforme nosso portal de desenvolvedor.
Chamando a primeira API
Com o token em mãos, conseguimos utilizar todas as APIs, como dito anteriormente. Para fins didáticos, iremos pensar no seguinte caso de uso:
Os leads no nosso sistema possuem um campo que não existe por padrão no RDSM: o campo CEP. Para isto então, desejamos criar um campo personalizado no RDSM, para que possamos enviar esse campo ao criar um lead.
Para isto, iremos utilizar a API Criar Campo Personalizado. Utilizando o nosso token, fazemos a requisição conforme a documentação:
curl --request POST \
--url https://api.rd.services/platform/contacts/fields \
--header 'accept: application/json' \
--header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9' \
--header 'content-type: application/json' \
--data '
{
"data_type": "STRING",
"name": {
"pt-BR": "CEP"
},
"label": {
"pt-BR": "CEP"
},
"presentation_type": "TEXT_INPUT",
"api_identifier": "cf_cep"
}
'O retorno foi:
HTTP Code 201
{
"uuid": "356d925c-ba3f-48aa-aa12-d6f6b66ebd46",
"label": {
"pt-BR": "CEP",
"default": "CEP"
},
"name": {
"pt-BR": "CEP",
"default": "CEP"
},
"api_identifier": "cf_cep",
"custom_field": true,
"validation_rules": {},
"presentation_type": "TEXT_INPUT",
"data_type": "STRING"
}Verificando no sistema, vemos que o campo personalizado foi criado:
E está disponível para ser cadastrado tanto via API, como na própria interface do RD Station:
Conclusão
Agora basta aproveitar todas as nossas APIs disponíveis para enriquecer a integração cada vez mais!
