Documentação
Salão e mesas
Mesas, históricos, chamados, caixa de leitura, métricas e reservas para integrações de restaurante.
Estas rotas são somente leitura: consultam mesas, sessões, chamados, caixas, reservas e eventos já registrados pela operação do restaurante. Nenhuma delas cria ou altera reservas.
Autorização e restaurante
Use um access token de integração obtido por OAuth de restaurante ou pela troca de uma API key. O perfil pessoal de garçom, sessões humanas e a credencial RPA da Store não concedem acesso a estas rotas. Se o token alcançar mais de um restaurante, envie restaurant_id na query; todos os recursos e relações são validados nesse contexto.
| Escopo | Permite |
|---|---|
tables:read | Consultar mesas, ocupação, consumo atual e atualizações em tempo real. |
table-assistance:read | Consultar chamados de atendimento das mesas e seus estados. |
cash-register:read | Consultar caixas em aberto e seus saldos. |
reservations:read | Consultar reservas das mesas, horários, clientes e estados. |
reports:tables:read | Consultar faturamento, ocupação, permanência e indicadores por mesa. |
Históricos usam table-sessions:read, independentemente de tables:read. Credenciais e instalações existentes precisam selecionar os novos escopos e obter novo token/consentimento; eles não são adicionados automaticamente.
Rotas
| Método | Caminho | Escopo |
|---|---|---|
| GET | /v1/tables | tables:read |
| GET | /v1/tables/history | table-sessions:read |
| GET | /v1/tables/:tableId/history | table-sessions:read |
| GET | /v1/counter-mode/history | table-sessions:read |
| GET | /v1/table-assistance | table-assistance:read |
| GET | /v1/cash-register | cash-register:read |
| GET | /v1/tables/:tableId/reservations | reservations:read |
| GET | /v1/reservations/:reservationId | reservations:read |
| GET | /v1/tables/metrics | reports:tables:read |
| GET | /v1/tables/events | tables:read, com famílias adicionais filtradas |
As operações e schemas completos estão na referência. A consulta de caixa lista apenas caixas abertos, com valores decimais em strings; cashier_id seleciona um caixa específico. Não há movimentação por PUT /v1/cash-register nem rota salon-settings.
Mesas e qualidade dos dados
A listagem exclui mesas de delivery e cardápio QR. A ocupação considera sessões abertas/em fechamento e reservas em atendimento; uma reserva futura não ocupa fisicamente a mesa. O consumo atual e o último pedido válido aparecem em active_sessions, sem somar pagamentos outra vez.
capacity vem exclusivamente dos lugares cadastrados no inventário de reservas (capacity_source: "reservation_inventory"), quando há esse vínculo. Não representa um novo cadastro físico do salão. area é null porque não há fonte confirmada. O status cleaning só é apresentado quando já registrado na fonte; a API não cria transições de higienização nem permite editar esses atributos.
Históricos retornam o resumo do atendimento, contagem de comandas e referências de transferências. Detalhes de itens e pagamentos continuam nas consultas existentes de table-sessions. Balcão exige classificação explícita balcony; não é inferido por nome ou ausência de mesa. Chamados não expõem telefone ou dados do comprador. Se o número da mesa não tiver uma associação física única, o chamado não é atribuído arbitrariamente a outra mesa.
Períodos e paginação
Históricos, chamados, reservas por mesa e métricas exigem start_date e end_date em ISO 8601 com timezone. Use intervalo positivo de até 31 dias, com início inclusivo e fim exclusivo. Métricas rejeitam fim futuro. Históricos aceitam table_type=table|lounge|balcony; reservas aceitam status=pending_payment|confirmed|checked_in|finished|cancelled|no_show|expired.
As listas paginadas usam limit de 1 a 100 (padrão 50), ordenação crescente por ID e pagination.next.cursor. Preserve recurso, restaurante, período, limite e filtros ao reutilizar o cursor. Ele não representa um snapshot imutável do banco. O limite de segurança do estado atual é de 2.000 mesas, 100 sessões por mesa e 10.000 sessões ativas; ultrapassá-lo retorna 422.
curl 'https://public-api.takeat.app/v1/tables/history?restaurant_id=<ID>&start_date=2026-11-15T00:00:00Z&end_date=2026-11-16T00:00:00Z&limit=50' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'Métricas e mapa de calor
A resposta inclui generated_at, período, time_zone, definition_version: 1, resumo e detalhes por mesa. Envie a janela de um turno para calcular os indicadores daquele turno. Dinheiro usa strings decimais; ocupação e aproveitamento usam razões, de modo que 0.75 significa 75%.
| Indicador | Definição v1 |
|---|---|
revenue | Consumo líquido persistido (total_price) dos atendimentos encerrados no período, sem adicionar taxa de serviço, gorjeta, entrega ou pagamentos. |
ticket_per_person | Receita / pessoas registradas nos mesmos atendimentos. |
revpash | Receita / assento-horas disponíveis durante o funcionamento. |
average_ticket | Receita / atendimentos encerrados. |
turnover | Ciclos de ocupação liberados no período; sessões simultâneas formam um único ciclo. |
average_stay_seconds | Duração média dos atendimentos encerrados. |
occupancy | União dos intervalos ocupados, recortada pelo funcionamento / tempo disponível. |
seat_utilization | null: o legado não mantém histórico da quantidade de pessoas ao longo da sessão. |
bill_count | Comandas individuais elegíveis; attendance_count informa atendimentos separadamente. |
idle_seconds | Agora menos o último pedido válido de uma mesa ativa; sem pedido, null. |
Divisor zero, horários ausentes/inválidos, capacidade alterada no período e pessoas não registradas produzem null e motivos em unavailable_reasons. Capacidade e horários usam a versão atual dos cadastros existentes somente quando seus timestamps de criação e atualização antecedem a janela. Isso não reconstrói versões excluídas do horário de funcionamento. seat_utilization fica sempre null, com people_history_unavailable; o valor final de pessoas ainda pode alimentar o ticket por pessoa.
Ocupação, giro e permanência usam os intervalos registrados de início/fim da sessão. O legado não mantém o histórico completo de fechamentos e reaberturas intermediários; esses intervalos não são reconstruídos. Transferências registradas tornam as métricas afetadas indisponíveis quando não há atribuição temporal completa. O resumo retorna null para um total que contenha valores indisponíveis. Não são criadas tabelas de captura, auditoria ou triggers.
Consultar reservas existentes
GET /v1/tables/:tableId/reservations lista as reservas já vinculadas àquela mesa no legado; GET /v1/reservations/:reservationId retorna os detalhes e a situação de pagamento persistida. Reservas ainda sem mesa não recebem alocação antecipada por esta integração. O período da lista seleciona o início dos horários de reserva. Os horários externos são instantes com timezone, convertidos da convenção local já usada pelo motor legado.
Criação, remarcação e cancelamento continuam nos fluxos e endpoints legados existentes: POST /restaurants/reservations, PATCH /restaurants/reservations/:id/reschedule e POST /restaurants/reservations/:id/cancel, com a autenticação e as regras já adotadas por essa API. Um access token OAuth desta integração não autoriza esses endpoints. A Nova API V1.0 não tem rotas de escrita de reservas.
SSE
Conecte com Accept: text/event-stream e o mesmo Bearer usado no REST. No navegador, use um cliente baseado em fetch que suporte esse header; não coloque o token na URL.
curl --no-buffer 'https://public-api.takeat.app/v1/tables/events?restaurant_id=<ID>' \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'Após autorizar e confirmar a assinatura Redis, o servidor envia tables.snapshot. Avisos tables.changed pedem releitura do estado. metrics.invalidate, assistance.changed, reservations.changed e cash-register.changed exigem seus próprios escopos. Os eventos não contêm payloads operacionais brutos nem dados de clientes.
Há heartbeat a cada 15 segundos, revalidação periódica de autorização e encerramento na expiração do token. Invalidações são agrupadas; a reconciliação de 60 segundos recupera sinais perdidos. O canal é transitório e não oferece replay por Last-Event-ID. Após queda, resync_required, cliente lento ou desconexão Redis, reconecte com backoff e recarregue o snapshot e as consultas autorizadas. A latência e os timeouts do proxy precisam ser homologados no ambiente de destino.
Erros e exemplos
Erros usam o envelope V1 { statusCode, message, key }. Códigos relevantes: invalid_salon_query, invalid_salon_cursor, invalid_salon_period, salon_table_not_found, salon_reservation_not_found, salon_cash_register_not_found e salon_too_large. SSE pode responder 503 quando seu barramento não estiver disponível.
A coleção Postman de salão e a pasta Salon do Bruno incluem os 10 contratos GET, todos somente de leitura, incluindo o stream SSE.
SSE limita cada instância a 1.000 conexões, com até 100 por restaurante e 10 por cliente/restaurante. O excesso retorna 429; reconecte com backoff.