Autenticação de apps para a Takeat Store

Para autorizar várias lojas da mesma rede, siga o guia de integrações para multilojas.

Apps para a Takeat Store usam OAuth 2.0 Authorization Code com PKCE. O dono do restaurante entra no portal da Takeat, revisa as permissões e autoriza o app. O backend do parceiro troca o código de uso único por access e refresh tokens.

Use este fluxo para SaaS e produtos conectados a vários restaurantes. Para uma automação controlada por um único restaurante, prefira a API key.

Se você estiver preparando um produto para publicação, leia também Publicar na Takeat Store. Para criar ou atualizar a especificação técnica com um agente, use os prompts prontos para apps da Takeat Store.

Antes de começar

Cadastre o aplicativo com a Takeat e defina:

• nome, descrição e identidade que o restaurante verá no consentimento;
• ambiente de teste ou produção;
• uma ou mais redirect URIs HTTPS completas e exatas;
• somente os escopos necessários;
• limites de requisição adequados à integração.

Você receberá o client_id público e a URL do portal Entrar com a Takeat do ambiente. Use sempre o portal e a API do mesmo ambiente.

Fluxo resumido

sequenceDiagram
  participant App as App parceiro
  participant Portal as Entrar com a Takeat
  participant Owner as Dono do restaurante
  participant API as Nova API V1.0

  App->>App: Gera state + PKCE
  App->>Portal: Redirect com client_id e code_challenge
  Portal->>Owner: Login e consentimento
  Owner->>Portal: Autoriza os escopos
  Portal->>App: Callback com code + state
  App->>App: Valida state
  App->>API: POST /oauth/token + code_verifier
  API->>App: access_token + refresh_token
  App->>API: GET /v1/* com Bearer

1. Gere state e PKCE

Antes do redirect, gere e associe a uma tentativa de instalação:

• state: valor aleatório, opaco, de uso único e com expiração curta;
• code_verifier: valor aleatório Base64URL com 43 a 128 caracteres;
• code_challenge: SHA-256 do verifier codificado em Base64URL sem padding;
• code_challenge_method: sempre S256.

Exemplo em Node.js:

import { createHash, randomBytes } from "node:crypto";

const state = randomBytes(32).toString("base64url");
const codeVerifier = randomBytes(64).toString("base64url");
const codeChallenge = createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

Persista state, code_verifier, redirect URI e contexto do usuário no backend. Não envie o verifier na URL e não use um identificador previsível como state sem assinatura e expiração.

2. Redirecione para o consentimento

Monte a URL no backend e redirecione o navegador:

${TAKEAT_OAUTH_PORTAL_URL}
  ?client_id=tk_app_EXEMPLO
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &code_challenge=CHALLENGE_BASE64URL
  &code_challenge_method=S256
  &state=VALOR_OPACO

O portal autentica o dono, mostra o aplicativo e seus escopos e devolve o navegador à redirect_uri. O restaurante é derivado da sessão Takeat do dono; seu app não envia restaurant_id no consentimento.

3. Receba e valide o callback

Em caso de aprovação:

https://app.example.com/oauth/callback?code=tk_code_...&state=...

Antes de usar o code:

1. compare state em tempo constante com o valor associado à sessão;
2. rejeite valor ausente, divergente, expirado ou já consumido;
3. recupere o code_verifier no backend;
4. marque a tentativa como consumida;
5. trate error=access_denied como recusa do usuário, não como falha interna.

O código expira em aproximadamente cinco minutos e é de uso único. Nunca o registre nem o encaminhe ao frontend depois do callback.

4. Troque o código por tokens

Faça a requisição no backend com formulário URL encoded:

curl -X POST "https://public-api.takeat.app/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=tk_app_EXEMPLO" \
  --data-urlencode "code=tk_code_EXEMPLO" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=VERIFIER_ORIGINAL"

Resposta:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "tk_refresh_...",
  "scope": "products:read table-sessions:read",
  "restaurant": {
    "id": "123",
    "email": "contato@restaurante.example",
    "fantasy_name": "Restaurante Exemplo"
  }
}

O access_token atual dura 15 minutos. Vincule o refresh token à instalação do restaurante e armazene-o criptografado. Uma instalação não pode compartilhar tokens com outra.

O objeto restaurant identifica o restaurante conectado: id é uma string, email é o e-mail da conta do restaurante e fantasy_name é seu nome fantasia. Esses dados também retornam atualizados a cada renovação da instalação. Não são os dados pessoais do usuário que aprovou o acesso; não são incluídos na URL de callback nem nas claims do JWT. Fluxos com chave de API não retornam esse objeto.

5. Use o Bearer token

curl "https://public-api.takeat.app/v1/products" \
  -H "Authorization: Bearer $TAKEAT_ACCESS_TOKEN"

O restaurante é inferido da instalação. A API retorna 403 quando o token não possui o escopo exigido pela operação.

6. Renove e rotacione

curl -X POST "https://public-api.takeat.app/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=tk_app_EXEMPLO" \
  --data-urlencode "refresh_token=$TAKEAT_REFRESH_TOKEN"

Cada renovação devolve um novo refresh token. Substitua o valor antigo e o novo em uma única transação. Se duas instâncias tentarem renovar ao mesmo tempo, coordene a operação com lock ou compare-and-swap. Reutilizar um refresh token já consumido revoga toda a família de tokens da instalação.

7. Revogue ou desinstale

Revogue um access ou refresh token:

curl -X POST "https://public-api.takeat.app/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=tk_app_EXEMPLO" \
  --data-urlencode "token=$TAKEAT_TOKEN_TO_REVOKE" \
  --data-urlencode "token_type_hint=refresh_token"

A revogação é idempotente. Revogar o aplicativo ou negar novamente o consentimento encerra a instalação e impede novas renovações.

Escopos

Solicite o menor conjunto possível. A Takeat pode editar as permissões de um app já instalado, mantendo seu client_id. Adicionar ou remover qualquer escopo revoga as autorizações de todos os restaurantes conectados, os códigos pendentes e os access/refresh tokens existentes. Reordenar a mesma lista ou alterar somente os dados públicos do app não revoga o consentimento.

Ao receber 401 com o token antigo ou invalid_grant na renovação, ofereça Reconectar restaurante e inicie um novo fluxo com state e PKCE. Cada restaurante deve revisar e autorizar a lista atual; renovar o token não concede permissões novas. A autorização de um restaurante não reconecta os demais.

Um mesmo aplicativo pode solicitar permissões de restaurante e de multilojas. Após autenticar a conta, o portal consulta GET /oauth/consent-status e exibe applicable_scopes: restaurantes comuns podem aprovar as permissões de restaurante; matrizes verificadas também podem aprovar as de cardápio central, com seleção de filiais, marcas e confirmação de publicação quando aplicável. As permissões configuradas no aplicativo continuam sendo o limite máximo. O token contém somente as permissões efetivamente aprovadas para aquela conta; renová-lo não acrescenta permissões de multilojas a um restaurante comum.

O portal envia approved_scopes em POST /oauth/consent, vinculando a aprovação à lista applicable_scopes exibida para a conta conectada. Se o cadastro mudar com a página aberta, a API responde 409 invalid_scope: o portal atualiza a lista e espera outra aprovação explícita. Esse campo é do portal; o aplicativo parceiro continua usando o redirect padrão.

Erros comuns

Checklist de segurança

• Valide state e use PKCE S256 em toda autorização.
• Troque o código e armazene tokens somente no backend.
• Não coloque tokens, código ou verifier em cookies legíveis por JavaScript, local storage, analytics, URLs internas ou logs.
• Criptografe refresh tokens em repouso e separe-os por instalação.
• Mascare Authorization, code, code_verifier e refresh_token na observabilidade.
• Não cole credenciais reais em prompts de IA. Forneça apenas nomes de variáveis e exemplos fictícios.
• Revogue instalações abandonadas e trate reutilização de refresh token como incidente de segurança.

O formato desta explicação segue a progressão prática do guia público de OAuth do Cardápio Web — preparação, PKCE, autorização, callback, tokens, escopos, renovação, revogação e erros — adaptada aos contratos da Takeat.

Ferramentas

• Experimente Entrar com a Takeat
• Gerencie apps para a Takeat Store
• Publique seu app na Takeat Store
• Crie ou atualize sua especificação com um agente

Aplicativos para garçons

Escolha Garçom no cadastro do aplicativo para usar autorização OAuth pessoal com PKCE. O perfil do Client ID é fixo e tem cinco permissões de leitura, distintas das permissões de restaurante. As oito consultas públicas apoiam o atendimento presencial, sem alterações de pedidos, pagamentos ou configurações. A conta e a loja vêm do token; não envie restaurant_id. Consulte o guia de aplicativos para garçons e a referência separada por perfil.

Consultar avaliações

Avaliações do restaurante e do Clube: GET /v1/ratings exige ratings:read para todos os canais. Use channel=clube nesta mesma rota para filtrar as avaliações atuais do Clube integradas ao Takeat. As respostas organizam notas, comentários, critérios, nome e telefone do cliente quando disponíveis, contexto e resumo de todo o período.

Status e funcionalidades para tutoriais

GET /v1/restaurants/features exige restaurants:read no OAuth, ou sessão do próprio restaurante. Retorna o status da conta e apenas as capacidades de produto exportáveis, com available_features: [] para contas inativas. Consulte o guia de funcionalidades. A permissão deve ser adicionada explicitamente; apps existentes precisam revisar o consentimento e reconectar após a alteração de escopos.