FAQ - Perguntas Frequentes¶

Respostas para as perguntas mais comuns sobre a integração.

Geral¶

Como a integração funciona?¶

1. Nayax envia webhook com transação
2. Sistema salva no banco e cria job
3. Worker processa job assincronamente
4. Dados são transformados (Nayax → Saipos)
5. Pedido é enviado para API Saipos

É em tempo real?¶

Quase. O webhook é recebido instantaneamente, mas o processamento é assíncrono (acontece em segundos).

Posso usar em produção?¶

Sim! O sistema usa padrões confiáveis (Outbox Pattern, retry com backoff, DLQ).

Webhook¶

Como configurar o webhook no Nayax?¶

1. Acesse painel administrativo Nayax
2. Configure URL: https://seu-dominio.com/webhooks/nayax
3. Método: POST
4. Header: Authorization: Bearer SEU_TOKEN

Como testar o webhook?¶

curl -X POST http://localhost:3000/webhooks/nayax \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionKey": "test-'$(date +%s)'",
    "transactionNumber": "TEST123",
    "isTestTransaction": true,
    "storeCode": "LOJA001",
    "totalAmount": 10.00,
    "items": [{"itemCode":"PROD001","itemName":"Teste","quantity":1,"price":10.00}],
    "payments": [{"tenderType":1,"amount":10.00}]
  }'

O webhook pode ser chamado várias vezes?¶

Sim, o sistema é idempotente. O mesmo transactionKey não cria pedidos duplicados (exceto em modo teste).

Jobs¶

Como ver jobs pendentes?¶

SELECT COUNT(*) FROM "OutboxJob" WHERE status = 'PENDING';

Ou no Prisma Studio:

npx prisma studio

Como reprocessar um job?¶

UPDATE "OutboxJob"
SET 
  status = 'PENDING',
  "nextRunAt" = NOW(),
  attempts = 0,
  "lastError" = NULL
WHERE id = 'job_id';

O que significa cada status?¶

Quanto tempo leva para processar?¶

• Jobs PENDING: processados a cada 20 segundos
• Jobs FAILED: retentados com backoff (30s, 2min, 5min, 15min, 30min, 60min)

Jobs em DLQ podem ser reprocessados?¶

Sim! Depois de corrigir o problema:

UPDATE "OutboxJob"
SET status = 'PENDING', "nextRunAt" = NOW(), attempts = 0
WHERE id = 'job_id';

Autenticação¶

Quais métodos de autenticação são suportados?¶

1. Bearer Token JWT - Para usuários
2. Bearer Token Nayax - Para webhook Nayax
3. Basic Auth - Email:senha em base64
4. Credentials no Body - email + senha

Como gerar um JWT token?¶

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"admin123"}'

Token JWT expira?¶

Sim, após 7 dias por padrão. Configure via JWT_EXPIRES_IN.

Saipos¶

Qual ambiente usar?¶

• Development/Staging: https://homolog-order-api.saipos.com
• Production: https://order-api.saipos.com

Como obter credenciais Saipos?¶

Entre em contato com o suporte Saipos para obter: - idPartner - secret - cod_store

Erro "order_id já existe"?¶

Use isTestTransaction: true em testes. O sistema adiciona timestamp automaticamente.

Como mapear formas de pagamento?¶

O mapeamento é automático via tenderType:

Ver lista completa em nayax-to-saipos.mapper.ts.

Banco de Dados¶

Qual banco usar?¶

PostgreSQL 14+ é obrigatório (usa recursos específicos do Postgres).

Como fazer backup?¶

pg_dump -U postgres nayax_saipos > backup.sql

Como restaurar backup?¶

psql -U postgres nayax_saipos < backup.sql

Posso usar outro ORM?¶

O projeto usa Prisma. Trocar requer refatoração significativa.

Performance¶

Quantos jobs posso processar?¶

O worker processa 20 jobs por vez a cada 20 segundos = ~60 jobs/minuto por instância.

Como aumentar throughput?¶

