Instalação¶

Guia completo de instalação da integração Nayax → Saipos.

Pré-requisitos¶

Antes de começar, certifique-se de ter instalado:

Software Obrigatório¶

Software	Versão Mínima	Recomendada	Como Verificar
Node.js	18.x	20.x	`node --version`
npm	8.x	10.x	`npm --version`
PostgreSQL	14.x	15.x	`psql --version`
Git	2.x	Latest	`git --version`

Opcional (mas recomendado)¶

Docker - Para rodar PostgreSQL em container
pgAdmin - Interface gráfica para PostgreSQL
Postman/Insomnia - Para testar APIs

Instalação do Node.js¶

Linux (Ubuntu/Debian)¶

# Usando NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verificar instalação
node --version
npm --version

macOS¶

# Usando Homebrew
brew install node@20

# Verificar instalação
node --version
npm --version

Windows¶

Baixe o instalador: nodejs.org
Execute o instalador
Verifique no terminal:

node --version
npm --version

Instalação do PostgreSQL¶

Linux (Ubuntu/Debian)¶

# Adicionar repositório PostgreSQL
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# Instalar
sudo apt-get update
sudo apt-get install postgresql-15 postgresql-contrib-15

# Iniciar serviço
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Verificar
sudo -u postgres psql -c "SELECT version();"

macOS¶

# Usando Homebrew
brew install postgresql@15

# Iniciar serviço
brew services start postgresql@15

# Verificar
psql --version

Windows¶

Baixe o instalador: postgresql.org/download/windows
Execute o instalador
Anote a senha do usuário postgres

Docker (recomendado para desenvolvimento)¶

# Criar container PostgreSQL
docker run -d \
  --name postgres-nayax \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=nayax_saipos \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres:15

# Verificar
docker ps
docker exec -it postgres-nayax psql -U postgres -d nayax_saipos

Clonando o Repositório¶

# Clone o repositório
git clone https://github.com/seu-usuario/nayax-saipos.git

# Entre no diretório
cd nayax-saipos

# Verifique a estrutura
ls -la

Instalando Dependências¶

# Instalar dependências do projeto
npm install

# Ou com cache limpo (se tiver problemas)
npm ci

Problemas Comuns na Instalação¶

Erro: "EACCES: permission denied"¶

# Solução: Configurar npm para não usar sudo
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Erro: "node-gyp rebuild failed"¶

# Linux/Mac
npm install -g node-gyp
npm install

# Windows - instale build tools
npm install -g windows-build-tools

Erro: "Prisma Client generation failed"¶

# Regenerar Prisma Client
npx prisma generate

Configuração do Banco de Dados¶

Criar Database¶

# Conectar ao PostgreSQL
psql -U postgres

# Criar database
CREATE DATABASE nayax_saipos;

# Criar usuário (opcional)
CREATE USER nayax_user WITH PASSWORD 'sua_senha_forte';
GRANT ALL PRIVILEGES ON DATABASE nayax_saipos TO nayax_user;

# Sair
\q

Verificar Conexão¶

# Testar conexão
psql -U postgres -d nayax_saipos -c "SELECT 1;"

Configuração de Variáveis de Ambiente¶

# Copiar arquivo de exemplo
cp .env.example .env

# Editar com suas configurações
nano .env
# ou
code .env

Arquivo .env mínimo:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/nayax_saipos?schema=public"

# JWT
JWT_SECRET="sua_chave_secreta_jwt_muito_forte"
JWT_EXPIRES_IN="7d"

# Server
PORT=3000
NODE_ENV=development

# Nayax
NAYAX_BEARER_TOKEN="seu_token_nayax"

# Saipos
SAIPOS_BASE="https://homolog-order-api.saipos.com"

Segurança

Nunca commite o arquivo .env no Git. Ele já está no .gitignore.

Executar Migrations¶

# Executar todas as migrations
npx prisma migrate deploy

# Ou em desenvolvimento (cria migration se necessário)
npx prisma migrate dev

Verificar Schema¶

# Ver schema atual
npx prisma db pull

