{
"title": "Visão geral da API Freshservice: Um guia completo para desenvolvedores para 2026",
"slug": "freshservice-api-overview",
"locale": "pt",
"date": "2026-03-12",
"updated": "2026-03-12",
"template": "default",
"excerpt": "Um guia abrangente da API Freshservice, cobrindo métodos de autenticação, endpoints principais, limites de taxa e dicas práticas de implementação para desenvolvedores.",
"categories": [
"Guides"
],
"tags": [
"Freshservice",
"API",
"ITSM",
"Developer Guide",
"Integration"
],
"readTime": 9,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Visão geral da API Freshservice: Um guia completo para desenvolvedores para 2026",
"description": "Um guia abrangente da API Freshservice, cobrindo métodos de autenticação, endpoints principais, limites de taxa e dicas práticas de implementação para desenvolvedores.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-562b5921-9ea4-4dfa-bdd4-1d95d5e4d11c"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-562b5921-9ea4-4dfa-bdd4-1d95d5e4d11c",
"coverImageAlt": "Imagem do banner para visão geral da API Freshservice: Um guia completo para desenvolvedores para 2026",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Quais métodos de autenticação a API Freshservice suporta?",
"answer": "A API Freshservice suporta três métodos de autenticação: autenticação por chave de API usando Basic Auth (recomendado para a maioria das integrações), autenticação por nome de usuário/senha e OAuth 2.0 para aplicações que requerem contexto de usuário. A autenticação por chave de API é a abordagem mais simples para integrações servidor a servidor."
},
{
"question": "Quais são os limites de taxa para a API Freshservice?",
"answer": "Os limites de taxa variam de acordo com o plano. Contas Starter recebem 100 requisições por minuto, Growth recebe 200, Pro recebe 400 e Enterprise recebe 500. Há também sub-limites para operações específicas, como listar tickets ou ativos. Esses limites são para toda a conta, não por usuário."
},
{
"question": "Posso usar a API Freshservice para criar tickets automaticamente?",
"answer": "Sim, o endpoint /api/v2/tickets suporta requisições POST para criar tickets programaticamente. Você pode especificar todas as propriedades do ticket, incluindo assunto, descrição, e-mail do solicitante, prioridade, status e campos personalizados. Isso é comumente usado para integrar ferramentas de monitoramento e sistemas de alerta automatizados."
},
{
"question": "Qual é a diferença entre a API Freshservice v1 e v2?",
"answer": "A API v2 oferece limites de taxa significativamente maiores, tratamento de erros aprimorado com códigos de status HTTP adequados, endpoints adicionais para conversas e atualizações de tickets, suporte para tamanhos de página de até 100 e conexões somente HTTPS. A versão 1 está obsoleta e não deve ser usada para novos projetos."
},
{
"question": "Como faço para lidar com a paginação na API Freshservice?",
"answer": "Os endpoints de listagem suportam paginação usando os parâmetros de consulta page e per_page. O parâmetro per_page aceita valores de até 100. Sempre implemente a paginação para integrações de produção, pois tentar recuperar grandes conjuntos de dados em uma única requisição falhará ou atingirá o tempo limite."
},
{
"question": "A API Freshservice suporta webhooks para notificações em tempo real?",
"answer": "Sim, o Freshservice suporta configurações de webhook que podem notificar sistemas externos quando eventos de ticket ocorrem. Isso geralmente é mais eficiente do que pesquisar a API repetidamente por atualizações. Os webhooks podem ser acionados na criação, atualizações, mudanças de status e outros eventos de tickets."
}
],
"supportLink": null
}
}
---
Se você está construindo integrações com o Freshservice, você precisa entender suas capacidades de API (API capabilities). Seja automatizando a criação de tickets, sincronizando dados de usuários ou construindo painéis personalizados, a API Freshservice te dá acesso programático aos seus dados de gerenciamento de serviços de TI.
Vamos detalhar o que a API Freshservice oferece, como autenticar, quais endpoints estão disponíveis e como trabalhar dentro de seus limites de taxa. Também veremos como ferramentas como [eesel AI](https://www.eesel.ai/integration/freshservice-ai) podem simplificar algumas dessas integrações sem escrever código do zero.
## O que é a API Freshservice?
A [API Freshservice](https://api.freshservice.com/) é uma interface RESTful que permite que você interaja com sua instância Freshservice programaticamente. Ela segue as convenções HTTP padrão, usa JSON para troca de dados e suporta toda a gama de operações CRUD (Create, Read, Update, Delete - Criar, Ler, Atualizar, Excluir).
Aqui está o que isso significa na prática. Você pode:
- Puxar dados de tickets para ferramentas de relatório externas
- Criar tickets automaticamente a partir de alertas de monitoramento
- Sincronizar informações de usuários com seu provedor de identidade
- Atualizar registros de ativos a partir de ferramentas de descoberta
- Construir portais personalizados ou aplicativos móveis
O Freshservice realmente oferece duas versões de API. A versão 1 é a API legada, ainda funcional, mas limitada. A versão 2 é o que você deve usar para novos projetos. Ela oferece limites de taxa mais altos, melhor tratamento de erros e mais endpoints. A API v2 aceita apenas JSON e requer conexões HTTPS.
O Freshservice também vem em três versões, cada uma com um comportamento de API ligeiramente diferente:
- **Freshservice**: A plataforma ITSM padrão
- **Freshservice for Business Teams (FSBT)**: Projetado para departamentos não relacionados a TI, como RH ou Instalações
- **Freshservice for MSPs**: Construído para provedores de serviços gerenciados que lidam com vários clientes
A API principal funciona da mesma forma em todos os três, mas alguns endpoints e terminologia diferem. Por exemplo, os MSPs usam "Contacts" (Contatos) em vez de "Requesters" (Solicitantes) e "Clients" (Clientes) em vez de "Workspaces" (Espaços de Trabalho).
## Métodos de autenticação
Antes de fazer qualquer chamada de API, você precisa se autenticar. O Freshservice oferece algumas opções, dependendo do seu caso de uso.
### Autenticação por chave de API (recomendado)
Esta é a abordagem mais simples e comum. Você gera uma chave de API a partir do seu perfil Freshservice e, em seguida, a inclui em suas requisições usando Basic Auth.
Veja como encontrar sua chave de API:
1. Faça login no seu portal Freshservice
2. Clique na sua foto de perfil no canto superior direito
3. Vá para **Configurações de Perfil**
4. Sua chave de API aparece abaixo da seção Alterar Senha
Depois de ter sua chave, você se autentica passando-a como o nome de usuário em um cabeçalho Basic Auth, com qualquer string (convencionalmente "X") como a senha. Veja como isso se parece na prática:
```bash
curl -u "sua_chave_api:X" \
-H "Content-Type: application/json" \
-X GET \
"https://seudominio.freshservice.com/api/v2/tickets"
Ou em JavaScript:
const apiKey = "sua_chave_api_aqui";
const encodedKey = Buffer.from(apiKey + ":X").toString("base64");
fetch("https://seudominio.freshservice.com/api/v2/tickets", {
method: "GET",
headers: {
"Authorization": `Basic ${encodedKey}`,
"Content-Type": "application/json"
}
})
.then(response => response.json())
.then(data => console.log(data));
Autenticação por nome de usuário e senha
Você também pode se autenticar usando suas credenciais de login do Freshservice. Isso funciona da mesma forma que a autenticação por chave de API, mas você passa seu e-mail e senha em vez disso:
curl -u "usuario@empresa.com:senha" \
-H "Content-Type: application/json" \
-X GET \
"https://seudominio.freshservice.com/api/v2/tickets"
OAuth 2.0
Para aplicativos que precisam agir em nome dos usuários (como aplicativos de marketplace), o Freshservice suporta OAuth 2.0. Isso é mais complexo de configurar, mas oferece melhor segurança para integrações voltadas para o usuário.
Melhores práticas de segurança
Algumas coisas para ter em mente:
- Armazene as chaves de API com segurança, nunca as inclua no controle de versão
- Use HTTPS para todas as requisições (a v2 exige isso)
- Gire as chaves de API periodicamente
- Use as permissões mínimas necessárias para sua integração
- Considere usar variáveis de ambiente para o armazenamento de chaves
Endpoints e capacidades principais da API
A API Freshservice cobre virtualmente todos os recursos da plataforma. Aqui estão os principais endpoints com os quais você trabalhará.
Tickets
O endpoint de tickets é o mais comumente usado. Você pode:
- Listar todos os tickets com filtragem e paginação
- Criar novos tickets programaticamente
- Atualizar propriedades do ticket (status, prioridade, responsável)
- Excluir ou restaurar tickets
- Adicionar respostas e notas
Uma requisição básica de criação de ticket se parece com isto:
fetch("https://seudominio.freshservice.com/api/v2/tickets", {
method: "POST",
headers: {
"Authorization": "Basic " + btoa("api_key:X"),
"Content-Type": "application/json"
},
body: JSON.stringify({
email: "solicitante@exemplo.com",
subject: "Nova solicitação de laptop",
description: "Preciso de um novo laptop para o próximo projeto",
priority: 2,
status: 2
})
});
As propriedades do ticket usam valores numéricos para status e prioridade:
| Status | Valor |
|---|---|
| Aberto | 2 |
| Pendente | 3 |
| Resolvido | 4 |
| Fechado | 5 |
| Prioridade | Valor |
|---|---|
| Baixa | 1 |
| Média | 2 |
| Alta | 3 |
| Urgente | 4 |
Usuários e grupos
Gerencie sua equipe de service desk e solicitantes:
- Agentes: Equipe de TI que lida com tickets
- Solicitantes: Funcionários que enviam tickets
- Grupos: Equipes que lidam com tipos de tickets específicos
- Departamentos: Estrutura organizacional
Ativos
Rastreie e gerencie ativos de TI ao longo de seu ciclo de vida:
- Criar e atualizar registros de ativos
- Associar ativos a tickets
- Gerenciar relacionamentos e dependências de ativos
- Rastrear manutenção e contratos de ativos
Mudanças e problemas
Para gerenciamento de mudanças alinhado ao ITIL:
- Criar solicitações de mudança
- Gerenciar fluxos de trabalho de aprovação de mudança
- Vincular mudanças a tickets e problemas
- Rastrear o status de implementação
Catálogo de serviços
Automatize solicitações de serviço:
- Listar itens de serviço disponíveis
- Enviar solicitações de serviço
- Rastrear o status de aprovação da solicitação
- Gerenciar acordos de nível de serviço
Conversas
Lidar com comunicações de tickets:
- Adicionar respostas públicas visíveis aos solicitantes
- Adicionar notas privadas para equipes internas
- Anexar arquivos a conversas
- Encaminhar tickets para terceiros
Limites de taxa e melhores práticas
O Freshservice impõe limites de taxa para garantir a estabilidade da plataforma. Estes variam com base no seu plano e quando sua conta foi criada.
Limites de taxa por plano
Para contas criadas após 1º de setembro de 2020:
| Plano | Limite Geral (por minuto) | Operações de Ticket/Lista (por minuto) |
|---|---|---|
| Starter | 100 | 40 |
| Growth | 200 | 70 |
| Pro | 400 | 120 |
| Enterprise | 500 | 140 |
Observe que estes são limites para toda a conta, não por usuário ou por IP. Cada chamada de API da sua conta conta para a mesma cota.
Cabeçalhos de limite de taxa
Cada resposta da API inclui cabeçalhos mostrando seu status atual de limite de taxa:
X-RateLimit-Total: O limite total da sua conta por minutoX-RateLimit-Remaining: Requisições restantes na janela atualX-RateLimit-Used-CurrentRequest: Quantas requisições sua última chamada consumiuRetry-After: Segundos para esperar quando você atingiu o limite (aparece apenas em respostas 429)
Lidando com limites de taxa
Quando você atinge o limite, a API retorna um código de status 429. Seu código deve lidar com isso normalmente:
async function makeRequestWithRetry(url, options, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
const response = await fetch(url, options);
if (response.status !== 429) {
return response.json();
}
const retryAfter = response.headers.get('Retry-After') || Math.pow(2, retries);
console.log(`Limite de taxa atingido. Tentando novamente em ${retryAfter} segundos...`);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
retries++;
}
throw new Error('Número máximo de tentativas atingido');
}
Paginação
Os endpoints de listagem retornam resultados paginados. Use o parâmetro page para navegar:
curl -u "api_key:X" \
"https://seudominio.freshservice.com/api/v2/tickets?page=2&per_page=100"
A API v2 suporta tamanhos de página de até 100 registros. Sempre implemente a paginação para integrações de produção, em vez de presumir que você obterá todos os resultados em uma única chamada.
Casos de uso comuns de integração
Aqui estão algumas maneiras práticas pelas quais as organizações usam a API Freshservice:
Criação automatizada de tickets: Ferramentas de monitoramento como Datadog ou PagerDuty podem criar tickets automaticamente quando os alertas são acionados, garantindo que as equipes de TI respondam rapidamente aos incidentes.
Provisionamento de usuários: Quando novos funcionários são contratados, os sistemas de RH podem criar contas Freshservice automaticamente, atribuindo-os aos departamentos e grupos certos com base em sua função.
Sincronização de ativos: Ferramentas de descoberta podem enviar dados de ativos para o CMDB do Freshservice, mantendo os registros de inventário atualizados sem entrada manual.
Painéis personalizados: As organizações puxam métricas de tickets para ferramentas de business intelligence como Tableau ou Power BI para relatórios executivos.
Integrações de chatbot: Ferramentas de suporte baseadas em IA podem criar tickets a partir de conversas de chat, categorizando e roteando-os automaticamente com base na análise de conteúdo.
Automação de e-mail: E-mails recebidos de domínios específicos ou contendo certas palavras-chave podem acionar a criação de tickets com categorias e responsáveis pré-preenchidos.
Começando com sua primeira chamada de API
Pronto para tentar você mesmo? Aqui está um guia de início rápido.
Primeiro, pegue sua chave de API nas configurações do seu perfil Freshservice. Em seguida, abra um terminal e execute este comando cURL (substitua seudominio e sua_chave_api):
curl -u "sua_chave_api:X" \
-H "Content-Type: application/json" \
-X GET \
"https://seudominio.freshservice.com/api/v2/tickets?page=1&per_page=1"
Se tudo funcionar, você receberá uma resposta JSON com seu ticket mais recente.
Para exploração, o Postman é inestimável. Crie uma nova requisição, defina a autenticação para Basic Auth com sua chave de API como o nome de usuário e "X" como a senha e comece a testar os endpoints.
A Freshworks também fornece um SDK oficial JavaScript/TypeScript que simplifica as interações da API:
const { Freshservice } = require("@freshworks/api-sdk");
const fs = new Freshservice("seudominio", "sua_chave_api");
// Obter todos os tickets
const tickets = await fs.tickets.list();
Simplificando as integrações do Freshservice com eesel AI
Construir integrações de API do zero leva tempo e recursos de engenharia. Se você precisa automatizar os fluxos de trabalho do Freshservice sem escrever código, o eesel AI oferece uma abordagem alternativa.
Nossa plataforma se conecta diretamente ao Freshservice e fornece automação baseada em IA para tarefas comuns:
- Agente de IA: Lida autonomamente com tickets de suporte de primeira linha, resolvendo problemas comuns sem intervenção humana
- Copiloto de IA: Redige respostas para seus agentes revisarem e enviarem, acelerando os tempos de resposta
- Triagem de IA: Marca, roteia e prioriza automaticamente os tickets recebidos com base no conteúdo
Em vez de escrever chamadas de API para criar tickets ou atualizar campos, você configura regras de automação em linguagem simples. Por exemplo: "Se um ticket mencionar 'redefinição de senha' e vier de um usuário VIP, atribua-o ao grupo de suporte sênior e marque-o como alta prioridade."
A configuração leva minutos, em vez de semanas. Você conecta sua conta Freshservice e nossa IA aprende com seus tickets existentes, artigos da central de ajuda e macros. Não há necessidade de mapear endpoints de API ou lidar com o limite de taxa você mesmo.
Para equipes que precisam de integrações de API personalizadas e automação de IA, as abordagens se complementam. Use a API para sincronização de dados e comunicação de sistema para sistema, e eesel AI para tratamento inteligente de tickets e redação de respostas.
Compartilhe esta postagem
Article by
