Takeat
Versão da documentação
Prompts

Documentação

Implementar access e refresh tokens

Prompt para implementar e testar o ciclo de tokens da API Key: troca, renovação antecipada, rotação atômica e recuperação de falhas.

Use este prompt quando a escolha por API Key já está feita e você quer que o agente implemente a autenticação no backend: troca da chave em POST /oauth/token, access token de 900 segundos, renovação antecipada, rotação atômica do refresh token, concorrência e recuperação de falhas.

Acrescente somente o objetivo da integração e as operações desejadas, sem credenciais reais. Para um app instalável por vários restaurantes, use os prompts da Takeat Store.

O fluxo completo, com exemplos de requisição, está em API Key: access e refresh tokens.

Prompt

Prompt pronto para usar

Implementar API Key com access e refresh tokens

Copie e adapte
Implemente no backend deste projeto a integração com a Nova API V1.0 da
Takeat usando API key, access token e refresh token. Inspecione a arquitetura
e siga as convenções e os testes existentes, preservando alterações alheias.
O escopo é a autenticação e o cliente HTTP para as operações solicitadas;
não crie funcionalidades de negócio nem altere o fluxo para OAuth com PKCE.

Leia as fontes oficiais antes de implementar:
https://docs.takeat.app/llms.txt
https://docs.takeat.app/md/v1/autenticacao.md
https://docs.takeat.app/md/v1/api-key-tokens.md
https://docs.takeat.app/openapi-v1.yaml
Localize também o contrato .md de cada operação utilizada. Se houver
divergências ou algo não documentado, sinalize; não invente campos ou rotas.

Contrato de autenticação:
1. Base da API: https://public-api.takeat.app. O endpoint de tokens é
   POST /oauth/token, sem /v1, com application/x-www-form-urlencoded.
2. Primeira troca: grant_type=api_key e api_key=valor de TAKEAT_API_KEY,
   lido apenas no backend. scope é opcional e só pode restringir permissões.
   Não envie client_id, client_secret, Basic Auth ou Authorization.
   Não use client_credentials: esse grant não devolve refresh token.
3. Valide status e resposta: access_token, refresh_token, token_type=Bearer,
   expires_in e scope. Os campos HTTP são snake_case, mesmo que as variáveis
   internas sejam accessToken e refreshToken.
4. O access token expira em 900 segundos (15 minutos) por padrão. Use o
   expires_in retornado em cada troca, convertido de segundos para
   milissegundos, e o instante anterior ao envio da requisição para calcular
   expiresAt. Renove com margem de 60 segundos e confira o prazo antes de
   cada chamada. Reutilize o token; não troque a API key a cada requisição.
5. Nas rotas de dados /v1/*, envie Authorization: Bearer <access_token>.
   Nunca use API key ou refresh token como Bearer. Respeite escopos e o
   restaurante autorizado; envie restaurant_id apenas conforme o contrato
   e o vínculo da chave. Não use login/sessão de restaurante de terceiros.
6. Renovação: POST /oauth/token com apenas grant_type=refresh_token e
   refresh_token=valor atual, como formulário. Não envie api_key, client_id,
   client_secret, scope ou Authorization nessa chamada.
7. Cada refresh é de uso único e retorna outro par de tokens. Salve ambos,
   scope e a nova expiração atomicamente antes de liberar chamadas em espera.
   Persista com segurança para sobreviver a reinícios. O refresh não expira
   em 900 segundos: o padrão é 30 dias sem uso e 90 dias absolutos por família;
   isso não dispensa tratar expiração/revogação retornadas pelo servidor.

Concorrência e recuperação:
- Implemente uma única renovação em andamento por contexto de credenciais.
  No mesmo processo, compartilhe a promessa; com vários workers/instâncias,
  use coordenação compartilhada e releia os tokens depois de adquirir o lock.
  Nunca envie duas renovações com o mesmo refresh token. Reutilização revoga
  a família e invalida access tokens associados à chave.
- Em timeout, falha de rede, 5xx ou erro de persistência após um refresh,
  não repita cegamente o token antigo: ele pode ter sido consumido. Releia o
  estado e, se não houver novo par, pare e exponha recuperação controlada.
- Em 401 de dados, confira se outra chamada já renovou; caso contrário,
  coordene no máximo uma renovação. Repita a chamada original no máximo uma
  vez e somente se for seguro. Um segundo 401 deve encerrar a tentativa.
- Em invalid_grant, pare o ciclo de refresh. Uma nova troca com API key
  válida deve ser controlada, após verificar a causa; não contorne revogação
  ou suspeita de vazamento. Trate invalid_client como falha de credencial.
- Não renove por 403; verifique escopos/restaurante. Em 429, respeite
  Retry-After quando presente e use backoff com jitter e tentativas limitadas.
  Não repita escritas com resultado incerto nem invente idempotência.

Segurança e entrega:
- Não peça, leia, imprima ou cole segredos reais. Não abra arquivos .env.
  Use apenas nomes de variáveis e placeholders em .env.example; a configuração
  real será feita fora do chat. Nunca exponha tokens ao navegador, localStorage,
  URLs, Git, logs, analytics ou mensagens de erro. Criptografe tokens
  persistidos e mascare headers e campos sensíveis.
- Isole estado e locks por integração/ambiente/contexto autorizado. Não
  execute chamadas reais à Takeat; tk_test_ também pode acessar dados reais.
- Teste com HTTP simulado, relógio controlado e tokens fictícios: formulário
  inicial, Bearer correto, reaproveitamento antes da expiração, margem de
  renovação, rotação/persistência, reinício, concorrência, timeout ambíguo,
  invalid_grant, 401 sem loop, 403 sem refresh, 429 e segurança de escritas.
- Implemente, execute as verificações disponíveis e entregue um resumo dos
  arquivos alterados, configuração necessária, testes executados e limites
  de verificação. Não declare integração em produção validada por mocks.
Revise o contexto antes de enviar e nunca inclua credenciais reais.

Veja também

On this page