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
Copie e adapteImplementar API Key com access e refresh tokens
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.