# Abrir Prisma Studio (interface gráfica)
npx prisma studio

Seed do Banco (Opcional)¶

# Popular com dados iniciais
npm run seed

# Ou manualmente
npx prisma db seed

O seed cria:

Usuário admin padrão
Configurações iniciais
Restaurante de exemplo (desenvolvimento)

Verificar Instalação¶

# Compilar TypeScript
npm run build

# Rodar testes
npm test

# Iniciar em modo desenvolvimento
npm run start:dev

Endpoints de Health Check¶

# Verificar se API está respondendo
curl http://localhost:3000/health

# Resposta esperada:
# {"status":"ok","timestamp":"2025-01-15T10:00:00.000Z"}

Estrutura de Arquivos¶

Após instalação, você terá:

nayax-saipos/
├── dist/                   # Build (após npm run build)
├── node_modules/           # Dependências
├── prisma/
│   ├── migrations/         # Migrations do banco
│   ├── schema.prisma       # Schema Prisma
│   └── seed.ts            # Dados iniciais
├── src/
│   ├── auth/              # Autenticação
│   ├── webhooks/          # Controllers de webhooks
│   ├── jobs/              # Processador de jobs
│   ├── restaurant/        # Gestão de restaurantes
│   ├── user-restaurant/   # Gestão de usuários
│   └── main.ts            # Entry point
├── test/                  # Testes
├── .env                   # Variáveis (criar)
├── .env.example           # Template
├── package.json           # Dependências
└── tsconfig.json          # Config TypeScript

Instalação em Ambientes¶

Desenvolvimento¶

# Instalar com dev dependencies
npm install

# Rodar em modo watch
npm run start:dev

# Logs verbose
DEBUG=* npm run start:dev

Staging/Homologação¶

# Instalar apenas production dependencies
npm ci --only=production

# Rodar migrations
npx prisma migrate deploy

# Build
npm run build

# Iniciar
npm run start:prod

Produção¶

# Instalar
npm ci --only=production

# Migrations
npx prisma migrate deploy

# Build otimizado
NODE_ENV=production npm run build

# Iniciar com PM2
pm2 start dist/main.js --name nayax-saipos
pm2 save

Instalação com Docker¶

Docker Compose¶

# docker-compose.yml
version: "3.8"

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: nayax_saipos
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    build: .
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/nayax_saipos
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules

volumes:
  pgdata:

# Iniciar tudo
docker-compose up -d

# Ver logs
docker-compose logs -f app

# Parar
docker-compose down

Verificação Final¶

Execute todos os comandos para garantir que está tudo funcionando:

# 1. Verificar versões
node --version    # >= 18.x
npm --version     # >= 8.x
psql --version    # >= 14.x

# 2. Verificar banco
psql -U postgres -d nayax_saipos -c "SELECT COUNT(*) FROM \"User\";"

# 3. Verificar build
npm run build

# 4. Rodar testes
npm test

# 5. Iniciar aplicação
npm run start:dev

# 6. Testar endpoint
curl http://localhost:3000/health

Troubleshooting¶

Porta 3000 já em uso¶

# Encontrar processo
lsof -i :3000
# ou
netstat -ano | findstr :3000

# Matar processo
kill -9 <PID>

# Ou mudar porta no .env
PORT=3001

Erro ao conectar no PostgreSQL¶

# Verificar se está rodando
sudo systemctl status postgresql
# ou
docker ps | grep postgres

# Verificar conexão
psql -U postgres -h localhost -p 5432

# Verificar DATABASE_URL no .env
echo $DATABASE_URL

Erro "Cannot find module"¶

# Limpar e reinstalar
rm -rf node_modules package-lock.json
npm install

# Regenerar Prisma
npx prisma generate

Migrations falhando¶

# Reset completo (CUIDADO: apaga dados)
npx prisma migrate reset

# Ou força migration
npx prisma migrate deploy --force

Próximos Passos¶

Instalação completa! Agora configure o ambiente:

Configuração

Recursos Adicionais¶

Troubleshooting