QR Voucher Check-in

Sistema de check-in por QR Code desenvolvido para controle de uso de vouchers de refeição em ambiente hoteleiro.

O projeto foi criado como uma solução prática para um problema real: pessoas cadastradas em uma planilha apresentavam um QR Code na hora da refeição, e o sistema validava o voucher e registrava o uso para controle operacional.

Sobre o projeto

O QR Voucher Check-in é uma aplicação Node.js/Express integrada ao Google Sheets.

A solução permite validar vouchers por QR Code, consultar os dados em uma planilha e registrar o check-in quando o voucher é utilizado.

O projeto também chegou a ser testado em ambiente de deploy com Docker/EasyPanel.

Problema resolvido

Em um hotel, havia a necessidade de controlar quais pessoas já haviam utilizado seus vouchers de refeição.

A conferência manual podia gerar erros, retrabalho ou dificuldade para acompanhar o uso dos vouchers em tempo real.

A solução criada permite:

• manter os dados dos vouchers em uma planilha;
• validar o QR Code apresentado na refeição;
• registrar o uso do voucher;
• evitar reutilização indevida;
• centralizar o controle em uma base simples com Google Sheets.

Funcionalidades

• Validação de voucher por QR Code
• Integração com Google Sheets
• Registro de check-in
• Controle de status do voucher
• Interface de leitura/validação
• Autenticação básica para acesso à área de scan
• Configuração por variáveis de ambiente
• Suporte a execução local e via Docker

Tecnologias utilizadas

• Node.js
• Express
• Google Sheets API
• JavaScript
• HTML
• Docker

Fluxo de uso

1. Os dados das pessoas e vouchers são cadastrados em uma planilha.
2. Cada registro possui um token associado a um QR Code.
3. No momento da refeição, o QR Code é apresentado.
4. O sistema valida o código recebido.
5. Se o voucher for válido, o check-in é registrado.
6. A planilha é atualizada com status e data/hora de uso.

Estrutura do projeto

checkin/
├── scan/
│   └── index.html
├── server.js
├── package.json
├── Dockerfile
├── .dockerignore
├── .env.example
├── .gitignore
└── README.md

Variáveis de ambiente

Crie um arquivo .env com base no .env.example.

Variáveis obrigatórias para o fluxo real:

GOOGLE_SA_JSON_B64=
EVENTS_DB_SHEET_ID=

Variáveis operacionais recomendadas:

ADMIN_USER=
ADMIN_PASS=
EVENTS_DB_TAB=
PORT=3000

Descrição das variáveis

• GOOGLE_SA_JSON_B64: credencial da service account do Google codificada em Base64.
• EVENTS_DB_SHEET_ID: ID da planilha utilizada como base de dados.
• ADMIN_USER: usuário para acesso à área de scan.
• ADMIN_PASS: senha para acesso à área de scan.
• EVENTS_DB_TAB: aba da planilha utilizada pelo sistema.
• PORT: porta em que a aplicação será executada.

Nunca inclua credenciais reais, tokens, QR Codes reais ou dados de hóspedes no repositório.

Como executar localmente

Pré-requisitos

• Node.js instalado
• Conta de serviço configurada no Google Cloud
• Google Sheets API habilitada
• Planilha do Google Sheets configurada no formato esperado pelo projeto

Instalar dependências

npm install

Executar o projeto

PORT=3000 npm start

A aplicação ficará disponível em:

http://localhost:3000

Rotas principais

Página inicial

GET /

Retorna uma resposta simples para validar que o servidor está ativo.

Tela de scan

GET /scan

Área protegida por autenticação básica para leitura/validação de vouchers.

Check-in

POST /api/checkin

Endpoint responsável por receber o QR Code, validar o voucher e registrar o uso na planilha.

Execução com Docker

O projeto possui Dockerfile para execução em container, usado em testes de deploy.

Build da imagem

docker build -t checkin-qrcode .

Executar o container

docker run --rm -p 3000:80 --env-file .env checkin-qrcode

Para execução em Docker, ajuste a variável PORT conforme a porta esperada no container.

Validação realizada

Durante a revisão do projeto, foram validados os seguintes pontos:

• Sintaxe do server.js;
• Inicialização local do servidor;
• Resposta da rota /;
• Proteção da rota /scan;
• Rejeição de QR Code malformado em /api/checkin;
• Ausência de arquivos .env com credenciais reais;
• Ausência de service account real no repositório;
• Ausência de QR Codes reais ou dados reais de hóspedes;
• Criação de .env.example;
• Criação de .gitignore;
• Criação de .dockerignore.

O Dockerfile foi revisado, mas o build não foi validado localmente porque o Docker daemon não estava ativo no ambiente de teste.

Segurança

Este projeto pode depender de credenciais sensíveis e dados pessoais, dependendo da planilha utilizada.

Antes de publicar ou reutilizar este repositório, verifique se não existem:

• arquivos .env com valores reais;
• credenciais de service account;
• tokens reais;
• QR Codes reais;
• nomes reais de hóspedes ou participantes;
• planilhas reais expostas;
• arquivos compactados contendo dados sensíveis.

Status do projeto

Projeto desenvolvido como solução prática para uma necessidade real de controle operacional.

O repositório foi mantido como registro de um projeto aplicado, envolvendo validação por QR Code, integração com Google Sheets, controle de uso de vouchers e teste de deploy com Docker/EasyPanel.

Possíveis melhorias futuras

• Criar dashboard administrativo
• Exibir total de vouchers utilizados
• Adicionar logs de auditoria
• Melhorar feedback visual da tela de scan
• Adicionar testes automatizados
• Criar dados fictícios para demonstração pública
• Documentar o formato esperado da planilha
• Suportar múltiplos eventos, refeições ou unidades

Observação

Este repositório não deve conter dados reais de hóspedes, participantes, vouchers ou credenciais.

Para demonstração pública, utilize apenas dados fictícios.