1. Escalar horizontalmente (múltiplas instâncias)
2. Aumentar lote de jobs processados
3. Reduzir intervalo do cron

Jobs estão acumulando, o que fazer?¶

-- Ver queue depth
SELECT COUNT(*) FROM "OutboxJob" WHERE status = 'PENDING';

-- Se > 100, considerar escalar

Soluções: - Adicionar mais workers - Otimizar queries (adicionar índices) - Aumentar recursos (CPU/RAM)

Desenvolvimento¶

Como rodar localmente?¶

npm install
cp .env.example .env
# Editar .env
npx prisma migrate deploy
npm run start:dev

Como adicionar novo campo?¶

1. Atualizar schema.prisma
2. Criar migration: npx prisma migrate dev
3. Atualizar mapper
4. Atualizar DTOs

Como debugar?¶

# Logs detalhados
LOG_LEVEL=debug npm run start:dev

# Ver logs
tail -f logs/app.log | grep -E "ERROR|WARN"

Multi-tenant¶

Como adicionar novo restaurante?¶

INSERT INTO "Restaurant" (
  id, name, slug, 
  "codeStoreNayax", "codeStoreSaipos",
  "saiposIdPartner", "saiposSecret"
) VALUES (
  gen_random_uuid(),
  'Novo Restaurante',
  'novo-restaurante',
  'LOJA002',
  'LOJA_SAIPOS_002',
  'partner_id',
  'secret'
);

Como vincular usuário a restaurante?¶

INSERT INTO "UserRestaurant" (id, "userId", "restaurantId", role)
VALUES (gen_random_uuid(), 'user_id', 'restaurant_id', 'MANAGER');

Quais roles existem?¶

Erros Comuns¶

"Database connection failed"¶

Verificar DATABASE_URL no .env e se PostgreSQL está rodando.

"Port 3000 already in use"¶

lsof -i :3000
kill -9 <PID>

"Prisma Client not generated"¶

npx prisma generate

"Migration failed"¶

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

# Ou resolve conflito manualmente

Monitoramento¶

Como monitorar jobs?¶

-- Dashboard de status
SELECT 
  status,
  COUNT(*) as count,
  ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) as percentage
FROM "OutboxJob"
GROUP BY status;

Como ver taxa de sucesso?¶

SELECT 
  COUNT(*) FILTER (WHERE status = 'SENT') as success,
  COUNT(*) FILTER (WHERE status IN ('FAILED', 'DLQ')) as failed,
  ROUND(
    COUNT(*) FILTER (WHERE status = 'SENT')::numeric / 
    COUNT(*)::numeric * 100, 
    2
  ) as success_rate
FROM "OutboxJob";

Como configurar alertas?¶

Use ferramentas como: - Sentry - Para erros - DataDog - Para métricas - PagerDuty - Para alertas

Deploy¶

Como fazer deploy?¶

# Build
npm ci --only=production
npm run build

# Migrations
npx prisma migrate deploy

# Start
pm2 start dist/main.js --name nayax-saipos

Como fazer rollback?¶

pm2 stop nayax-saipos
git checkout versao-anterior
npm ci
npm run build
pm2 restart nayax-saipos

Preciso rodar migrations em produção?¶

Sim! Sempre rode npx prisma migrate deploy antes de iniciar a aplicação.

Segurança¶

Como alterar senha admin?¶

curl -X PATCH http://localhost:3000/users/me/password \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"currentPassword":"admin123","newPassword":"nova_senha"}'

JWT_SECRET deve ser forte?¶

Sim! Gere com:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Devo commitar .env?¶

NUNCA! O .env já está no .gitignore.

Suporte¶

Onde encontrar ajuda?¶

• Troubleshooting
• Debug
• Slack: #nayax-saipos
• Email: suporte@example.com

Como reportar bug?¶

1. Ver logs: tail -f logs/app.log
2. Exportar dados do job/evento
3. Criar issue no GitHub com logs

Posso contribuir?¶

Sim! Veja guia de contribuição no README.

Próximos Passos¶

• Problemas Comuns
• Debug
• Glossário