> For the complete documentation index, see [llms.txt](https://multiagents.gitbook.io/multiagents-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiagents.gitbook.io/multiagents-docs/documentacao-de-tools/readme/freshsales-v2.md).

# FreshSales V2

Este guia explica como conectar o **Freshsales** ao Multiagents para sincronizar automaticamente leads, oportunidades e contatos entre os dois sistemas.

***

### O que a integração faz

Quando configurada, a integração sincroniza automaticamente:

* **Novos leads** criados no Multiagents → cria deal no Freshsales
* **Mudança de estágio** → move o deal para o stage correspondente
* **Lead ganho/perdido** → atualiza status do deal
* **Notas adicionadas** → cria nota vinculada ao deal
* **Contatos adicionados** → cria/atualiza contato no Freshsales
* **Lembretes** → cria task no Freshsales

***

### Passo 1 — Identificar seu tipo de conta

Freshsales existe em duas versões:

| Versão                     | URL da conta                   | Status              |
| -------------------------- | ------------------------------ | ------------------- |
| **Freshworks CRM (Suite)** | `sua-empresa.myfreshworks.com` | Atual (recomendado) |
| **Freshsales Classic**     | `sua-empresa.freshsales.io`    | Legado              |

A integração suporta **ambas**. Verifique a URL no navegador ao acessar seu Freshsales.

O **subdomínio** é a parte antes do domínio. Exemplo: se sua URL é `acme.myfreshworks.com`, o subdomínio é `acme`.

***

### Passo 2 — Obter a API Key

1. Acesse seu Freshsales e faça login
2. Clique no seu **avatar** (canto superior direito)
3. Vá em **"Profile Settings"** (ou "Configurações do Perfil")
4. Clique na aba **"API Settings"**
5. Copie a **API Key** exibida

**URLs diretas:**

* Freshworks CRM: `https://sua-empresa.myfreshworks.com/crm/sales/personal-settings/api-settings`
* Freshsales Classic: `https://sua-empresa.freshsales.io/personal-settings/api-settings`

> **Importante:** A API Key herda as permissões do usuário. Use a key de um **Admin** para acesso completo.

***

### Passo 3 — Criar a Credencial no Multiagents

1. No painel do Multiagents, acesse **Configurações > Integrações**
2. Clique em **"+ Nova Credencial"**
3. Na categoria **CRM**, selecione **"Freshsales"**
4. Preencha:
   * **API Key:** a key copiada no passo anterior
   * **Subdomínio:** o subdomínio da sua conta (ex: `acme`)
5. Clique em **"Testar Conexão"** — deve confirmar a conexão
6. Dê um nome à credencial (ex: "Freshsales - Equipe Vendas")
7. Clique em **"Salvar"**

***

### Passo 4 — Adicionar a Ferramenta ao Trabalho

1. Acesse o **Trabalho** onde deseja ativar a integração
2. Na lista de ferramentas, encontre **"Freshsales"** na seção CRM
3. Clique no botão **"+"** para instalar

***

### Passo 5 — Configurar Pipeline e Mapeamento de Estágios

Após instalar a ferramenta, clique no ícone de **engrenagem** para configurar:

#### 5.1. Selecionar Credencial

* Escolha a credencial criada no Passo 3

#### 5.2. Selecionar Pipeline

* Um dropdown exibirá os pipelines disponíveis no Freshsales
* Selecione o pipeline que deseja sincronizar com este Trabalho

#### 5.3. Mapear Estágios

Após selecionar o pipeline, o mapeamento de estágios aparece automaticamente:

* **Lado esquerdo:** estágios do Trabalho no Multiagents
* **Lado direito:** dropdown com os stages do pipeline no Freshsales
* Para cada estágio, selecione o stage correspondente no Freshsales
* Estágios sem mapeamento **não serão sincronizados**

**Exemplo de mapeamento:**

| Estágio Multiagents | Stage Freshsales |
| ------------------- | ---------------- |
| Novo Lead           | New              |
| Qualificação        | Qualification    |
| Proposta            | Proposal         |
| Negociação          | Negotiation      |
| Fechamento          | Closing          |

#### 5.4. Salvar

* Clique em **"Salvar e Fechar"**
* A integração está ativa!

***

### Passo 6 — Configurar Sync Bidirecional (Freshsales → Multiagents)

Para que mudanças feitas **no Freshsales** sejam refletidas automaticamente no Multiagents, é necessário configurar webhooks via **Workflows** no Freshsales.

#### 6.1. Obter a URL do Webhook

No Multiagents, na configuração da ferramenta mostra a url para usar nno Freshsales.

<figure><img src="https://3744957929-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsOmzWUgDGQvQAevhZo3I%2Fuploads%2FAcX37AX175jO4hVNWanj%2Fimage.png?alt=media&amp;token=1b8cd6c9-6f18-479c-8fdb-a31800d55798" alt=""><figcaption></figcaption></figure>

> 6.2 Configurar URL do webhook no Freshsales
>
> 1. No Freshsales, clique no ícone de **engrenagem** (Settings, canto superior direito)
>
> 2. Vá em **"Admin Settings"**
>
> 3. Na seção **"Workflows & Automations"**, clique em **"Workflows"**
>
> 4. Clique em **"+ Create Workflow"**
>
> 5. Configure:
>    * **Name:** `Multiagents Sync - Deal Updated`
>    * **Entity:** **Deal**
>    * **When:** selecione **"Deal is updated"**
>    * **Conditions:** deixe vazio (para capturar todas as atualizações)
>
> 6. Em **Actions**, clique em **"+ Add Action"**
>
> 7. Selecione **"Trigger Webhook"**
>
> 8. Configure o webhook

***

### Como funciona na prática

#### Cenário 1: Novo lead no Multiagents → Freshsales

1. Um novo lead entra no Multiagents (via WhatsApp, widget, etc.)
2. O agente IA qualifica o lead e move para um estágio
3. A integração automaticamente:
   * Busca/cria a **conta (Account)** no Freshsales (por nome)
   * Busca/cria o **contato** no Freshsales (por email via upsert)
   * Cria o **deal** no pipeline selecionado, no stage mapeado
4. O deal aparece no Freshsales vinculado ao contato e conta

#### Cenário 2: Mudança de estágio (Multiagents → Freshsales)

1. O agente IA ou um humano move o lead de estágio no Multiagents
2. A integração move o deal para o stage correspondente no Freshsales

#### Cenário 3: Mudança de estágio (Freshsales → Multiagents)

1. Um vendedor move o deal de estágio no Freshsales
2. O webhook do workflow dispara para o Multiagents
3. O handler faz o mapeamento reverso (Freshsales stage → estágio interno)
4. O lead no Multiagents é atualizado automaticamente

#### Cenário 4: Lead ganho

1. O lead é marcado como "ganho" no Multiagents
2. O deal no Freshsales é movido para o stage "Won"
3. Uma nota é adicionada com o motivo e valor

#### Cenário 5: Lead ganho no Freshsales

1. O vendedor move o deal para "Won" no Freshsales
2. O webhook notifica o Multiagents
3. O lead é marcado como ganho no Multiagents

***

### Resolução de Problemas

#### "Testar Conexão" falha

* Verifique se a API Key está correta (copie novamente do Freshsales)
* Verifique se o subdomínio está correto (sem `https://`, sem `.myfreshworks.com`)
* Confirme que o usuário da API Key tem permissão de Admin

#### Pipelines não aparecem no dropdown

* Verifique se existem pipelines de deals criados no Freshsales
* O plano Free tem limite de 50 req/hora — aguarde e tente novamente

#### Erro 403

* O endpoint pode não estar disponível no seu plano
* Verifique as permissões do usuário em **Settings > Users and permissions**

#### Deal não foi criado no Freshsales

* Verifique se o lead tem informações de contato (email é obrigatório para upsert)
* O campo `amount` é obrigatório nos deals do Freshsales — verificar logs

***

### Rate Limits por Plano

| Plano      | Limite         |
| ---------- | -------------- |
| Free       | 50 req/hora    |
| Growth     | 1.000 req/hora |
| Pro        | 3.000 req/hora |
| Enterprise | 5.000 req/hora |

***

### Informações Técnicas

| Item         | Valor                                                 |
| ------------ | ----------------------------------------------------- |
| API Base URL | `https://{subdomain}.myfreshworks.com/crm/sales/api/` |
| Autenticação | Header `Authorization: Token token=<API_KEY>`         |
| IDs          | Numéricos                                             |
| Companies    | Endpoint `/sales_accounts` (não `/accounts`)          |
| Notes        | Polimórfico: `targetable_type` + `targetable_id`      |
| Tasks        | Requer `owner_id` (ID do usuário responsável)         |
| Webhooks     | Configurados via Workflows (não via API)              |
