Aplicativos para garçons

O aplicativo escolhe Garçom no cadastro na Takeat Store. Esse perfil usa Authorization Code com PKCE S256 e uma autorização pessoal. A conta do garçom e sua loja acompanham o token. Dois garçons da mesma loja podem conectar e revogar o mesmo app de forma independente.

Os perfis têm permissões separadas. O perfil é imutável: registre clientes distintos quando precisar de outra identidade. Uma chave de API ou o fluxo client credentials não representa um garçom.

Autorizar e conectar

1. Cadastre um app com authorizationProfile: "waiter", redirects exatos e somente as permissões de leitura necessárias.
2. Gere state, code_verifier e code_challenge S256 novos e abra o portal Takeat com os parâmetros do fluxo OAuth.
3. O portal apresenta o login de garçom, sua conta, a loja e as permissões. O aplicativo não coleta a senha nem a sessão humana.
4. Valide o state no callback e troque o código por tokens em POST /oauth/token, com grant_type=authorization_code e o verifier original.
5. Use Authorization: Bearer <ACCESS_TOKEN> nas consultas abaixo. A emissão inclui authorization_profile: "waiter" e subject: { type, id, restaurantId }; preserve essa identidade ao armazenar a conexão.
6. Renove em POST /oauth/token, com grant_type=refresh_token, e substitua o refresh token a cada renovação. Use POST /oauth/revoke para revogar uma credencial. O garçom também pode desconectar o app no portal Takeat.

As ações de consentir, retomar e desconectar uma conta usam a sessão humana somente dentro do portal Takeat. Elas não fazem parte do catálogo de recursos de terceiros.

Consultas disponíveis

Todos os métodos desta seção são GET e não aceitam corpo. A loja vem da concessão pessoal: não envie restaurant_id, restaurantId, waiter_id ou outra identidade.

As listas de marcas, mesas, comandas e pedidos retornam { items, offset, limit, has_more }, ordenadas por ID, com páginas de até 100 itens. Envie offset=100 para a segunda página. O cardápio usa o contrato de catálogo publicado, com canal presencial, escolhas incluídas, somente itens disponíveis e sem dados fiscais. Seu único seletor opcional é brand_id, de uma marca ativa da loja.

As consultas de comandas e pedidos consideram o atendimento presencial ativo da loja do garçom, compartilhado entre os integrantes da equipe. Não são um histórico de vendas nem ficam restritas aos pedidos criados por aquele garçom. IDs ausentes, de outra loja ou fora desse atendimento recebem o mesmo 404.

Dados e limites de acesso

As respostas declaram os campos permitidos, inclusive nos objetos internos. Dados pessoais dos clientes, documentos, contatos, observações livres, chaves de sessão ou QR, senhas, configuração de terminais/impressoras e payloads de pagamentos ou provedores ficam fora dessa API. Os valores financeiros publicados se limitam aos preços dos itens e totais das comandas/contas ativas.

Este perfil não oferece criação ou alteração de pedidos, pagamentos, descontos, taxas, gorjetas, emissão fiscal, transferência ou encerramento de comandas, administração da equipe ou configuração operacional. As antigas rotas operacionais e suas permissões foram retiradas, inclusive o GET que cancelava uma pendência de POS. POST, PUT, PATCH e DELETE nos recursos acima retornam 404.

A API verifica a autorização e o vínculo ativo com a loja antes da consulta. Garçons removidos, protegidos ou movidos de loja perdem acesso. Permissões retiradas não continuam válidas em tokens antigos; o app precisa usar o catálogo atual e obter novo consentimento. Respostas usam Cache-Control: no-store.

A referência dos métodos separa Restaurante e Garçom, com categorias próprias. A coleção Postman de garçom contém somente as oito consultas e os exemplos de troca de código e renovação, sem credenciais salvas.