Como configurar a integração com Salesforce

[lindsey (Lindsey Fogle)]

Este guia aborda as etapas de configuração necessárias para conectar o Discourse ao Salesforce usando o plugin Discourse Salesforce.

O Discourse Salesforce está disponível no plano Enterprise.

Nível de usuário necessário: Administrador

Etapa 0: Encontrar as pessoas certas na sua organização

Antes de fazer qualquer coisa no Discourse, certifique-se primeiro de que você conhece as pessoas certas da sua organização para envolver nos requisitos do lado do Salesforce.

Administrador do Salesforce

Quem são: Na maioria das organizações, esta é geralmente a pessoa que sua equipe chama de “admin do Salesforce” — a pessoa que gerencia a configuração da sua org do Salesforce, e não necessariamente seu administrador de sistemas de TI.

O que fazem: Cuida da configuração inicial do lado do Salesforce criando o External Client App (ou Connected App) na Configuração do Salesforce, configurando as definições de OAuth e obtendo a Consumer Key e a Consumer Secret.

O que precisam: Acesso à Configuração (Setup) do Salesforce e especificamente ao External Client App Manager. No Salesforce, isso requer a permissão de sistema Customize Application. Isso está incluído no perfil padrão System Administrator. Se a pessoa que faz a configuração não tiver um perfil System Administrator, um administrador do Salesforce precisará conceder a ela um conjunto de permissões que inclua “Customize Application”.

Usuário de integração do Salesforce

Quem são: Um usuário do Salesforce cujas credenciais de conta são usadas pelo plugin do Discourse para fazer chamadas de API para o Salesforce.

O que fazem: Fornecem o nome de usuário que será inserido na configuração salesforce username nas configurações do Discourse Salesforce para facilitar todas as chamadas de API do Discourse para o Salesforce.

O que precisam: Este usuário deve ter:

Permissão	Por que é necessária
API Enabled (API habilitada)	Necessária para qualquer acesso à API do Salesforce
Create, Read, Edit on Lead (Criar, ler, editar em Lead)	Criar e vincular Leads a partir de usuários do Discourse
Create, Read, Edit on Contact (Criar, ler, editar em Contact)	Criar e vincular Contacts a partir de usuários do Discourse
Create, Read, Edit on Case (Criar, ler, editar em Case)	Criar Cases a partir de tópicos do Discourse
Create on Case Comment (Criar em Case Comment)	Sincronizar respostas de tópicos como Case Comments
Create on FeedItem (Chatter) (Criar em FeedItem)	Publicar atividade de tópicos no Chatter

Nota: O usuário de integração do Salesforce pode ser a mesma pessoa que o administrador do Salesforce. No entanto, como boa prática de segurança, recomendamos usar uma conta separada, com permissões mais restritas, para o usuário de integração.

Etapa 1: Gerar um certificado e uma chave privada

Papel: Administrador do Discourse

O Discourse Salesforce usa o Fluxo JWT Bearer para autenticar com o Salesforce. Isso requer um par de chaves RSA: um certificado público que o Salesforce usa para verificar a identidade do plugin e uma chave privada que o Discourse usa para assinar suas solicitações.

1. Siga estas instruções para gerar o par de chaves:
   • server.crt - um certificado público que prova que o Discourse é o aplicativo autorizado
   • server.key - uma chave privada que assina as solicitações de API do Discourse para o Salesforce
2. Envie o arquivo server.crt para seu administrador do Salesforce para que ele possa enviá-lo na Etapa 3.
3. Guarde a server.key para colar nas configurações do Discourse Salesforce na Etapa 5.

Etapa 2: Criar o External Client App no Salesforce

Papel: Administrador do Salesforce

1. Faça login no Salesforce.

2. Clique no ícone de engrenagem () no canto superior direito e selecione Setup (Configuração).

   

3. Na caixa Pesquisa Rápida (Quick Find), procure por External Client App Manager e selecione-o.

   

4. Clique em New External Client App.

   

Nota: Estas etapas usam o External Client App Manager, introduzido no Salesforce Spring '25. Se sua organização estiver em uma versão anterior, a interface pode mostrar App Manager ou Connected Apps em vez disso — as configurações subjacentes são as mesmas.

Etapa 3: Preencher Informações Básicas e Configurações de OAuth

Papel: Administrador do Salesforce

1. Preencha a seção Basic Information (Informações Básicas) (Nome do App e E-mail de Contato são obrigatórios).

   

