Glossário¶

Termos e conceitos importantes da integração Nayax → Saipos.

A¶

API (Application Programming Interface)¶

Interface de programação que permite comunicação entre sistemas diferentes.

Async (Assíncrono)¶

Processamento que não bloqueia a execução principal, permitindo que o sistema continue responsivo.

B¶

Backoff¶

Estratégia de aumentar progressivamente o tempo entre tentativas de retry.

Exemplo: 30s → 2min → 5min → 15min → 30min → 60min

Basic Auth¶

Método de autenticação HTTP que envia credenciais (usuário:senha) codificadas em base64.

Authorization: Basic dXNlcjpwYXNzd29yZA==

Bearer Token¶

Token de autenticação enviado no header Authorization com prefixo "Bearer".

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

C¶

Cron¶

Sistema de agendamento de tarefas que executa comandos em horários específicos.

Exemplo: */20 * * * * * = a cada 20 segundos

CRUD¶

Create, Read, Update, Delete - operações básicas de persistência.

D¶

DLQ (Dead Letter Queue)¶

Fila para mensagens/jobs que falharam permanentemente e não devem ser retentados.

Quando vai para DLQ:

• Erros HTTP 400 (Bad Request)
• Erros HTTP 422 (Unprocessable Entity)
• Erros de validação permanentes

DTO (Data Transfer Object)¶

Objeto usado para transferir dados entre camadas da aplicação.

export class CreateRestaurantDto {
  name: string;
  slug: string;
  codeStoreSaipos: string;
}

E¶

Event¶

Evento de transação recebido do Nayax contendo todos os dados da compra.

Exponential Backoff¶

Estratégia de retry onde o tempo de espera dobra a cada tentativa.

G¶

Guard¶

Mecanismo do NestJS para controlar acesso a rotas (autenticação/autorização).

@UseGuards(JwtAuthGuard)

H¶

Hash¶

Resultado de função criptográfica unidirecional, usada para senhas.

const hash = await bcrypt.hash(password, 10);

I¶

Idempotency¶

Propriedade onde múltiplas execuções da mesma operação produzem o mesmo resultado.

Exemplo: Enviar o mesmo order_id múltiplas vezes não cria pedidos duplicados.

J¶

Job¶

Tarefa assíncrona a ser processada pelo JobsProcessor.

Estados: PENDING → PROCESSING → SENT/FAILED/DLQ

JWT (JSON Web Token)¶

Token de autenticação autocontido que contém informações do usuário.

{
  "sub": "user_id",
  "email": "user@example.com",
  "iat": 1516239022,
  "exp": 1516242622
}

L¶

Lock Otimista¶

Técnica de concorrência onde verificamos se o recurso mudou antes de atualizá-lo.

const updated = await prisma.outboxJob.updateMany({
  where: { id, status: "PENDING" },
  data: { status: "PROCESSING" },
});

if (updated.count === 0) {
  // Outro worker já processou
}

M¶

Mapper¶

Função que transforma dados de um formato para outro.

Exemplo: mapNayaxToSaipos() converte evento Nayax → pedido Saipos

Multi-tenant¶

Arquitetura onde uma única instância serve múltiplos clientes (restaurantes).

N¶

Nayax¶

Sistema de pagamentos para máquinas de vending e self-service.

NestJS¶

Framework Node.js progressivo para construir aplicações server-side eficientes.

O¶

ORM (Object-Relational Mapping)¶

Técnica de mapear objetos para tabelas relacionais.

Exemplo: Prisma ORM

Outbox Pattern¶

Padrão de design que garante processamento confiável de eventos usando uma tabela auxiliar.

graph LR
    A[Evento] --> B[Salva na DB]
    B --> C[Outbox Table]
    C --> D[Worker]
    D --> E[API Externa]

P¶

Payload¶

Dados enviados em uma requisição HTTP (body).

POS (Point of Sale)¶

Sistema de ponto de venda usado para gerenciar vendas e pedidos.

Prisma¶

ORM moderno para Node.js e TypeScript com type-safety.

R¶

Reaper¶

Processo que limpa jobs travados (stuck em PROCESSING).

Repository Pattern¶

Padrão que abstrai acesso a dados através de uma interface.

Retry¶

Tentativa automática de reprocessar uma operação que falhou.

Role¶

Papel/função de um usuário no sistema (OWNER, ADMIN, MANAGER, etc).

S¶

Saipos¶

Sistema POS (Point of Sale) para gestão de pedidos e vendas.

Seed¶

Dados iniciais inseridos no banco para desenvolvimento/testes.

npx prisma db seed

Slug¶

Identificador único amigável para URLs.

Exemplo: "Restaurante Exemplo" → "restaurante-exemplo"

T¶

tenderType¶

Código numérico do Nayax que identifica a forma de pagamento.

Transaction¶

Conjunto de operações no banco que devem ser executadas atomicamente.

await prisma.$transaction([
  prisma.user.create({...}),
  prisma.userRestaurant.create({...})
]);

TTL (Time To Live)¶

Tempo máximo que um recurso deve existir antes de expirar.

Exemplo: Jobs em PROCESSING por mais de 2 minutos são resetados.

W¶

Webhook¶

Endpoint HTTP que recebe notificações em tempo real de sistemas externos.

POST / webhooks / nayax;

Worker¶

Processo que executa tarefas em background (JobsProcessor).

Símbolos e Operadores¶

@ (Decorator)¶

Anotação TypeScript/NestJS que adiciona metadados a classes/métodos.

@Controller()
@Injectable()
@UseGuards()

?? (Nullish Coalescing)¶

Operador que retorna o valor da direita se o da esquerda for null/undefined.

const value = input ?? "default";

?. (Optional Chaining)¶

Operador que permite acessar propriedades de objetos que podem ser null/undefined.

const name = user?.profile?.name;

Acrônimos Comuns¶

Próximos Passos¶

• Códigos de Erro
• Mapeamento de Pagamentos