> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.drimify.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Configuração de Integrações de Webhook na Drimify

## Configurando Integrações no Drimify (Webhooks & Mailers)

As integrações do Drimify permitem que você envie automaticamente dados dos participantes para serviços externos sempre que um utilizador interagir com sua aplicação. Pode conectar-se a uma API Personalizada, HubSpot ou Salesforce — e, para cada integração, pode especificar exatamente quais campos de dados serão transmitidos.

## Começando

| Vá para Minha Conta → Integrações.

Se ainda não houver integrações configuradas, verá a tela de espaço reservado "Ainda sem integrações de webhook" ou "Ainda sem integrações de e-mail". Clique em **+ Adicionar Nova Integração** (disponível tanto no topo direito quanto no centro da página) para abrir o seletor de integrações.

# Integrações De Webhook

## Selecionando um Tipo de Integração

Surgirá uma janela modal intitulada **"Selecionar Integração de Webhook"**. Pode filtrar por categoria usando o menu suspenso (o padrão é **Todos**). As três integrações disponíveis são:

* API Personalizada — para qualquer endpoint da API REST que você controle
* HubSpot — para automação de CRM e Marketing através do HubSpot
* Salesforce — para o CRM da Salesforce

Clique no bloco da integração que deseja configurar.

# Integração com API Personalizada

## Autenticação

Após selecionar **API Personalizada**, o painel **Adicionar Integração** abrirá com os seguintes campos:

* **Nome da Integração**: Um rótulo para sua própria referência (padrão: "Integração de API Personalizada"). Pode renomeá-lo para algo mais descritivo.
* **Endpoint da API**: O URL completo do receptor de webhook (por exemplo: `https://api.example.com/webhook`). Este deve ser um endpoint HTTPS.
* **Método HTTP**:

Selecione o método HTTP usado para enviar a solicitação de webhook para o seu endpoint.
Opções disponíveis:

* **POST** — Recomendado para a maioria dos casos (cria um novo recurso ou envia dados)
* **PUT** — Substitui totalmente um recurso existente
* **PATCH** — Atualiza parcialmente um recurso existente

Escolha o método que corresponde à forma como sua API espera receber dados.

* **Tipo de Autenticação**: Escolha o método de autenticação utilizado pelo seu endpoint.

| Opção | Descrição |
| ---- |
| Nenhum | Nenhum cabeçalho de autenticação é enviado |
| chave api (X-API-KEY) | Envia a chave em um cabeçalho `X-API-KEY` |
| Bearer Token | Envia a chave como `Authorization: Bearer <token>` |
| Autenticação Básica | Envia um cabeçalho `Authorization: Basic` criado a partir do seu Login e Senha |
| Cabeçalho Personalizado | Permite que defina o nome do seu próprio cabeçalho (por exemplo, `X-Custom-Auth`) |

* Quando **Autenticação Básica** é selecionada, dois campos são exibidos: **Login** (nome de utilizador) e **Senha**. Insira-os como estão — o Drimify constrói o cabeçalho `Authorization: Basic` para você automaticamente. Não precisa codificar nada por si mesmo.
* Quando **Cabeçalho Personalizado** é selecionado, um campo adicional **Nome do Cabeçalho Personalizado** aparece onde pode inserir o nome da chave do cabeçalho.
* **Chave da API**: O valor secreto enviado usando o método de autenticação selecionado.
* **Verificar Conexão**: Clique neste botão para testar se o Drimify consegue alcançar seu endpoint com sucesso usando as credenciais fornecidas antes de salvar.

## Obtenção do token de um endpoint de autenticação (pré-chamada)

Algumas APIs requerem que você autentique primeiro: deve chamar um endpoint de autenticação com suas credenciais, receber um token e usar esse token na chamada do webhook real. O Drimify suporta isso automaticamente.

Quando o tipo de autenticação é **Chave da API**, **Bearer Token** ou **Cabeçalho Personalizado**, uma caixa de seleção **"Obter este token de um endpoint de autenticação"** aparece. Quando marcada, o campo de credencial estática é substituído pelas configurações de pré-chamada abaixo (para Cabeçalho Personalizado, o campo do nome do cabeçalho permanece visível — o token obtido é enviado nesse cabeçalho).

