Introdução

A API do Festero entrega aos seus sistemas os dados da sua empresa no Festero, somente para leitura. Com ela você alimenta um ERP, monta relatórios num BI, avisa outro sistema quando um orçamento é aceito ou deixa um assistente de IA responder perguntas sobre o seu negócio, sem ninguém copiar planilha.

Os dados são da sua empresa e só dela: cada credencial enxerga uma única empresa, e um recurso de outra empresa responde 404, nunca 403.

Três formas de usar

Forma	Para que serve	Comece por
API de leitura	Consultar oportunidades, eventos, orçamentos, visitas e recebíveis quando o seu sistema precisar.	Início rápido
Webhooks	Receber um aviso no seu endereço HTTPS quando algo acontece, em vez de consultar a API o tempo todo.	Webhooks
Servidor MCP	Conectar um assistente de IA às mesmas informações, para perguntar em português.	Servidor MCP

As três formas usam a mesma credencial, os mesmos escopos e os mesmos dados.

Cinco conjuntos de dados

Cada conjunto tem um escopo. Ao criar uma credencial, você escolhe quais deles ela pode ler.

Conjunto (nome na tela)	Escopo	O que traz	Página
CRM	crm:read	Oportunidades e etapas do funil, sem dados de contato do lead.	CRM
Visitas	visits:read	Visitas agendadas, sem telefone, e-mail, link de reunião e anotações.	Visitas
Eventos	events:read	Identidade, data, hora, status, tipo, cliente e valor total do evento.	Eventos
Orçamentos	quotes:read	Orçamentos e seus itens, sem custo e sem anotação interna.	Orçamentos
Financeiro	finance:read	Recebíveis e parcelas, e o resumo de vendas por período, sem custo e margem.	Financeiro

As rotas GET /v1/health e GET /v1/me (Conta) não pedem escopo.

O que a API não faz

• Não escreve. Não existe rota para criar, alterar ou excluir nada. Quem muda os dados é o Festero.
• Não entrega custo nem margem. Todo valor em dinheiro é o preço ao cliente.
• Não entrega contato de pessoa. Telefone, e-mail e documento não saem pela API. Quando um nome ou título traz um trecho assim (por exemplo, um cliente cadastrado com o telefone no lugar do nome), a API troca o trecho por [oculto].

Planos e limites

A API faz parte dos planos Premium e Enterprise. Cada credencial tem a sua cota por minuto e por dia, que depende do plano. Veja os números em Limites de uso.

Se a empresa sair desses planos, as credenciais ficam suspensas e as chamadas passam a responder plan_required ou credential_revoked.

Quem pode criar uma credencial

A credencial é criada no próprio Festero, no item API do Festero do menu lateral. Para isso, a pessoa precisa de:

1. uma empresa nos planos Premium ou Enterprise;
2. a permissão Gerenciar a API pública e as chaves MCP no perfil de acesso dela (em Perfis e Permissões).

Os conjuntos de dados oferecidos na criação são os que a própria pessoa enxerga no Festero: quem não vê o financeiro não consegue criar uma credencial com finance:read. Assim, uma credencial nunca vê mais do que quem a criou.

Disponibilidade

O item API do Festero só aparece no menu das empresas em que a API já foi liberada. Se a sua empresa tem o plano Premium ou Enterprise e você não encontra o item, fale com o suporte.

Convenções da API

Item	Como é
Endereço base	https://platform.festero.com.br
Versão	/v1 no caminho. Veja Versionamento.
Formato	JSON, com nomes de campo em camelCase.
Autenticação	Authorization: Bearer <token>. Veja Autenticação.
Listas	Paginadas por cursor. Veja Paginação e datas.
Erros	application/problem+json com um code estável. Veja Erros.
Contrato	Documento OpenAPI em /openapi.v1.json e referência interativa.

Por onde seguir

1. Faça a primeira chamada em poucos minutos: Início rápido.
2. Entenda o token, os escopos e a revogação: Autenticação.
3. Evite surpresas em produção: Limites de uso e Erros.
4. Prefira avisos a consultas repetidas: Webhooks.
5. Quer perguntar em linguagem natural? Servidor MCP.