Primeiros passos

Este guia é o ponto de partida para quem vai criar uma aplicação nova do zero com a Nova API V1.0. Antes de gerar código, escolha o fluxo de acesso correto e leia o contrato de cada operação que será usada.

Sua aplicação já usa o API Legado?

Essa versão será removida em breve. Não trate a mudança apenas como uma troca de URL. Siga o guia Migrar do API Legado para inventariar rotas, substituir a autenticação, validar compatibilidade e planejar o corte.

Escolha o tipo de integração

Cenário	Use	Credencial inicial	Guia
Automação de um restaurante, backend próprio ou protótipo privado	API key	`tk_test_...` ou `tk_live_...` criada no AI Builders	API Key
SaaS, app de parceiro ou produto instalado por vários restaurantes	OAuth Authorization Code + PKCE	Client ID público `tk_app_...`	OAuth para aplicativos
Interface Takeat usada por um restaurante já autenticado	Sessão do restaurante	Token emitido pelo login Takeat	Reutilize a sessão somente dentro da interface autenticada

Regra prática

Comece com API key quando o próprio restaurante controla a integração. Use OAuth quando cada cliente precisa entrar com a Takeat e autorizar seu app sem compartilhar uma API key. Reutilize a sessão do restaurante somente em interfaces Takeat ou fluxos interativos próprios; integrações de backend não devem pedir senha nem copiar o token do painel.

As rotas de dados aceitam os dois tipos de Bearer. Tokens OAuth precisam do escopo de cada operação. A sessão do restaurante não carrega esses escopos: o restaurant_id assinado limita todas as leituras e alterações ao próprio restaurante. Chaves tk_ continuam proibidas diretamente em /v1.

Fluxo recomendado para vibe coding

1. Dê somente documentação ao agente

Peça ao agente para ler /llms.txt, o guia de autenticação em Markdown e os contratos .md das operações necessárias. Não envie uma credencial real no prompt.

2. Gere a estrutura sem segredos

Solicite .env.example, validação de configuração, um cliente HTTP isolado, tipos de resposta e tratamento explícito de 400, 401, 403 e 429.

3. Configure a credencial fora do chat

Guarde a API key, ou os tokens emitidos por uma instalação OAuth, no backend: use um .env.local ignorado pelo Git durante o desenvolvimento e um gerenciador de segredos na hospedagem. O agente deve usar somente nomes de variáveis e valores fictícios.

4. Teste no ambiente correto

Mantenha portal, API e credenciais do mesmo ambiente. Com API Key, use tk_test_..., poucos dados e chamadas controladas. Respeite os limites exibidos no AI Builders; uma chave de restaurante começa com 10 requisições por minuto e no máximo 500 por dia.

5. Revise antes de publicar

Procure segredos no diff e no histórico, confirme que tokens não chegam ao navegador e valide a resposta real contra o contrato documentado.

Primeira chamada com API key

Crie a chave no AI Builders, guarde-a em TAKEAT_API_KEY e faça a troca no backend:

const tokenBody = new URLSearchParams({
  grant_type: "api_key",
  api_key: process.env.TAKEAT_API_KEY,
});

const tokenResponse = await fetch("https://public-api.takeat.app/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: tokenBody,
});

if (!tokenResponse.ok) {
  throw new Error(`Falha ao emitir token: ${tokenResponse.status}`);
}

const { access_token: accessToken } = await tokenResponse.json();

