Primeiros passos com a API

A API do Chatfood deixa seus sistemas fazerem o que você faz no painel: ler o desempenho das páginas, listá-las, agendar broadcasts, cadastrar pixels de conversão e mais. Todas as rotas ficam sob /v1 (por exemplo GET /v1/pages) e toda chamada é autenticada com um token de API que você cria no painel e que só faz o que você permitir.

Endereço base: https://api.chatfood.app.

1. Crie um token

1. Entre no painel e abra Configurações > Tokens de API.
2. Dê um nome que diga quem vai usar o token (por exemplo, “Relatórios do ERP”).
3. Escolha a conta em que o token pode agir. Um token preso a uma conta nunca enxerga as outras.
4. Escolha os escopos: o mínimo que a tarefa precisa. metrics:read basta para relatórios; enviar broadcasts precisa de broadcasts:write e flows:read.
5. Defina uma validade sempre que o uso for temporário.
6. Copie o token (cf_live_...). Ele aparece uma única vez: o Chatfood guarda apenas o hash.

Trate o token como uma senha. Guarde-o num cofre de segredos no seu servidor, nunca no navegador, numa URL ou num repositório.

2. Como funcionam tokens e escopos

O token é uma credencial de longa duração ligada a um usuário, a um conjunto de escopos e, opcionalmente, a uma das contas desse usuário. Formato: cf_live_ seguido de 43 caracteres base64 URL-safe (regex cf_live_[A-Za-z0-9_-]{43}, para que scanners de segredo encontrem um token vazado). Envie em qualquer um dos cabeçalhos:

Authorization: Bearer cf_live_...
X-Api-Key: cf_live_...

Os escopos seguem o formato area:acesso, em que o acesso é read ou write, e write inclui read:

Área	O que cobre
pages	páginas (/v1/pages), histórico de conexões (/v1/connections), conexão de páginas Meta e Telegram, ice breakers, variáveis da página, alertas
leads	leads (/v1/leads), tags de lead (/v1/tags), exclusão dos leads de uma página
flows	fluxos (/v1/schemas), templates de utilidade, templates de mensagem da Meta, upload de mídia (/v1/uploads, /v1/voice-messages), POST /v1/schemas/{schemaId}/test
broadcasts	/v1/broadcasts e suas execuções
journeys	/v1/journeys
metrics	/v1/alerts/summary, /v1/schemas/{schemaId}/metrics*, /v1/pages/{pageId}/send-time-suggestion e o endpoint GraphQL
websites	/v1/website-domains e /v1/websites
pixels	/v1/meta/datasets
payments	reservado para relatórios de Pix (ainda não publicado)
account	configurações da conta, slugs de UTM e de idioma, apps da Meta, notificações, categorias e grupos de variáveis
users	listagem dos membros da conta (GET /v1/accounts/{accountId}/users)
billing	/v1/billing/*

Regras:

• GET exige read; os demais verbos exigem write. Algumas rotas declaram exceções, como POST /v1/schemas/validate-variables (basta flows:read) e POST /v1/broadcasts/delivery-preview (basta broadcasts:read).
• Rota que não declara área não está disponível para tokens, assim como rotas administrativas, internas, de gestão de tokens e de ciclo de vida de conta ou membro. A resposta é 403 com um detail dizendo o que falta.
• O token nunca passa do dono. Em cada conta, a chamada só faz o que os escopos do token e as permissões do dono naquela conta permitem. Se o dono perde uma conta ou permissão, o token perde junto na próxima chamada.
• Tokens revogados ou vencidos recebem 401 na hora.
• Cada token tem limite de 120 chamadas por minuto por instância da API. Acima disso, a resposta é 429 com Retry-After.
• Toda escrita feita com token fica registrada no log de auditoria com o id do token.

3. Primeira chamada

export CF=cf_live_...
export API=https://api.chatfood.app
curl -s "$API/v1/me" -H "Authorization: Bearer $CF"

Leia accounts[].id e accounts[].permissions. Se a conta que você precisa não aparece, ou está sem a permissão, peça outro token ao dono: tentar de novo não resolve.

4. Documento OpenAPI

• A Referência da API deste site é gerada do documento OpenAPI publicado pela API em https://api.chatfood.app/swagger/agents/swagger.json, que lista só as rotas que um token de API pode chamar, cada uma com o escopo exigido em x-required-scope.
• O documento é sincronizado a cada publicação deste site. API v1 em lançamento: enquanto a /v1 não estiver publicada em produção, a referência pode mostrar as rotas anteriores; os guias já descrevem a /v1.
• Para testar chamadas pelo navegador, use a referência interativa: cole o token em Authentication e use Test request. O token fica só na aba do navegador.
• Qualquer ferramenta OpenAPI (Postman, Bruno, Insomnia, geradores de código) importa o documento.