O token obtido é colocado de acordo com o seu tipo de autenticação:

* Bearer Token → `Authorization: Bearer <token>`
* chave api → `X-API-KEY: <token>`
* Cabeçalho Personalizado → `<seu nome do cabeçalho>: <token>`### Escolha um dos três métodos

**OAuth2 (client_credentials)** — para servidores padrão OAuth2 (ex: Keycloak).

* Campos: **Token URL**, **Client ID**, **Client Secret**, **Scope** (opcional)
* Drimify envia uma solicitação padrão OAuth2 client_credentials e lê o token de `access_token`. A duração do token é obtida do `expires_in` do servidor.

**Login JSON** — para endpoints de login que aceitam um corpo JSON e retornam um token.

* Campos: **Auth URL**, **Body** (lista de chave/valor), **Token path**
* Drimify envia um `POST` com um corpo JSON construído a partir das suas linhas de chave/valor (ex: linhas `email = a@b.com` e `password = secret` produzem `{"email":"a@b.com","password":"secret"}`).
* **Token path** indica a Drimify onde está o token na resposta JSON, usando notação de ponto — ex: `data.access_token`, ou apenas `token` se estiver no nível superior.

**Personalizado** — para qualquer situação que não se enquadre nos dois métodos acima.

* Campos: **Auth URL**, **Método HTTP** (`POST` ou `GET`), **Headers** (lista de chave/valor), **Body** (lista de chave/valor), **Body encoding** (JSON ou form-urlencoded), **Token path**
* Com o método `GET`, não há corpo de solicitação — passe os parâmetros via Headers ou Auth URL.
* Se adicionar um cabeçalho `Content-Type` por conta própria, ele tem prioridade sobre o implícito pela codificação do corpo.

### Listas de chave/valor (Body e Headers)

Cada linha tem uma **chave**, um **valor**, e uma caixa de seleção **"sensitive"** (marcada por padrão). As linhas podem ser adicionadas e removidas, mas não editadas no local — para alterar uma linha, remova-a e adicione-a novamente. A flag sensível só pode ser definida ao adicionar uma linha. Valores sensíveis são mascarados após salvar e nunca são expostos novamente, no formulário ou em registros.

### Cache do Token e Tentativas

* Tokens OAuth2 são armazenados em cache pela duração indicada pelo `expires_in`.
* Para Login JSON e Personalizado, defina **Validade do Token (minutos)** — o padrão é **60 minutos** se deixado vazio.
* Tokens em cache são mantidos por um máximo de 7 dias.
* Se seu endpoint retornar **401** enquanto um token em cache está em uso, Drimify descarta o token, reautentica e tenta a chamada novamente.
* Se a pré-chamada falhar (erro, timeout, ou nenhum token encontrado no Token path), o webhook **não** é enviado sem autenticação — a entrega falha, é registrada, e é retriada pela fila de entrega conforme habitual.

### Verificar Conexão com uma Pré-Chamada

O botão **Verificar Conexão** suporta plenamente a pré-chamada: primeiro autentica contra o seu endpoint de autorização, depois executa a chamada de teste com o token obtido.

# Integração HubSpot

Após selecionar **HubSpot**, o painel exibe:
* **Nome da Integração**: Padrão: "Integração HubSpot".
* **API Key / Access Token**: Cole aqui o seu Token de Acesso Privado Aplicativo do HubSpot. O HubSpot descontinuou as chaves de API legadas em 2022, portanto deve usar um token de Aplicação Privada gerado a partir da sua conta HubSpot em: **Configurações → Integrações → Aplicativos Privados**
* **Verificar Conexão**: Testa o token contra a API do HubSpot antes de salvar.

# Integração Salesforce

Após selecionar **Salesforce**, o painel exibe:

