--- title: "Conector Freshdesk" description: "Guia completo de integração do Freshdesk para sincronizar tickets de suporte, contatos e dados de agentes com o Brevo através do Tajo." url: https://tajo.io/pt/docs/connectors/support/freshdesk/ markdown: https://tajo.io/pt/docs/connectors/support/freshdesk.md lang: pt-BR robots: noindex --- Solicite acesso antecipado Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo. # Conector Freshdesk Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje. | Campo de origem | Campo de destino | Valor de exemplo | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Conecte o Freshdesk ao Brevo através do Tajo para unificar dados de suporte e marketing. Sincronize tickets de suporte ao cliente, perfis de contato e pontuações de satisfação para alimentar comunicações segmentadas com base em interações de suporte. ## Visão geral | Propriedade | Valor | | --- | --- | | **Plataforma** | Freshdesk | | **Categoria** | Suporte | | **Complexidade de configuração** | Fácil | | **Integração oficial** | Não | | **Dados sincronizados** | Tickets, Contatos, Agentes, Empresas | | **Skills disponíveis** | 6 | ## Recursos - **Sincronização de contatos** - Sincronização bidirecional de contatos do Freshdesk para listas de contatos do Brevo - **Rastreamento de eventos de ticket** - Encaminhe eventos de criação, atualização e resolução de tickets para o Brevo - **Sincronização de CSAT** - Sincronize pontuações de satisfação do cliente como atributos de contato do Brevo - **Sincronização de empresas** - Mapeie empresas do Freshdesk para segmentação de contatos do Brevo - **Dados de agente** - Rastreie atribuições de agentes para automação de workflows internos - **Campos personalizados** - Mapeie campos personalizados de tickets e contatos do Freshdesk para atributos do Brevo ## Pré-requisitos Antes de começar, certifique-se de ter: 1. Uma conta Freshdesk com acesso de admin 2. Sua chave de API do Freshdesk (encontrada em Profile Settings) 3. Seu domínio do Freshdesk (por exemplo, `suaempresa.freshdesk.com`) 4. Uma conta Brevo com acesso à API 5. Uma conta Tajo com credenciais de API ## Autenticação ### Autenticação por chave API O Freshdesk usa autenticação por chave API via HTTP Basic Auth. A chave API é usada como nome de usuário com qualquer string (normalmente `X`) como senha. ```bash curl -u "YOUR_API_KEY:X" \ https://yourcompany.freshdesk.com/api/v2/tickets ``` Ou usando codificação Base64 no cabeçalho Authorization: ```bash curl https://yourcompany.freshdesk.com/api/v2/tickets \ -H "Authorization: Basic BASE64_ENCODED_API_KEY:X" \ -H "Content-Type: application/json" ``` ### Localizar sua chave API 1. Faça login em sua conta Freshdesk 2. Clique na sua foto de perfil no canto superior direito 3. Vá para **Profile Settings** 4. Sua chave API é exibida no lado direito ## Configuração ### Configuração básica ```yaml connectors: freshdesk: enabled: true domain: "yourcompany.freshdesk.com" api_key: "your-freshdesk-api-key" # Data sync options sync: contacts: true tickets: true companies: true satisfaction_ratings: true # Brevo list assignment lists: all_support_contacts: 30 open_tickets: 31 resolved_tickets: 32 ``` ### Mapeamento de campos de contato Mapeie campos de contato do Freshdesk para atributos do Brevo: ```yaml contact_mapping: email: email name: FULLNAME phone: SMS company_id: COMPANY job_title: JOB_TITLE twitter_id: TWITTER language: LANGUAGE time_zone: TIMEZONE # Support metrics total_tickets: TICKET_COUNT open_tickets: OPEN_TICKETS avg_csat: CSAT_SCORE last_ticket_date: LAST_SUPPORT_DATE # Custom fields custom_fields.account_type: ACCOUNT_TYPE custom_fields.subscription_tier: PLAN ``` ### Mapeamento de eventos de ticket Mapeie eventos de ticket do Freshdesk para gatilhos de automação do Brevo: ```yaml ticket_events: ticket_created: "support_ticket_created" ticket_updated: "support_ticket_updated" ticket_resolved: "support_ticket_resolved" ticket_closed: "support_ticket_closed" ticket_reopened: "support_ticket_reopened" satisfaction_rated: "csat_submitted" note_added: "support_note_added" ``` ## Endpoints da API | Método | Endpoint | Descrição | | --- | --- | --- | | `GET` | `/api/v2/tickets` | Listar todos os tickets | | `POST` | `/api/v2/tickets` | Criar um ticket | | `GET` | `/api/v2/tickets/{id}` | Obter um ticket específico | | `PUT` | `/api/v2/tickets/{id}` | Atualizar um ticket | | `DELETE` | `/api/v2/tickets/{id}` | Excluir um ticket | | `GET` | `/api/v2/contacts` | Listar todos os contatos | | `POST` | `/api/v2/contacts` | Criar um contato | | `PUT` | `/api/v2/contacts/{id}` | Atualizar um contato | | `GET` | `/api/v2/companies` | Listar todas as empresas | | `GET` | `/api/v2/agents` | Listar todos os agentes | | `GET` | `/api/v2/surveys/satisfaction_ratings` | Listar avaliações CSAT | | `GET` | `/api/v2/search/tickets?query=` | Buscar tickets | ## Exemplos de código ### Inicializar o conector Freshdesk ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); // Connect Freshdesk account await tajo.connectors.connect('freshdesk', { domain: 'yourcompany.freshdesk.com', apiKey: process.env.FRESHDESK_API_KEY }); ``` ### Sincronizar contatos para o Brevo ```javascript // Fetch Freshdesk contacts and sync to Brevo const response = await fetch( 'https://yourcompany.freshdesk.com/api/v2/contacts?page=1&per_page=100', { headers: { 'Authorization': 'Basic ' + btoa(`${API_KEY}:X`), 'Content-Type': 'application/json' } } ); const contacts = await response.json(); // Each contact: // { // "id": 12345, // "name": "Jane Kim", // "email": "jane@example.com", // "phone": "+15551234567", // "company_id": 678, // "job_title": "Product Manager", // "created_at": "2024-01-15T10:30:00Z" // } ``` ### Rastrear eventos de ticket ```javascript // Set up Freshdesk webhook to forward ticket events // Configure in Freshdesk Admin > Automations > Webhook // Webhook handler app.post('/webhooks/freshdesk', async (req, res) => { const { ticket, event_type } = req.body; await tajo.connectors.handleWebhook('freshdesk', { topic: event_type, payload: { ticketId: ticket.id, subject: ticket.subject, status: ticket.status, priority: ticket.priority, requesterEmail: ticket.requester.email, createdAt: ticket.created_at } }); res.status(200).send('OK'); }); ``` ### Buscar tickets por cliente ```javascript // Search for all tickets from a specific customer const query = encodeURIComponent('"email:jane@example.com"'); const response = await fetch( `https://yourcompany.freshdesk.com/api/v2/search/tickets?query=${query}`, { headers: { 'Authorization': 'Basic ' + btoa(`${API_KEY}:X`) } } ); const { results, total } = await response.json(); ``` ## Limites de taxa | Plano | Limite | Detalhes | | --- | --- | --- | | **Sprout** | 50 requisições/min | Plano gratuito | | **Blossom** | 200 requisições/min | Plano starter | | **Garden** | 400 requisições/min | Plano growth | | **Estate** | 700 requisições/min | Plano pro | | **Forest** | 1.000 requisições/min | Plano enterprise | Limites adicionais: | Recurso | Limite | | --- | --- | | **Endpoints de listagem** | 30 páginas por consulta | | **Por página** | 100 registros no máximo | | **API de busca** | 2 requisições/seg | | **Operações em lote** | 10 registros/requisição | Cabeçalhos de limite de taxa O Freshdesk retorna informações de limite de taxa nos cabeçalhos de resposta. Monitore `X-RateLimit-Remaining` e implemente backoff quando se aproximar dos limites. ## Solução de problemas | Problema | Causa | Solução | | --- | --- | --- | | `401 Unauthorized` | Chave API inválida | Verifique a chave API em Freshdesk Profile Settings | | `403 Forbidden` | Permissões insuficientes | Certifique-se de que a chave API pertence a uma conta de admin | | Contatos não sincronizam | Campo de e-mail ausente | Contatos do Freshdesk exigem um endereço de e-mail | | Tickets não aparecem | Domínio incorreto | Verifique se a URL do domínio do Freshdesk está correta | | Busca retornando vazio | Erro de sintaxe na consulta | Use a sintaxe de consulta de busca do Freshdesk com aspas duplas | | `429 Too Many Requests` | Limite de taxa excedido | Implemente limitação de taxa com base no nível do plano | | Campos personalizados ausentes | Campo não habilitado | Certifique-se de que os campos personalizados estão habilitados no admin do Freshdesk | ## Melhores práticas 1. **Use webhooks para sincronização em tempo real** - Configure Freshdesk Automations para disparar webhooks em eventos de ticket 2. **Sincronize pontuações CSAT** - Rastreie avaliações de satisfação do cliente como atributos do Brevo para segmentação 3. **Mapeie status de ticket para listas** - Mova automaticamente contatos entre listas do Brevo com base no status do ticket 4. **Rastreie métricas de suporte** - Sincronize contagem de tickets, tempo médio de resposta e taxa de resolução por contato 5. **Use a API de busca com moderação** - A API de busca tem limites de taxa mais rigorosos; armazene resultados em cache quando possível 6. **Paginação para grandes exportações** - Use paginação com parâmetros `page` e `per_page` para a sincronização inicial ## Segurança - **Autenticação por chave API** - HTTP Basic Auth simples com chave API - **Somente HTTPS** - Toda comunicação com a API requer criptografia TLS - **Whitelisting de IP** - Disponível nos planos Estate e Forest - **Acesso baseado em função** - Permissões de chave API vinculadas à função do agente - **SOC 2 Type II** - O Freshdesk é certificado SOC 2 Type II - **Conformidade com GDPR** - Suporta solicitações de exportação e exclusão de dados ## Recursos relacionados - [Conector Brevo](https://tajo.io/pt/docs/connectors/marketing/brevo) - [Skill de sincronização de clientes](https://tajo.io/pt/docs/skills/data-sync/customer-sync) - [Conector Shopify](https://tajo.io/pt/docs/connectors/ecommerce/shopify) - [API de contatos do Brevo](https://tajo.io/pt/docs/contact-management)