Um guia prático para a API de tickets do Freshdesk com exemplos (2025)

Então, está a usar o Freshdesk. É um helpdesk fantástico, não há como negar. Mas se estiver apenas a usar o que vem de origem, pode estar a perder o seu verdadeiro poder. A magia começa quando coloca o Freshdesk a comunicar com as suas outras ferramentas, automatizando as partes maçadoras do seu dia.

Tradicionalmente, a chave para desbloquear tudo isto tem sido a API do Freshdesk. É o que permite que os seus programadores criem relatórios personalizados, acionem ações a partir de outras aplicações e, de um modo geral, façam com que os seus dados de suporte fluam pelo resto da sua empresa.

Este guia irá dar-lhe uma visão direta da API de tickets do Freshdesk. Vamos percorrer alguns exemplos comuns da API de tickets do Freshdesk e analisar algumas formas diferentes de realizar a automação, quer tenha uma equipa de programadores ou prefira tratar do assunto por si mesmo.

Compreender a API de tickets do Freshdesk

Pense numa API (Application Programming Interface) como um mensageiro privado entre o seu software. É um conjunto de regras que permite que diferentes aplicações troquem informações e digam umas às outras o que fazer. A API do Freshdesk é uma API REST, um padrão comum para estes mensageiros. Permite-lhe gerir os dados do seu helpdesk de forma programática, o que significa que pode escrever código para criar, ler, atualizar e eliminar tickets.

Antes de começar, aqui estão algumas coisas que precisa de entender:

• Autenticação: Não pode simplesmente permitir que qualquer aplicação aceda aos dados dos seus clientes. Cada pedido enviado à API precisa de provar que tem permissão. Faz isto com uma chave de API, que pode encontrar nas definições do seu perfil do Freshdesk. É basicamente uma palavra-passe secreta para as suas aplicações.

• Limites de Taxa (Rate Limits): O Freshdesk está atento a quantos pedidos está a fazer para evitar sobrecarregar os seus servidores. Eles limitam o número de chamadas de API que pode fazer por minuto, e este número depende do seu plano de preços do Freshdesk. Se estiver a construir uma integração que lida com muitos tickets, pode esbarrar nestes limites, o que pode fazer com que a sua automação pause.

• Recursos para Programadores: Usar a API não é exatamente uma tarefa de apontar e clicar. Geralmente, requer alguém que saiba o que está a fazer com uma linguagem de programação (como Python) para escrever, alojar e cuidar do código que faz tudo funcionar.

Embora a API seja um cavalo de batalha para soluções personalizadas, muitas equipas apenas querem a automação sem o projeto de engenharia que a acompanha. É aqui que as plataformas no-code estão a mudar o jogo, oferecendo um caminho muito mais simples para o mesmo destino.

Exemplos comuns da API de tickets do Freshdesk

Vamos à parte prática. Aqui estão algumas das coisas mais comuns que as pessoas fazem com a API de tickets do Freshdesk. Usaremos Python para os trechos de código, uma vez que é uma escolha popular para este tipo de tarefa.

Exemplo 1: Obter uma lista de tickets

Porque faria isto: Talvez os relatórios integrados do Freshdesk não sejam exatamente o que precisa. Pode querer extrair dados de tickets para um painel de controlo personalizado para acompanhar métricas muito específicas, analisar tendências ou alimentar essa informação numa ferramenta de business intelligence.

Para fazer isto, usaria o endpoint GET /api/v2/tickets. Um pequeno detalhe é que a API fornece os dados em "páginas". Não pode simplesmente obter todos os tickets de uma vez. Tem de os pedir página por página, como se estivesse a folhear um livro. Também pode adicionar parâmetros como updated_since para obter apenas os tickets que foram alterados recentemente.

import requests  

import json  

# O seu domínio do Freshdesk e chave de API  

domain = "o-seu-dominio"  

api_key = "A_SUA_CHAVE_DE_API"  

password = "X" # A palavra-passe pode ser qualquer coisa ao usar uma chave de API  

# Começar com a primeira página  

page = 1  

while True:  

    url = f"https://{domain}.freshdesk.com/api/v2/tickets?page={page}&per_page=100"  

    response = requests.get(url, auth=(api_key, password))  

    if response.status_code == 200:  

        tickets = response.json()  

        if not tickets:  

            # Não há mais tickets para obter  

            break  

        print(f"--- Página {page} ---")  

        for ticket in tickets:  

            print(f"Ticket #{ticket['id']}: {ticket['subject']}")  

        page += 1  

    else:  

        print(f"Falha ao obter tickets. Código de estado: {response.status_code}")  

        break  

Um painel de análise do Freshdesk, que pode ser preenchido com dados de exemplos da API de tickets do Freshdesk.