const menuResponse = await fetch(
  "https://public-api.takeat.app/v1/menu?channel=delivery",
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

O exemplo é intencionalmente server-side. Não prefixe a variável com NEXT_PUBLIC_, VITE_, PUBLIC_ ou qualquer convenção que a envie ao bundle do navegador.

Segurança obrigatória

Nunca cole API keys, access tokens, refresh tokens, códigos OAuth, code_verifier, senhas ou headers de autorização em uma conversa com IA.
Nunca faça commit de .env, dumps, coleções com valores preenchidos, screenshots ou logs que contenham credenciais.
Guarde API keys e refresh tokens somente no backend, criptografados em repouso quando persistidos, e restrinja o acesso por serviço.
Mostre ao agente nomes de variáveis e valores fictícios, por exemplo tk_test_EXEMPLO, nunca o segredo verdadeiro.
Remova ou mascare Authorization, api_key, refresh_token, code e code_verifier de logs e ferramentas de observabilidade.
Use o menor conjunto de escopos possível. Uma operação que só lê o cardápio deve usar menu:read, não todos os escopos disponíveis.
Em caso de vazamento, revogue a chave no AI Builders, substitua o segredo na hospedagem e revise Git, logs, builds e histórico do provedor de IA.

Copie e adapte

Oi! Preciso da sua ajuda para criar do zero uma aplicação integrada à Nova API
V1.0 da Takeat.

Contexto rápido: a Takeat é a plataforma que o restaurante usa para operar o
cardápio, as comandas e os pedidos. Esta é uma aplicação nova: não existe uma
integração anterior para preservar e nenhum endpoint do API Legado deve ser usado. Se
já houver um projeto neste workspace, examine sua arquitetura e convenções;
caso esteja vazio, proponha uma estrutura adequada antes de criar arquivos.

A documentação oficial foi preparada para agentes e está disponível aqui:
https://docs.takeat.app/llms.txt  (índice das páginas e contratos)
https://docs.takeat.app/api/mcp   (MCP somente leitura, se estiver disponível)

Leia primeiro Primeiros passos e compare Autenticação com API Key com OAuth
para aplicativos. Escolha API Key se a integração pertencer a um único
restaurante; escolha OAuth Authorization Code com PKCE se o produto for
instalado por restaurantes diferentes. Explique essa decisão antes de gerar
código. Depois, localize o contrato Markdown completo de cada operação
necessária. Trate esses documentos como fonte da verdade e não invente
endpoints, campos, escopos ou comportamentos que não estejam publicados.

O que o app precisa fazer:

Primeiro: conectar o restaurante usando o fluxo de autenticação correto. A
emissão, troca e renovação de tokens devem acontecer somente no backend, sem
renovações concorrentes para a mesma credencial ou instalação.

Segundo: carregar o cardápio de delivery, incluindo categorias, produtos,
preços e complementos que o contrato realmente disponibilizar. Quero tipos
derivados do contrato e uma separação clara entre o cliente HTTP da Takeat e a
camada que prepara os dados para a interface.

Terceiro: consultar as comandas dentro dos limites de data publicados. Confirme
no contrato os nomes dos parâmetros, formatos UTC, escopos, paginação e formato
de resposta antes de definir tipos ou regras de negócio.

Quarto: lidar explicitamente com 400, 401, 403 e 429. Uma chave criada pelo
restaurante começa com 10 requisições por minuto e no máximo 500 por dia, então
proponha cache, backoff com jitter e uma forma de evitar chamadas duplicadas.

Quinto: alternar entre Teste e Produção apenas por configuração validada, nunca
por mudanças no código. Uma chave de Teste não cria dados fictícios; qualquer
teste deve ser conservador e somente leitura.

Segurança é inegociável: não me peça para colar API Keys, tokens, códigos
OAuth, code_verifier ou headers Authorization. Não abra, imprima nem altere
arquivos .env que possam conter segredos. Credenciais e tokens nunca podem
chegar ao navegador, a logs, ao Git, a mensagens de erro ou a artefatos
gerados. Produza somente um .env.example com nomes de variáveis e valores
fictícios.

Antes de escrever a implementação, me explique como pretende organizar os
arquivos, a escolha de autenticação, o isolamento por restaurante quando
aplicável, o cache, a renovação de tokens, os contratos usados e o tratamento
de erros. Cite as URLs .md que sustentam o plano, separe recursos confirmados de
lacunas e termine com uma ordem de implementação em etapas. Nesta primeira
resposta, não escreva a aplicação inteira: quero revisar e aprovar o plano.

Escolha o tipo de integração

Fluxo recomendado para vibe coding

Primeira chamada com API key

Segurança obrigatória

Escolha um prompt oficial

Criar uma aplicação nova

Migrar do API Legado

Prompt para uma aplicação nova

Continue daqui

On this page