Documentação QR Vale

Bem-vindo à documentação oficial do QR Vale - o sistema completo para gestão de vales-presente digitais via QR Code.

Dica: Se você está começando agora, recomendamos seguir a ordem: Introdução → Criando Conta → Primeiro Vale → Dashboard.

O Que é o QR Vale?

O QR Vale é uma plataforma SaaS (Software as a Service) que permite a empresas de qualquer porte emitir, gerenciar e validar vales-presente digitais de forma segura, escalável e profissional.

Principais Funcionalidades

Criando sua Conta

Passo a Passo

  1. Acesse app.qr-vale.com
  2. Clique em "Criar Conta"
  3. Preencha:
    • Nome completo
    • Email (será usado para login)
    • Senha (mínimo 8 caracteres)
  4. Confirme seu email (verifique caixa de spam)
  5. Pronto! Você já pode usar o plano Free
Plano Free Gratuito: Não precisa de cartão de crédito. Inclui 20 QR codes/mês e todas as funcionalidades básicas.

Gerando seu Primeiro Vale

Via Interface Web

1. No painel, clique no botão "+" (canto inferior direito)
2. Preencha:
   - Valor em centavos (ex: 5000 = R$ 50,00)
   - Validade em dias (padrão: 180)
   - Template (opcional)
3. Clique em "Gerar"
4. QR code é criado instantaneamente
5. Baixe, compartilhe ou imprima

Campos Explicados

Campo Descrição Exemplo
valueCents Valor do vale em centavos 5000 (R$ 50,00)
validDays Validade em dias a partir da geração 180 (6 meses)
templateId ID do template (opcional) 1, 2, 3...

Dashboard Analytics

Visão Geral

O dashboard oferece estatísticas completas sobre sua operação:

Cards Principais

Filtros Disponíveis

Gráficos

Geração de Vales

Geração Individual

Para gerar um vale por vez, use o botão "+" conforme descrito em "Primeiro Vale".

Geração em Lote

Disponível nos planos Professional e Enterprise

1. No painel, acesse "Gerar em Lote"
2. Defina:
   - Quantidade (máx: 100 por lote)
   - Valor (mesmo para todos)
   - Validade (mesma para todos)
3. Clique em "Gerar"
4. Aguarde processamento (pode levar alguns segundos)
5. Download automático de arquivo ZIP com todos os QRs
Atenção: Geração em lote consome do seu limite mensal. Certifique-se de ter saldo suficiente no plano.

Validades Customizadas

Você pode configurar validades de 1 a 3650 dias (10 anos):

Validação de Vales

Fluxo de Validação

Existem dois tipos de validação:

1. Purchase (Compra)

2. Use (Uso)

Como Validar

Via Scanner Mobile

1. Abra o app QR Vale no celular
2. Toque no ícone de scanner (câmera)
3. Aponte para o QR code do vale
4. Escolha: "Comprar" ou "Usar"
5. Confirme a ação
6. Pronto! Vale validado

Via Entrada Manual

1. No app, toque em "Validar Manualmente"
2. Digite o código do vale (ex: ABC123XYZ)
3. Escolha: "Comprar" ou "Usar"
4. Confirme
5. Validação concluída
Internet Necessária: A validação requer conexão para evitar fraudes e duplicação. Modo offline está previsto para 2026.

Studio de Design

Disponível nos planos Professional e Enterprise

O Que é o Studio?

Editor visual baseado em Fabric.js que permite criar templates personalizados para seus vales sem necessidade de código.

Formatos Pré-Configurados

Objetos Disponíveis

Objeto Descrição Propriedades
QR Code Código QR do vale Posição, tamanho
Texto Texto editável Fonte, tamanho, cor, alinhamento
Imagem Upload de logo/foto Posição, escala, opacidade
Retângulo Forma geométrica Cor, borda, opacidade
Círculo Forma circular Cor, raio, borda

Criando um Template

1. No painel, acesse "Studio"
2. Escolha um formato ou crie customizado
3. Adicione objetos:
   - Arraste QR Code para o canvas
   - Adicione logo da empresa
   - Insira texto (valor, validade, instruções)
4. Customize posições e cores
5. Salve o template com nome único
6. Use ao gerar novos vales

Gestão de Equipe

Perfis de Usuário

Perfil Permissões Uso Recomendado
SUPER_ADMIN Acesso total à plataforma (gestão de orgs) Uso interno (Ciatto)
ADMIN Gestão completa da organização Gerente, Proprietário
CLERK Apenas gerar e validar vales Vendedores, Caixa, Porteiros

Criando Usuários

1. Acesse "Equipe" no painel (somente ADMIN)
2. Clique em "Adicionar Usuário"
3. Preencha:
   - Nome completo
   - Email
   - Perfil (ADMIN ou CLERK)
4. Senha é gerada automaticamente
5. Usuário recebe email com credenciais
6. Pode redefinir senha no primeiro login
Limite de Usuários: Free (1), Professional (10), Enterprise (ilimitado). Usuários extras podem ser adicionados via add-on.

API RESTful

Base URL

https://app.qr-vale.com/api

Autenticação

Todas as requisições requerem token JWT no header:

Authorization: Bearer YOUR_JWT_TOKEN

Obtendo Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "sua_senha"
}