Uma abordagem diferente: Construir e manter um pipeline de relatórios personalizado é um projeto sério. Uma plataforma de IA integrada como o eesel AI oferece-lhe relatórios avançados e acionáveis desde o primeiro dia. Não se limita a mostrar gráficos; na verdade, analisa os seus tickets para encontrar lacunas na sua base de conhecimento e aponta as melhores oportunidades de automação, tudo sem que tenha de escrever uma única linha de código.

Exemplo 2: Criar um novo ticket

Porque faria isto: Quer criar automaticamente um ticket no Freshdesk quando algo importante acontece noutra aplicação. Por exemplo, um alerta crítico da sua ferramenta de monitorização de servidores pode criar um ticket de alta prioridade para a sua equipa de engenharia, ou o envio de um formulário no seu site pode ir diretamente para a fila da sua equipa de vendas.

Para isto, usaria o endpoint POST /api/v2/tickets. Só precisa de enviar um objeto JSON com todos os detalhes do ticket, como o e-mail do cliente, assunto, descrição, prioridade e estado.

import requests  

import json  

domain = "o-seu-dominio"  

api_key = "A_SUA_CHAVE_DE_API"  

password = "X"  

url = f"https://{domain}.freshdesk.com/api/v2/tickets"  

headers = { "Content-Type": "application/json" }  

ticket_data = {  

    "email": "cliente@example.com",  

    "subject": "Envio de formulário do site: Pedido de Demonstração",  

    "description": "Um novo lead solicitou uma demonstração através do site.",  

    "status": 2,  # Aberto  

    "priority": 3, # Alta  

    "group_id": 12345 # ID do seu grupo de Vendas  

}  

response = requests.post(url, auth=(api_key, password), headers=headers, data=json.dumps(ticket_data))  

if response.status_code == 201:  

    print("Ticket criado com sucesso!")  

    print(response.json())  

else:  

    print(f"Falha ao criar ticket. Estado: {response.status_code}, Resposta: {response.text}")  

O painel de controlo de tickets do Freshdesk onde apareceria um novo ticket, criado através de um dos exemplos da API de tickets do Freshdesk.

Uma abordagem diferente: Criar o ticket é a parte fácil. O verdadeiro trabalho é descobrir o que acontece a seguir. Codificar manualmente regras para encaminhamento, etiquetagem e resposta pode tornar-se complicado rapidamente. A Triagem por IA do eesel AI trata de toda essa "higiene de tickets" por si. Lê o novo ticket e pode definir instantaneamente a prioridade correta, atribuí-lo à equipa certa, adicionar etiquetas relevantes ou até mesmo detetar e fechar spam.

Exemplo 3: Atualizar um ticket existente

Porque faria isto: Precisa de alterar automaticamente o estado de um ticket ou adicionar informações com base num evento noutro sistema. Por exemplo, quando uma encomenda é enviada da sua loja Shopify, pode adicionar automaticamente uma nota privada com as informações de rastreamento ao ticket do cliente e alterar o seu estado para "Pendente".

Aqui, usaria o endpoint PUT /api/v2/tickets/[id], onde [id] é apenas o número de ID do ticket que pretende atualizar. Os dados que envia só precisam de incluir os campos que está a alterar.

import requests  

import json  

domain = "o-seu-dominio"  

api_key = "A_SUA_CHAVE_DE_API"  

password = "X"  

ticket_id = 123 # O ID do ticket a ser atualizado  

url = f"https://{domain}.freshdesk.com/api/v2/tickets/{ticket_id}"  

headers = { "Content-Type": "application/json" }  

update_data = {  

    "status": 3, # Pendente  

    "priority": 1 # Baixa  

}  

response = requests.put(url, auth=(api_key, password), headers=headers, data=json.dumps(update_data))  

if response.status_code == 200:  

    print(f"Ticket #{ticket_id} atualizado com sucesso!")  

else:  

    print(f"Falha ao atualizar ticket. Estado: {response.status_code}, Resposta: {response.text}")  

Uma abordagem diferente: Isto é ótimo para atualizações simples, mas e se precisar de mais? E se quisesse verificar o estado da encomenda em tempo real, adicionar uma resposta pública ao cliente com o número de rastreamento e depois resolver o ticket? Isso é um fluxo de trabalho de vários passos que se torna complicado de programar. Com um Agente de IA do eesel AI, pode construir toda essa sequência usando um editor de prompts simples. A IA pode realizar ações, contactar outros sistemas para obter dados em tempo real e tratar de toda a conversação.

Automatizar fluxos de trabalho com exemplos da API de tickets do Freshdesk

Embora chamar a API diretamente seja útil, a verdadeira automação consiste em sistemas que reagem a eventos à medida que acontecem, sem que precise de executar manualmente um script. É aqui que os webhooks geralmente entram em cena.

Usar automações e webhooks do Freshdesk para fluxos de trabalho avançados

O Freshdesk possui regras de automação integradas que são ótimas para tarefas simples. Para coisas mais complexas, pode usar webhooks. Um webhook é apenas uma mensagem automática que o Freshdesk envia para outro sistema sempre que algo específico acontece, como a mudança de estado de um ticket.