2. Expanda a seção API (Enable OAuth Settings) e marque a configuração Enable OAuth.

3. Configure as seguintes opções nesta seção:

   • Callback URL: Adicione ambos os links, substituindo <your-discourse-site> pela URL completa do seu site Discourse (ex.: meta.discourse.org):
     https://<your-discourse-site>
https://<your-discourse-site>/auth/salesforce/callback
     Certifique-se de que não haja uma barra final / no final de qualquer URL!
   • Available OAuth Scopes: Adicione todos os três:
     • Access the identify URL service (id, profile, email, address, phone)
     • Manage user data via APIs (api)
     • Perform requests at any time (refresh_token, offline_access)
   • Flow Enablement: Habilite ambos:
     • Enable Client Credentials Flow
     • Enable JWT Bearer Flow — isto é necessário para que o plugin crie Leads, Contacts e Cases

4. Em Certificate Upload, clique em Upload files e faça upload do arquivo server.crt da Etapa 1.

   

5. Clique em Create (Criar).

Etapa 4: Obter a Consumer Key e a Consumer Secret

Papel: Administrador do Salesforce

1. No External Client App recém-criado, clique na aba Settings (Configurações).

2. Role para baixo e expanda OAuth Settings.

3. Clique em Consumer Key and Secret.

   

4. Reinsira suas credenciais de login do Salesforce quando solicitado.

5. Copie a Consumer Key e a Consumer Secret e envie-as para seu administrador do Discourse para a Etapa 5.

Etapa 5: Configurar as definições do plugin do Discourse

Papel: Administrador do Discourse

1. No Discourse, vá para Admin → Plugins → Salesforce → Settings (Configurações).

2. Preencha as seguintes configurações:

   Configuração	Valor
   salesforce enabled	Marque a caixa para habilitar a integração
   salesforce client id	A Consumer Key da Etapa 4
   salesforce client secret	A Consumer Secret da Etapa 4
   salesforce rsa private key	Cole o conteúdo completo do arquivo server.key da Etapa 1
   salesforce username	O nome de usuário do usuário de integração do Salesforce
   salesforce authorization server url	Necessário apenas se você usar um domínio personalizado do Salesforce (ex.: https://mycompany.my.salesforce.com)

   

3. Clique em Save changes (Salvar alterações).

Etapa 6: Autorizar o aplicativo do Discourse no Salesforce

Papel: Usuário de integração do Salesforce

1. Acesse https://<your-discourse-site>/salesforce/admin/authorize, substituindo <your-discourse-site> pela URL completa do seu site Discourse (ex.: meta.discourse.org).
2. Você será redirecionado para o Salesforce e solicitado a autorizar o aplicativo.
3. Faça login no Salesforce e conceda acesso ao aplicativo.

Após concluir esta etapa, você deve estar pronto. Você pode confirmar que está funcionando indo a qualquer perfil de usuário no Discourse — uma opção Sync with Salesforce (Sincronizar com Salesforce) deve aparecer no menu de administrador.

Solução de problemas

Se o plugin não estiver funcionando após a configuração, verifique primeiro o seguinte:

• Verificações de saúde do painel de administração: o plugin apresenta dois alertas em /admin quando há configuração incorreta:

  • SalesforceInvalidCredentials: a Consumer Key, Consumer Secret, chave privada RSA ou nome de usuário está incorreta
  • SalesforceAppNotApproved: a etapa de autorização (Etapa 6) não foi concluída, ou o aplicativo conectado foi rejeitado

• Habilitar registro detalhado (verbose logging): Ative a configuração do site salesforce_auth_verbose_logging para escrever uma saída de autenticação detalhada nos /logs do Discourse. Erros comuns e causas:

Sintoma	Causa provável
“Insufficient privileges” (Privilégios insuficientes) ao criar um Lead ou Contact	O usuário de integração não tem permissões de Criação/Edição nos objetos Lead ou Contact
“Insufficient privileges” (Privilégios insuficientes) ao criar um Case	O usuário de integração não tem permissões de Case ou Case Comment
“Invalid grant” (Concessão inválida) na etapa de autorização	A chave RSA não corresponde ao certificado enviado na Etapa 3, ou o Fluxo JWT Bearer não foi habilitado
Erro “DUPLICATE_VALUE” na criação de Lead ou Contact	Comportamento esperado se o usuário já existir no Salesforce — o plugin lida com isso, mas veja a documentação principal do plugin para detalhes
Posts do Chatter não aparecem	O usuário de integração pode não ter permissões de criação de FeedItem