Migrar do API Legado

A Nova API V1.0 preserva o formato de resposta das rotas que foram replicadas, mas muda a origem, os caminhos e todo o ciclo de autenticação. Este guia ajuda a migrar uma integração que hoje consome webhook.takeat.app sem misturar credenciais nem substituir silenciosamente um recurso que ainda não existe.

Antes de alterar o código

Faça um inventário da integração atual:

• onde e como POST /public/api/sessions é chamado;
• onde e-mail, senha e JWT do API Legado são armazenados;
• quais rotas /api/v1/* são realmente consumidas;
• quais campos da resposta alimentam regras de negócio, cache, banco e UI;
• quais jobs, retries e limites de data existem;
• quais testes ou fixtures podem comprovar paridade;
• quantos restaurantes usam a integração e como seus dados são isolados.

Não envie credenciais reais a um agente para fazer esse levantamento. Ele pode inspecionar nomes de variáveis, chamadas HTTP e tipos, mas deve mascarar qualquer valor que pareça ser um segredo.

1. Escolha a nova forma de acesso

Em ambos os casos, as rotas /v1/* recebem um access token curto. A API Key não é enviada diretamente aos recursos, e um aplicativo OAuth público não usa client_secret.

A sessão do restaurante também é aceita nas rotas de dados para interfaces Takeat já autenticadas. Ela é uma credencial humana, vinculada ao restaurant_id assinado, e não substitui OAuth em integrações externas de backend.

2. Mapeie as rotas

A origem também muda de https://webhook.takeat.app para https://public-api.takeat.app. Nas rotas replicadas, remova /api do prefixo; não faça uma substituição global sem conferir a tabela.

O que permanece compatível

As rotas migradas mantêm serialização snake_case, valores monetários como strings com escala, relações aninhadas das comandas, limite de três dias e o comportamento UTC do API Legado.

O novo GET /v1/menu não é uma réplica de /api/v1/products: ele representa o cardápio publicado por canal, remove registros internos e agrupa preços em pricing, incluindo a base e o mínimo com escolhas obrigatórias em pricing.resolved. Adote-o como uma nova capacidade, não como substituição automática em uma migração de paridade.

3. Substitua a autenticação

Para uma API Key, a primeira troca usa grant_type=api_key e api_key; não envie client_id nem client_secret. Depois, renove com o refresh token atual e substitua-o atomicamente pelo novo valor retornado. Proteja a renovação contra duas execuções concorrentes.

4. Migre em etapas

5. Planeje limites e isolamento

Uma chave criada pelo restaurante começa com 10 requisições por minuto e no máximo 500 por dia. Evite duplicar chamadas ao API Legado e à V1.0 de forma contínua durante a migração; use amostras controladas, cache e backoff com jitter. Ao receber 429, respeite Retry-After.

Uma credencial de restaurante tem o restaurant_id inferido. Em uma integração multi-restaurante, vincule credenciais, tokens, cache, jobs e resultados à instalação correta. Nunca aceite um restaurant_id arbitrário vindo do cliente sem validar que ele pertence à credencial.

Checklist para o corte

• Todas as rotas usadas foram classificadas como compatíveis, novas ou sem equivalente.
• Cada rota V1.0 usa somente os escopos necessários.
• Access e refresh tokens ficam somente no backend e são mascarados nos logs.
• A rotação do refresh token é atômica e protegida contra concorrência.
• Teste e Produção mudam por configuração, sem condicionais espalhadas.
• Testes de contrato cobrem os campos realmente consumidos pelo produto.
• Erros 400, 401, 403 e 429 têm tratamento observável e seguro.
• O rollback foi testado antes de retirar a integração com o API Legado.
• E-mail, senha e JWT antigos foram removidos e revogados após o corte.

Prompt para migrar com um agente

Oi! Preciso da sua ajuda para migrar uma integração existente do API Legado
da Takeat para a Nova API V1.0.

Este projeto já consome https://webhook.takeat.app, faz login em
/public/api/sessions e pode chamar rotas sob /api/v1. A migração precisa
preservar o comportamento usado pelo produto e ter rollback. Não trate isso
como uma simples substituição global de URL ou prefixo.

A documentação oficial foi preparada para agentes:
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 Migrar do API Legado e Autenticação com API Key. Depois,
encontre no llms.txt o contrato Markdown do API Legado e o contrato V1.0 de cada
operação encontrada no código. Trate os contratos publicados como fonte da
verdade. Não invente equivalências, campos, escopos ou endpoints.

Comece com uma análise somente leitura do projeto. Localize:

- a criação e renovação da sessão do API Legado;
- as variáveis de ambiente pelo nome, sem revelar seus valores;
- todas as chamadas a webhook.takeat.app e /api/v1;
- os campos de resposta realmente consumidos;
- caches, jobs, retries, logs, testes e regras de isolamento por restaurante.

Classifique cada chamada em uma tabela com: uso atual, contrato do API Legado, rota
V1.0 correspondente, escopo exigido, compatibilidade de resposta, mudanças
necessárias e bloqueios. Para /inputs e /intermediaries, confira os escopos e
a paginação da referência V1.0. Não substitua
/products por /menu sem justificar a mudança de semântica.

A autenticação da migração é por API Key. Onde hoje o projeto envia e-mail e
senha para /public/api/sessions e guarda o JWT de 15 dias, ele passa a usar uma
chave tk_test_ ou tk_live_ criada no AI Builders. No backend, troque essa chave
em POST /oauth/token com grant_type=api_key e api_key, sem client_id e sem
client_secret, e use o access token retornado como Bearer nas rotas /v1. A API
Key nunca vai diretamente para /v1. Renove com grant_type=refresh_token usando
o refresh token atual, que é rotativo: substitua-o atomicamente pelo novo valor
e proteja a renovação contra execuções concorrentes. Não proponha OAuth
Authorization Code nem PKCE nesta migração.

Proponha uma migração incremental com cliente HTTP isolado, configuração para
alternar API Legado e V1.0, testes de contrato, amostras controladas de paridade,
canário, observabilidade e rollback. Considere os limites publicados, cache,
backoff e renovação atômica do refresh token. Cada restaurante deve permanecer
isolado em credenciais, tokens, banco, cache e jobs.

Segurança é inegociável: não me peça e-mail, senha, API Key, JWT, access token,
refresh token ou header Authorization. Não abra, imprima nem altere arquivos
.env que possam conter segredos. Se encontrar um possível segredo no código,
informe somente arquivo e localização com o valor totalmente mascarado e
recomende rotação.

Na primeira resposta, não modifique o código. Entregue o inventário, a matriz de
migração, os riscos e lacunas, os testes de paridade e uma sequência de etapas
com critérios de aceite e rollback. Cite as URLs .md oficiais que sustentam
cada decisão. Espere minha aprovação antes de implementar.

Continue daqui

• Contratos do API Legado
• Autenticação com API Key
• OAuth para aplicativos
• Contratos da Nova API V1.0

Diferenças de contrato a considerar

• Erros V1 usam { statusCode, message, key }; o legado em produção pode usar { status, message, errorType, payload }. Validações podem ter uma lista de mensagens. OAuth mantém { error, error_description }.
• Respostas de erro incluem o header X-Error-Id, também acessível por CORS. Envie esse ID ao suporte junto com método, rota, status e horário aproximado para localizar a falha nos logs. Não envie tokens, senhas ou API Keys.
• Intervalos invertidos de comandas retornam []. O limite usa dias inteiros: três dias mais uma fração são aceitos; quatro dias são rejeitados.
• bills[].buyer.delivery_address usa o destino selecionado pela sessão (buyer_delivery_address_id), sem fallback para o cadastro de endereços do comprador. Retorna null para sessões sem entrega, retirada, destino ausente ou pertencente a outro restaurante. Um comprador ausente continua null.
• details da comanda e do pedido e ifood_document preservam valores nulos.
• ean_codes no catálogo preserva null, [] e listas preenchidas. O menu normaliza códigos ausentes para [].
• O catálogo de complementos não promete ordem dos arrays. Compare os registros preservando duplicatas; não use a posição como identificador.
• Insumos e intermediários ordenam por nome e desempate por ID. Chaves antigas não recebem os novos escopos automaticamente; crie uma chave com os escopos necessários ou renove o consentimento após atualizar as permissões do app.

A documentação acompanha a versão de código. Confirme a revisão implantada antes do corte: publicação de contrato, isoladamente, não comprova que uma rota já está disponível no ambiente de destino.

Marcas e NF-e recebidas

Os caminhos legados GET /restaurants/brands, GET /restaurants/nfe-received e GET /restaurants/nfe-received/info/:id inspiram os novos contratos /v1/brands, /v1/nfe-received e /v1/nfe-received/info/:nfe_received_id. As respostas são agrupadas por assunto, não substituições transparentes. Consulte marcas e campos, autenticação e diferenças.