graph TD;  

    A[Ocorre um Evento no Freshdesk] -->|Aciona Webhook| B(Freshdesk Envia Pedido POST);
    B --> C{Endpoint da Sua Aplicação};  

    C --> D[Processar Dados e Executar Lógica];  

    D --> E(Realizar Ação noutro Sistema);  

Mas aqui está o problema: um webhook apenas envia os dados. Não faz nada por si só. Ainda precisa de construir, alojar e manter uma aplicação separada para receber esses dados e executar a sua lógica. Isto adiciona outra camada de complexidade e custo à sua configuração.

A alternativa mais simples e poderosa: integração com IA

É para aqui que muitas equipas estão a mudar agora. Em vez de construir um serviço separado para ouvir webhooks e executar código personalizado, pode usar uma plataforma de IA integrada que faz todo o trabalho pesado por si.

O eesel AI oferece uma integração de um clique com o Freshdesk que substitui a necessidade de escrever scripts de API ou construir ouvintes de webhooks. É um motor de fluxo de trabalho completo que pode pôr a funcionar em minutos.

Eis porque isto é tão importante:

• Não é necessário programar: Pode construir automações surpreendentemente complexas e de vários passos usando um painel de controlo simples. Não são necessários programadores.

• Ações personalizadas: A IA não está apenas confinada ao Freshdesk. Pode fazer chamadas de API para os seus outros sistemas (como verificar uma encomenda no Shopify) para obter informações em tempo real antes de decidir o que fazer a seguir.

• Modo de simulação: Esta é provavelmente a parte mais interessante. Antes de ativar a sua automação, pode testá-la em milhares dos seus tickets passados. A simulação do eesel AI mostra-lhe exatamente como o seu agente de IA se irá comportar, qual será a sua taxa de resolução e onde poderá ficar preso. Isto permite-lhe implementar com confiança, em vez de apenas cruzar os dedos.

Compreender preços e limitações

Aqui está outra coisa prática a ter em mente: custo e escala. O seu acesso à API do Freshdesk está diretamente ligado ao seu plano de preços, que define o seu limite de taxa.

Plano	Limite de Taxa da API (por minuto)
Growth	200
Pro	400
Enterprise	700

O que é que isto significa na prática para si? Se a sua empresa recebe muitos tickets, ou se as suas automações são comunicativas e fazem várias chamadas de API por ticket, pode atingir esse limite com bastante facilidade. Quando isso acontece, as suas integrações simplesmente param de funcionar até o relógio reiniciar, o que pode causar atrasos para os seus clientes.

Isto por vezes força as empresas em crescimento a optar por um plano mais caro do Freshdesk apenas para obter limites de API mais altos, mesmo que não precisem das outras funcionalidades. É um custo um pouco oculto quando constrói as suas próprias integrações.

Comece a funcionar em minutos, não em meses, com o eesel AI

Construir integrações de API personalizadas é um projeto sério. Requer tempo de programador para planear, construir, testar e implementar. E o trabalho nunca para realmente, tem de alojar o código e mantê-lo atualizado para sempre.

Com o eesel AI, muitas vezes pode obter melhores resultados numa pequena fração do tempo.

• É verdadeiramente self-service: Pode inscrever-se e lançar um agente de IA funcional em poucos minutos, por sua conta. Não precisa de assistir a uma demonstração de vendas se não quiser.

• Integração com um clique: Esqueça o copiar e colar de chaves de API. O eesel AI liga-se de forma direta e segura à sua conta Freshdesk.

• Controlo total: Não tem de automatizar todo o seu helpdesk de um dia para o outro. Comece com um caso de uso simples, como perguntas do tipo "Onde está a minha encomenda?". À medida que vê como funciona e se sente confortável, pode gradualmente dar mais tarefas à IA.

O eesel AI não é apenas um substituto para a API; é uma forma mais rápida e acessível de resolver os mesmos problemas que levam as pessoas a recorrer à API em primeiro lugar.

Considerações finais sobre o uso da API de tickets do Freshdesk

A API de tickets do Freshdesk é uma ferramenta sólida se tiver os recursos de programação para construir e manter integrações personalizadas. Dá-lhe a liberdade de ligar o seu helpdesk a praticamente qualquer coisa. Mas essa liberdade vem com o custo contínuo de tempo de programador, manutenção e limites de API que podem ser uma dor de cabeça à medida que cresce.

Para a maioria das equipas que apenas querem automatizar trabalho repetitivo e libertar os seus agentes, as plataformas de IA modernas oferecem um caminho muito mais direto. Elas gerem a complexidade técnica por si, para que se possa focar em criar ótimas experiências para o cliente, e não em gerir infraestruturas.

Pronto para ver o que pode automatizar sem escrever qualquer código? Experimente o eesel AI gratuitamente e veja o quanto consegue fazer nos próximos 10 minutos.