Radar KDS — API SaaS Multi-tenant de Pedidos

Arquitetura

Como tudo se conecta

Um único backend multi-tenant atende N restaurantes com isolamento absoluto por empresa_id, eventos em tempo real via Socket.io e credenciais criptografadas com AES-256-GCM.

Plataformas Externas Integradas

polling

GraphQL · POST /graphql
1×/min · multi-estabelecimento

webhook

HMAC-MD5 · POST /api/webhooks/99food
auth_token por loja · renovação auto

polling webhook

OAuth2 · HMAC-SHA256
/webhooks/ifood · polling 30s · multi-merchant

API Saas Radar KDS

Stack Node.js 22 Express 4 Socket.io 4 Prisma node-cron

🛡

Gateway de Segurança

Helmet CORS RateLimit JWT Auth inject empresa_id Zod validation

⚡

Camada de Transporte

REST /api/* Socket.io 4 WS 52+ endpoints rooms empresa_id /api/webhooks/* pedido_novo pedido_atualizado

🎛

Controllers

Autenticação Empresa Usuário KDS Webhook req → service → res formatado

⚙️

Serviços + Integrações

Autenticação Empresa Usuário Pedido KDS GrandChefServico NovenoveFoodServico IFoodServico

⏱

Jobs Agendados · node-cron

pollingGrandChef · 1×/min pollingIFood · 30s emite pedido_novo via WS sincroniza status

🗄

Camada de Dados

Prisma ORM MySQL 8.0 192.168.18.44:3306 AES-256-GCM isolamento empresa_id graceful shutdown

Painel de Administradores

Stack

React + MUI axios REST admin SaaS

Painel de Empresas

Stack

React + MUI axios REST multi-tenant

Painel KDS

Stack

React + MUI axios REST socket.io-client kanban RT

Multi-tenant · Tempo Real · AES-256-GCM · JWT Duplo · Socket.io · Polling Automático · Webhooks · Isolamento Total

Painel KDS

Kanban em tempo real

Visualização ao vivo dos pedidos de todas as plataformas integradas. Cada mudança de status, de Novo a Concluídos, aparece instantaneamente via Socket.io, sem nenhum refresh de página.

Novos

GC-1042

Entrega

João Silva

2×X-Burguer Especial

1×Batata Frita G

2×Refrigerante 350ml

R$ 52,90 há 3 min

99F-7821

Retirada

Maria Oliveira

1×Combo Família

1×Refrigerante 2L

R$ 87,50 há 7 min

Em Preparo

GC-0987

Entrega

Pedro Almeida

Pizza Calabresa G

2×Refrigerante Lata

R$ 68,90 há 14 min

Prontos

IFD-5534

Entrega

Ana Lima

2×Hambúrguer Artesanal

1×Milk Shake Oreo

R$ 73,80 há 22 min

Em Entrega

GC-1234

Entrega

Carlos Souza

1×Frango Grelhado + Acomp.

1×Suco de Laranja

R$ 38,90 há 30 min

Concluídos

99F-4421

Retirada

Lúcia Ferreira

2×Temaki Especial

1×Missô Soup

R$ 44,90 há 38 min

Cancelados

Nenhum pedido

Integrações

Três plataformas, um único painel

Pedidos chegam automaticamente via polling periódico e webhooks push, sem configuração manual e sem alternar entre apps.

Integração via polling GraphQL, a cada minuto o servidor autentica, consulta pedidos do dia e sincroniza novos ou alterados. Suporta múltiplos estabelecimentos por empresa.

Polling 1×/min GraphQL AES-256

Integração via webhook push (HMAC-SHA256) e polling de 30 s. Suporta múltiplos merchants por empresa com OAuth2 client credentials e renovação automática do token.

Webhook push OAuth2 Multi-merchant

Integração via webhook push com assinatura MD5. Cada loja tem seu próprio auth_token e renovado automaticamente antes da expiração.

Webhook push MD5 sign Multi-loja

Plataforma

Tudo que um SaaS KDS precisa

Infraestrutura robusta para múltiplos restaurantes com isolamento total de dados, autenticação em camadas e integrações bidireccionais.

Multi-tenant isolado

Um único backend atende N restaurantes. O empresa_id do JWT é filtro obrigatório em toda query e um operador nunca acessa dados de outra empresa.

Tempo real

Eventos Socket.io emitidos a cada novo pedido ou mudança de status o kanban é atualizado sem refresh. Suporte a som de notificação no cliente.

Integrações bidirecionais

Ao marcar um pedido como "Pronto" numa integração GrandChef, 99Food e iFood a API notifica a plataforma automaticamente e os pedidos recebem as mudanças de status em tempo real.

Credenciais criptografadas

As credenciais GrandChef, 99Food e iFood são armazenados com AES-256-GCM. Formato iv:authTag:cipher. Senhas bcrypt com salt rounds 12.

OpenAPI 3.1 completo

52+ endpoints documentados com exemplos, schemas Zod, validação em todas as rotas, filtros e paginação. Swagger UI com "Try it out" em /docs.

Segurança em camadas

Rate limit 200 req/min por IP, Helmet.js, CORS explícito, timing-safe na verificação de webhooks, refresh token com rotação silenciosa.

Fluxo de pedido

Como um pedido percorre a plataforma

Passo 1

Entrada do pedido

GrandChef é monitorado via cron, enquanto 99Food e iFood entregam pedidos por polling e webhook. Em todos os casos o pedido é criado com status novo e transmitido em tempo real via Socket.io.

Passo 2

Processamento na cozinha ou bar

Operador vê o card em Novos, clica "Iniciar Preparo" → preparo. Ao finalizar, clica "Pronto" → pronto. Cada transição tem ator e timestamp auditável.

Passo 3

Notificação à plataforma

O status pronto aciona a rota POST da API Radar KDS para a API do 99Food. A plataforma iFood recebe startPreparation, readyToPickup e dispatch conforme o status e, por fim, a plataforma GrandChef é atualizada via GraphQL UpdatePedido.

Segurança

Quatro camadas de autenticação

JWT com dois tokens (access 15 min + refresh 7 dias) e escopos isolados por tipo de usuário. O empresa_id extraído do token garante isolamento absoluto entre tenants.

Admin SaaS

Acesso total à plataforma. Cadastra empresas, configura integrações, gerencia todos os usuários e visualiza dados globais.

Endpoint POST /api/auth/admin/login

Admin de Empresa

Administrador de um tenant específico. Gerencia operadores e entregadores da própria empresa sem acesso ao painel SaaS.

Endpoint POST /api/auth/empresa-admin/login

Operador KDS

Acessa o kanban da cozinha. Atualiza status de pedidos, aciona notificações às plataformas e visualiza histórico da sessão.

Endpoint POST /api/auth/operador/login

Entregador KDS

Mesmo endpoint de operador, perfil entregador. Visualiza apenas pedidos atribuídos a si com escopo restrito automaticamente no servidor.

Endpoint POST /api/auth/operador/login

Referência

Endpoints principais

Visão rápida das rotas disponíveis. Para exemplos completos, schemas e "Try it out", acesse a documentação Swagger.

Autenticação — público

POST/api/auth/admin/loginpúblicoLogin admin SaaS

POST/api/auth/empresa-admin/loginpúblicoLogin admin de empresa

POST/api/auth/operador/loginpúblicoLogin operador / entregador

POST/api/auth/operador/refreshpúblicoRenovar token operador

GET/api/auth/admin/meadminDados do admin logado

Empresas — admin SaaS

GET/api/empresasadminListar empresas paginado

POST/api/empresasadminCriar empresa

PATCH/api/empresas/:idadminAtualizar empresa

DEL/api/empresas/:idadminExcluir empresa

PUT/api/empresas/:id/credenciais/grandchefadminConfig GrandChef

PUT/api/empresas/:id/credenciais/ifoodadminConfig iFood

PUT/api/empresas/:id/credenciais/99foodadminConfig 99Food

POST/api/empresas/:id/credenciais/ifood/testaradminTestar OAuth2 iFood

KDS — operador / entregador

GET/api/kds/pedidosoperadorKanban de pedidos ativos

PATCH/api/kds/pedidos/:id/statusoperadorTransição de status

PATCH/api/kds/pedidos/:id/entregadoroperadorAtribuir entregador

GET/api/kds/entregadoresoperadorListar entregadores ativos

GET/api/kds/ifood/motivos-cancelamentooperadorMotivos de cancelamento iFood

Pedidos — admin

GET/api/pedidosadminListar pedidos com filtros

GET/api/pedidos/:idadminDetalhe + itens + histórico

Dashboard

GET/api/dashboard/resumoadmin/opContadores da sessão

GET/api/dashboard/graficoadmin/opSérie temporal de pedidos

Webhooks — plataformas

POST/api/webhooks/ifoodHMACReceptor iFood

POST/api/webhooks/99foodMD5Receptor 99Food

Health

GET/healthpúblicoStatus + latência do banco

GET/api/usuariosadmin/opListar usuários da empresa

Abrir documentação completa no Swagger

A API por trás do Painel Radar KDS SaaS Multi-tenant em tempo real

Como tudo se conecta

Kanban em tempo real

Três plataformas, um único painel

Tudo que um SaaS KDS precisa

Como um pedido percorre a plataforma

Quatro camadas de autenticação

Endpoints principais