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 app público da Takeat Store 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 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://public-api.takeat.app/mcp   (MCP unificado com OAuth)

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
• Autenticação de apps para a Takeat Store
• 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.
• A V1 mantém os envelopes existentes. As novas listagens em /v2 usam { data, pagination }; continue com pagination.next até has_more=false. Na V2, metadados financeiros ficam em meta, inclusive os totais do período.
• A V1 de comandas mantém o array completo, o limite de três dias inteiros e [] para períodos invertidos. Na /v2/table-sessions, use limit (padrão 50, máximo 100) e cursor, sem limite de dias. Veja paginação e migração gradual.
• 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.
• GET /v1/table-sessions/:sessionId consulta uma comanda aberta ou fechada pelo ID interno, com o mesmo objeto da listagem e sem intervalo de datas. IDs ausentes, de outra loja ou fora da marca selecionada retornam 404 table_session_not_found.
• A listagem aceita motoboy_id, combinado com brand_id e as datas obrigatórias, e retorna as sessões atribuídas ao entregador com todos os pedidos aninhados. IDs sem correspondência retornam [] na V1 e uma página vazia na V2.
• Listagem e detalhe incluem motoboy_id e motoboy: { id, name, phone }. Os contatos são anuláveis; ambos os campos de entregador retornam null para vínculos ausentes ou contraditórios, inclusive de outra loja. Atribuições históricas permanecem legíveis para entregadores arquivados.
• Listagem V1, listagem V2 e detalhe retornam o objeto intended_payments, inclusive quando payments está vazio. Ele concentra payment_method, change_for, is_prepaid e ifood_paid. A forma escolhida tem id, name, keyword, method e brand; ela não comprova recebimento. Os sinalizadores são os valores originais persistidos, sem inferir pagamento pelo nome da forma.
• No checkout nativo, intended_payments.change_for: "100.00" significa troco para R$ 100,00, não R$ 100,00 de troco. O campo projeta user_change do banco: null e "0.00" são preservados. Integrações históricas podem gravar esse valor com outra convenção; a API mantém o valor da origem. O troco efetivamente devolvido continua em payments[].change.
• session_number é a sequência anulável da comanda no restaurante, distinta do ID interno e de attendance_password.
• 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.

A gestão de fichas técnicas usa novos contratos /v1/inventory e rotas technical-sheet de produtos/complementos. As listagens legadas de estoque continuam inalteradas.

Cobrança na entrega

Veja o guia de pagamentos na entrega para os tipos de cada campo, as regras de maquininha e os cuidados com o cálculo de troco.

A intenção de pagamento aparece na própria comanda; não é necessário existir um registro em payments para consultar o que foi combinado com o cliente. Exemplo sintético de um trecho retornado por GET /v2/table-sessions ou GET /v1/table-sessions/:sessionId:

{
  "is_delivery": true,
  "with_withdrawal": false,
  "total_delivery_price": "87.80",
  "intended_payments": {
    "payment_method": {
      "id": 12,
      "name": "Dinheiro",
      "keyword": "dinheiro",
      "method": null,
      "brand": null
    },
    "change_for": "100.00",
    "is_prepaid": false,
    "ifood_paid": false
  },
  "payments": []
}

Nesse pedido do checkout nativo, o cliente informou que entregará R$ 100,00 para uma cobrança de R$ 87,80; o troco a preparar seria R$ 12,20. Esses valores ainda não são um recebimento. Para cartão na entrega, a forma pretendida identifica o instrumento e a bandeira, quando informados, permitindo orientar o entregador. A presença dessa forma não significa, sozinha, que o cartão será cobrado na entrega: considere também o canal, os sinalizadores de pré-pagamento e os pagamentos registrados.

Uma forma ausente é null, inclusive para sessões antigas; não a deduza a partir do primeiro pagamento ou de texto livre. Os novos campos são de leitura e usam os mesmos guards de restaurante/marca e table-sessions:read. Não alteram o cálculo financeiro nem criam pagamentos ou novas permissões.

Descoberta de funcionalidades

GET /v1/restaurants/features exige restaurants:read no OAuth ou sessão do próprio restaurante. Publica somente as 26 capacidades exportáveis, agrupadas em operation, payments, offline, delivery e additional_features. available_features continua uma lista plana e fica vazia para contas inativas. Consulte o guia completo. Adicione a permissão explicitamente ao app ou chave; apps existentes exigem novo consentimento.

Clientes vinculados à loja

Para uma base com identidade Takeat estável e dados de compras, use GET /v1/clients, com a nova permissão clients:read. A população são buyers vinculados, inclusive importados/sem compras; pessoas exclusivas do Clube não entram. A rota legada GET /v1/clube/clients continua disponível com clube:read. Chaves e instalações existentes precisam selecionar a nova permissão e emitir tokens; apps OAuth precisam do consentimento correspondente.