* **Nome da Integração**: Padrão: "Integração Salesforce".
* **Domínio Salesforce**: A URL da sua instância Salesforce (por exemplo: `seusite.my.salesforce.com`).
* **Consumer Key e Consumer Secret**: Obtidos de uma Aplicação Conectada configurada no Salesforce em: **Configuração → Gerenciador de Aplicativos → Novo Aplicativo Conectado **Drimify usa o fluxo OAuth 2.0 Client Credentials.
* **Nome do Campo de ID Externo:** O nome da API do campo usado para corresponder (upsert) registros — geralmente algo como `Email_External_Id__c` ou um campo personalizado de ID externo no objeto Contacto ou Lead. Este campo deve ser marcado como um **ID Externo** no Salesforce.
* **Fonte do ID Externo**: Um menu suspenso que permite selecionar qual campo de dados Drimify deve ser usado como a chave de correspondência (por exemplo: Email).
* **Verificar Conexão:** Testa a conexão OAuth do Salesforce antes de salvar.## ⚠️ Campos Obrigatórios do Salesforce

O Salesforce exige campos obrigatórios a nível de objeto. Se estiver a atualizar ou inserir Conduz, o Salesforce requer pelo menos:

* `lastName` — obrigatório para a criação de Lead

Se estiver a atualizar ou inserir Contactos, o Salesforce requer:

* `lastName` — obrigatório para a criação de Contacto

Embora o Email não seja obrigatório pelo esquema padrão do Salesforce, é quase sempre necessário como um ID Externo para corresponder e desduplicar adequadamente os registos durante as atualizações. Sem uma correspondência confiável do ID Externo, o Salesforce pode criar registos duplicados ou retornar um erro.

### Melhor Prática
Mapeie sempre pelo menos:

* Apelido
* Email

ao conectar com o Salesforce. A omissão do Apelido fará com que o webhook falhe e o registo não será criado ou atualizado.

# Mapeamento de Campos

Disponível para todos os três tipos de integração, **Mapeamento de Campos** permite especificar exatamente quais campos de dados da Drimify são enviados para a sua integração, e sob quais nomes de chave.
Clique em **+ Adicionar Campo** para adicionar uma linha de mapeamento.

Cada linha consiste em:

* **Campo do Webhook (à esquerda)** — o nome da chave que aparecerá na carga útil de saída (definida por si para corresponder aos requisitos da sua integração)
* **→ Campo Fonte (dropdown à direita)** — o valor fonte para este campo. Pode:
  * Selecionar um **Campo de dados Drimify** (por exemplo, Referência do Aplicação, Email, Pontuação) para enviar um valor dinâmico coletado do participante
  * Selecionar **Valor estático** para enviar um valor fixo e codificado em cada execução do webhook — um campo de texto adicional aparecerá onde deve inserir o valor (por exemplo, `My_Value`). Útil para passar constantes como o nome de um evento, um identificador de fonte, ou uma tag de ambiente.

## Campos Fonte Disponíveis na Drimify

| Nome de Exibição | Chave do Campo |
| ---- |
| Endereço Postal | `address` |
| ID do Aplicação | `appId` |
| Referência do Aplicação | `appReference` |
| Código | `code` |
| Nome da Empresa | `companyName` |
| País de Conexão | `connectionCountry` |
| País | `country` |
| Código do País | `countryCode` |
| Caixa de Seleção Personalizada | `customCheckbox` |
| Formato Personalizado | `customFormat` |
| Campo de Texto Personalizado | `customText` |
| Data | `date` |
| Data de Nascimento | `dob` |
| Data com Fuso Horário | `dateWithTimezone` |
| Email | `email` |
| Nome | `firstName` |
| Gênero | `gender` |
| ID | `id` |
| Idunic | `idunic` |
| Endereço IP | `ipAddress` |
| Apelido | `lastName` |
| Níveis Jogados | `levelsPlayed` |
| Idioma Local | `locale` |
| Opt-In para Newsletter | `optinNewsletter` |
| Número de Telefone | `phoneNumber` |
| Jogados | `played` |
| Código Postal | `cp` |
| Perfil | `profil` |
| UID do Perfil | `profilUid` |
| Referência do Prêmio | `prizeRef` |
| Título do Prêmio | `prizeTitle` |
| UID do Prêmio | `prizeUid` |
| Indicação | `referral` |
| Pontuação | `score` |
| Selecionar Valor | `selectValue` |
| Selecionar Valor 2 | `selectValue2` |
| ID da Sessão | `sessionId` |
| Tempo Gasto | `timeTaken` |
| Cidade | `town` |
| Atualizado Em | `updatedAt` |
| Carimbo de Tempo Atualizado | `updatedAtTimeStamp` |
| Usuário | `username` |
| Site | `website` |