// Resposta
{
  "ok": true,
  "data": {
    "user": { ... },
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Endpoints Principais

Gerar QR Code

POST /api/qr/generate
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "valueCents": 5000,
  "validDays": 180,
  "templateId": 1 // opcional
}

// Resposta
{
  "ok": true,
  "data": {
    "id": 123,
    "code": "ABC123XYZ",
    "valueCents": 5000,
    "validUntil": "2026-05-10T00:00:00Z",
    "qrCodeUrl": "https://..."
  }
}

Validar Vale (Use)

POST /api/qr/use/:code
Authorization: Bearer TOKEN

// Resposta
{
  "ok": true,
  "message": "Vale usado com sucesso",
  "data": {
    "code": "ABC123XYZ",
    "valueCents": 5000,
    "usedAt": "2025-11-05T14:30:00Z",
    "usedBy": "João Silva"
  }
}

Listar Vales

GET /api/qr/list?page=1&limit=50&status=all
Authorization: Bearer TOKEN

// Parâmetros query:
// - page: número da página (padrão: 1)
// - limit: itens por página (max: 100)
// - status: 'all' | 'pending' | 'purchased' | 'used' | 'expired'

// Resposta
{
  "ok": true,
  "data": {
    "qrCodes": [ ... ],
    "total": 250,
    "page": 1,
    "totalPages": 5
  }
}

Rate Limiting

Erro 429: Excesso de requisições. Aguarde 60 segundos ou faça upgrade do plano.

SDK TypeScript

Instalação

npm install @qr-vale/sdk
# ou
yarn add @qr-vale/sdk
# ou
bun add @qr-vale/sdk

Uso Básico

import { QRValeClient } from '@qr-vale/sdk';

const client = new QRValeClient({
  apiUrl: 'https://app.qr-vale.com/api',
  token: 'SEU_TOKEN_JWT'
});

// Gerar vale
const qr = await client.qr.generate({
  valueCents: 5000,
  validDays: 180
});

console.log('Código gerado:', qr.code);

// Validar vale
await client.qr.use('ABC123XYZ');

// Listar vales
const list = await client.qr.list({ page: 1, limit: 50 });
console.log('Total:', list.total);

Recursos do SDK

Documentação Completa

Visite github.com/qr-vale/sdk para exemplos avançados e referência completa da API.

Webhooks

✅ Disponível agora!

Configure endpoints para receber notificações em tempo real sobre eventos do sistema.

Configurar Webhook

POST /api/webhooks
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "url": "https://qr-vale.com/webhooks/qr-vale",
  "events": [
    "qr.generated",
    "qr.purchased",
    "qr.used"
  ]
}

// Resposta
{
  "ok": true,
  "data": {
    "id": "webhook_abc123",
    "url": "https://qr-vale.com/webhooks/qr-vale",
    "events": ["qr.generated", "qr.purchased", "qr.used"],
    "secret": "abc123...def456" // ⚠️ Copie agora! Não será mostrado novamente
  }
}

Eventos Disponíveis

Formato do Payload

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "qr.generated",
  "timestamp": "2025-11-05T14:30:00.000Z",
  "organization_id": "org_123abc",
  "data": {
    "code": "QR-ABC-XYZ-123",
    "amount": 50.00,
    "amount_cents": 5000,
    "template_id": "template_natal",
    "valid_days": 365
  }
}

Validar Assinatura (HMAC-SHA256)

Todos os webhooks incluem header X-QRVale-Signature para validação:

// Node.js
const crypto = require('crypto');

const signature = req.headers['x-qrvale-signature'];
const payload = JSON.stringify(req.body);
const secret = process.env.QRVALE_WEBHOOK_SECRET;

const expected = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expected) {
  return res.status(401).send('Invalid signature');
}

// Processar evento
const event = req.body;
console.log(`Evento: ${event.type}`, event.data);
res.status(200).send('OK');

Gerenciar Webhooks

// Listar webhooks
GET /api/webhooks

// Atualizar webhook
PATCH /api/webhooks/:id
{
  "is_active": false,
  "events": ["qr.used"]
}

// Deletar webhook
DELETE /api/webhooks/:id

// Testar webhook
POST /api/webhooks/:id/test

// Ver histórico de entregas
GET /api/webhooks/:id/deliveries?limit=50&offset=0

Retry Automático

Webhooks falhados são automaticamente reprocessados com exponential backoff:

Timeout: 10 segundos por tentativa

Blockchain Proof

O Que é Blockchain Proof?

Registro imutável de provas de integridade em blockchain, garantindo que vales não possam ser alterados retroativamente.

Tipos de Proof

OpenTimestamps (Gratuito)

Polygon (Opcional - Planos Pagos)

Como Usar

1. Ao gerar um vale, marque "Registrar em Blockchain"
2. Aguarde confirmação (pode levar alguns minutos)
3. Baixe o certificado .ots (OpenTimestamps)
4. Ou visualize no explorer (Polygon)
5. Compartilhe com cliente para verificação independente

Verificação

Qualquer pessoa pode verificar a autenticidade:

Export/Import de Dados

Exportar Dados

1. Acesse "Configurações" > "Exportar Dados"
2. Escolha o que exportar:
   - Usuários
   - QR Codes
   - Templates
   - Organização
   - Tudo
3. Clique em "Exportar"
4. Download de arquivo JSON estruturado

Formato do Export

{
  "version": "1.0",
  "exportedAt": "2025-11-05T12:00:00Z",
  "organization": { ... },
  "users": [ ... ],
  "qrCodes": [ ... ],
  "templates": [ ... ]
}

Importar Dados

1. "Configurações" > "Importar Dados"
2. Faça upload do JSON exportado
3. Escolha opções:
   - Substituir dados existentes (sobrescrever)
   - Adicionar apenas novos (upsert)
4. Clique em "Importar"
5. Aguarde processamento
Atenção: Import substitui dados com mesmo ID. Faça backup antes!

Segurança e Boas Práticas

Senhas Fortes

Proteção de Token JWT

Rate Limiting

LGPD e Privacidade

Suporte

Para dúvidas técnicas ou reportar vulnerabilidades:

Precisa de mais ajuda?
Visite nosso FAQ ou entre em contato com o suporte.

© 2025 Ciatto Software LTDA - Todos os direitos reservados