# 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](https://developers.festero.com.br/inicio-rapido.md) |
| **Webhooks** | Receber um aviso no seu endereço HTTPS quando algo acontece, em vez de consultar a API o tempo todo. | [Webhooks](https://developers.festero.com.br/webhooks.md) |
| **Servidor MCP** | Conectar um assistente de IA às mesmas informações, para perguntar em português. | [Servidor MCP](https://developers.festero.com.br/mcp.md) |

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](https://developers.festero.com.br/api/crm.md) |
| Visitas | `visits:read` | Visitas agendadas, sem telefone, e-mail, link de reunião e anotações. | [Visitas](https://developers.festero.com.br/api/visitas.md) |
| Eventos | `events:read` | Identidade, data, hora, status, tipo, cliente e valor total do evento. | [Eventos](https://developers.festero.com.br/api/eventos.md) |
| Orçamentos | `quotes:read` | Orçamentos e seus itens, sem custo e sem anotação interna. | [Orçamentos](https://developers.festero.com.br/api/orcamentos.md) |
| Financeiro | `finance:read` | Recebíveis e parcelas, e o resumo de vendas por período, sem custo e margem. | [Financeiro](https://developers.festero.com.br/api/financeiro.md) |

As rotas `GET /v1/health` e `GET /v1/me` ([Conta](https://developers.festero.com.br/api/conta.md)) 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](https://developers.festero.com.br/limites.md).

Se a empresa sair desses planos, as credenciais ficam suspensas e as chamadas passam a responder [`plan_required`](https://developers.festero.com.br/errors.md#plan_required) ou [`credential_revoked`](https://developers.festero.com.br/errors.md#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.

> **Informação**: 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](https://developers.festero.com.br/versionamento.md). |
| Formato | JSON, com nomes de campo em `camelCase`. |
| Autenticação | `Authorization: Bearer <token>`. Veja [Autenticação](https://developers.festero.com.br/autenticacao.md). |
| Listas | Paginadas por cursor. Veja [Paginação e datas](https://developers.festero.com.br/paginacao.md). |
| Erros | `application/problem+json` com um `code` estável. Veja [Erros](https://developers.festero.com.br/errors.md). |
| Contrato | Documento OpenAPI em [`/openapi.v1.json`](https://developers.festero.com.br/openapi.v1.json) e [referência interativa](https://developers.festero.com.br/referencia/). |

## Por onde seguir

1. Faça a primeira chamada em poucos minutos: [Início rápido](https://developers.festero.com.br/inicio-rapido.md).
2. Entenda o token, os escopos e a revogação: [Autenticação](https://developers.festero.com.br/autenticacao.md).
3. Evite surpresas em produção: [Limites de uso](https://developers.festero.com.br/limites.md) e [Erros](https://developers.festero.com.br/errors.md).
4. Prefira avisos a consultas repetidas: [Webhooks](https://developers.festero.com.br/webhooks.md).
5. Quer perguntar em linguagem natural? [Servidor MCP](https://developers.festero.com.br/mcp.md).