Pode adicionar quantos mapeamentos forem necessários.
Para remover um mapeamento, clique no ícone da lixeira à direita da linha.

# Disponível em Espaços de Trabalho

Na parte inferior do formulário de integração, a seção **Disponível em Espaços de Trabalho** permite usar o alternador ao lado de cada espaço de trabalho para controlar qual espaço de trabalho pode usar a integração.
Clique em **Selecionar Tudo** para ativar a integração para todos os espaços de trabalho de uma só vez.

# Salvar e Gerir Integrações

Uma vez que todos os campos estejam preenchidos, clique em **Salvar Alterações** para criar a integração. A integração aparecerá então na lista principal de Integrações. Pode editar ou excluir integrações existentes desta lista a qualquer momento. Clique em **Cancelar** para descartar alterações não salvas.

---

# Integrações de E-mail

As integrações de e-mail permitem-lhe enviar e-mails transacionais (por exemplo, confirmações, resultados ou acompanhamentos) diretamente das suas experiências Drimify usando o seu provedor de e-mail preferido.### Adicionar Integração de Remetente

1. Vá para **Integrações → Integrações de Remetente**
2. Clique em **Adicionar Integração de Remetente**
3. Selecione o seu provedor:
* Amazon SES
* Brevo
* Drimify
* Mailgun
* Mailjet
* Mandrill
* SendGrid
* Tipimail
* SMTP Personalizado

### Configurar a sua Integração de Remetente

#### Configurações Gerais

Todos os provedores têm as seguintes configurações gerais:

* **Nome da Integração** – Nome interno para identificar a sua integração
* **Nome do Remetente** – Nome exibido como remetente do e-mail
* **E-mail do Remetente** – Endereço de e-mail usado para enviar e-mails (não aplicável ao Drimify — veja abaixo)
* **E-mail BCC** *(opcional)* – Adicionar um endereço de e-mail para receber uma cópia de todos os e-mails enviados

#### Autenticação

Cada provedor requer credenciais específicas. Consulte a seção de configurações específicas do provedor abaixo para mais detalhes.

#### Testar a Sua Conexão

Após inserir as suas credenciais, clique em **Enviar E-mail de Teste** para verificar se a sua integração está a funcionar corretamente. Uma confirmação "E-mail de teste enviado com sucesso" aparecerá se a conexão for válida.

||| ⚠️ A integração deve passar no teste de conexão antes de poder ser usada. Se o teste for ignorado ou falhar, o remetente não estará disponível para uso nas suas experiências.

#### Campos de Parâmetros do Modelo

Mapeie os campos de dados do Drimify para as variáveis do modelo do seu provedor de e-mail. Esta seção está disponível para provedores que suportam modelos de e-mail dinâmicos: **Brevo, Mailgun, Mailjet, Mandrill, SendGrid e Tipimail**.

* **Nome do Parâmetro** – O nome da variável esperado no seu modelo de e-mail
* **Campo** – Os dados correspondentes do Drimify (por exemplo, Nome, Email, Pontuação, etc.)

Clique em **Adicionar Campo** para criar mapeamentos adicionais.

| 💡 Isto permite-lhe personalizar os e-mails dinamicamente utilizando os dados recolhidos dos jogadores na sua experiência.

#### Disponível em Espaços de Trabalho
Selecione em quais espaços de trabalho esta integração de remetente pode ser usada.### Configuração Específica do Provedor

#### Amazon SES

O que você precisa:

* Um utilizador AWS IAM com permissões `ses:SendEmail`
* Chave de Acesso API e Chave Privada API (do AWS IAM)
* Sua região AWS (por exemplo, `eu-west-1`, `us-east-1`)
* Token de Sessão *(apenas se estiver a usar credenciais temporárias/STS)*
* Um domínio ou e-mail do remetente verificado no Amazon SES

Passos:

1. No AWS IAM, criar um utilizador com permissões de envio SES e gerar um par de chave de acesso
2. No Drimify, insira sua **API Access Key**, **API Private Key** e **Region**
3. Se estiver a usar credenciais temporárias, insira também o **Session Token**
4. Certifique-se de que seu e-mail do remetente ou domínio está verificado no Amazon SES
5. Clique em **Enviar Email de Teste** para validar a conexão
6. Salve sua integração

#### Brevo

O que você precisa:

* Uma chave api Brevo

Passos:

1. Na sua conta Brevo, gere uma chave api em **Configurações → API Keys**
2. Cole-a no campo **API Key** no Drimify
3. Clique em **Enviar Email de Teste** para validar a conexão
4. Salve sua integração

#### Drimify

Não requer autenticação. E-mails são enviados através da infraestrutura interna de email do Drimify ([notification@digitaservice.com](mailto:notification@digitaservice.com)).
O que você precisa:

* Um nome do remetente
* Um endereço de e-mail de resposta (por exemplo, [contact@yourcompany.com](mailto:contact@yourcompany.com))
* Opcionalmente, um endereço de e-mail BCC

Passos:

1. Selecione **Drimify** como seu provedor
2. Insira seu **Sender Name** e **Reply-To Email**
3. Opcionalmente, adicione um **BCC Email**
4. Selecione os espaços de trabalho que devem usar esta integração e salve

| 💡 Use esta opção se não tiver um provedor de e-mail de terceiros ou quiser começar rapidamente sem nenhuma configuração externa.

#### Mailgun

O que você precisa:

* Uma chave api Mailgun
* Seu domínio de envio registrado no Mailgun
* Sua região API (US ou UE)

Passos:

1. Na sua conta Mailgun, recupere sua chave de api e domínio de envio
2. No Drimify, insira sua **API Key**, **API Domain**, e **API Region**
3. Clique em **Enviar Email de Teste** para validar a conexão
4. Salve sua integração

#### Mailjet

O que você precisa:

* Uma Chave de Acesso API Mailjet e Chave Privada API

Passos:

1. Na sua conta Mailjet, vá para **Configurações de Conta → REST API → gerenciamento de chave api**
2. Copie sua **API Access Key** e **API Private Key**
3. Insira ambas no Drimify
4. Clique em **Enviar Email de Teste** para validar a conexão
5. Salve sua integração

#### Mandrill

O que você precisa:

* Uma chave api Mandrill *(Mandrill é um complemento de email transacional do Mailchimp)*

Passos:

1. Na sua conta Mandrill, vá para **Configurações → API Keys** e gere uma chave
2. Cole a **API Key** no Drimify
3. Clique em **Enviar Email de Teste** para validar a conexão
4. Salve sua integração

#### SendGrid

O que você precisa:

* Uma chave api SendGrid com permissões para enviar emails

Passos:

1. Na sua conta SendGrid, vá para **Configurações → API Keys** e crie uma chave com permissões **Mail Send**
2. Cole a **API Key** no Drimify
3. Clique em **Enviar Email de Teste** para validar a conexão
4. Salve sua integração

#### Tipimail

O que você precisa:

* Um Utilizador API Tipimail e chave api *(Tipimail é o serviço de email transacional da Sarbacane)*

Passos:

1. Na sua conta Tipimail, vá para **Configurações → SMTP & APIs** e recupere seu **API User** e **API Key**
2. Insira ambos no Drimify
3. Clique em **Enviar Email de Teste** para validar a conexão
4. Salve sua integração

| 💡 Tipimail suporta modelos de email dinâmicos: refira-se ao seu modelo pelo nome e use a seção Campos De Parâmetros Do Modelo para mapear dados do Drimify para as variáveis do seu modelo.

#### SMTP Personalizado

O que você precisa:

* O nome do host do seu servidor SMTP
* Porta SMTP (normalmente `587` para TLS, `465` para SSL)
* Login SMTP (geralmente seu endereço de e-mail)
* Senha SMTP

Passos:

1. Recupere suas credenciais SMTP do seu provedor de hospedagem de e-mail ou configuração do servidor
2. No Drimify, insira seu **Host**, **Port**, **Login**, e **Password**
3. Clique em **Enviar Email de Teste** para validar a conexão
4. Salve sua integração