🚌

Trip Sampa

Sistema de gestão operacional. Controla vendas, vendedores, comissões, passageiros e listas de embarque — integrado ao WooCommerce para automação completa do fluxo comercial.

✓

Status: Produção. O sistema está funcional e rodando com dados reais de Fevereiro/2026. Todos os módulos descritos nesta documentação estão operacionais.

O que o sistema resolve

A Trip Sampa opera excursões rodoviárias com uma rede de vendedores por indicação. Antes do sistema, o rastreio de quem vendeu o quê, o cálculo de comissões e a geração de listas operacionais era manual. Isso gerava erros, conflitos e retrabalho constante.

O Trip Sampa automatiza todo esse fluxo:

🔗

Atribuição automática

Cada vendedor tem um link único. Vendas pelo link são atribuídas automaticamente a ele.

💰

Comissão calculada

O percentual é configurável por vendedor. O sistema calcula sobre vendas confirmadas em tempo real.

📋

Listas operacionais

Exportação em CSV das listas de guia e ônibus com todos os dados de embarque.

🛒

WooCommerce sync

Pedidos e produtos sincronizados via webhooks. Zero entrada manual de dados.

Quem usa o sistema

Perfil	Acesso	O que faz
Admin	Acesso total	Gerencia passageiros, vendedores, pacotes, listas operacionais e métricas. Cria contas de vendedores.
Vendedor	Portal restrito	Visualiza seus leads, vendas, comissão acumulada e gera links de venda personalizados.

Stack técnico rápido

React 18 Vite Tailwind CSS Supabase (Auth + DB) Edge Functions (Deno) WooCommerce API PostgreSQL Row Level Security

Arquitetado, desenvolvido e entregue por Elastre

⚡

Arquitetura & Stack

Visão técnica de como os componentes se conectam — do frontend React até o WooCommerce.

Fluxo principal

Site

WooCommerce

→

Webhook

Edge Function

→

Banco

Supabase DB

→

Interface

React App

Componentes

Camada	Tecnologia	Detalhe
Frontend	React 18 + Vite	SPA com componentes funcionais, hooks, Context API para Auth e Toast. Tailwind CSS para estilos.
Auth	Supabase Auth	Email/password. Roles definidos na tabela `profiles`. Sessions gerenciadas via `onAuthStateChange`.
Database	PostgreSQL (Supabase)	7 tabelas principais + views otimizadas. RLS ativado em todas as tabelas.
Edge Functions	Deno (Supabase)	2 funções: `woocommerce-order` e `woocommerce-product`. Recebem webhooks e escrevem no banco.
E-commerce	WooCommerce (WordPress)	Vende os pacotes. Envia webhooks em pedido criado/atualizado e produto criado/atualizado.
Referral	PHP (functions.php)	Captura `?ref=` da URL, armazena em cookie/session, injeta no pedido como meta_data.

Estrutura do projeto

tripsampa/
├── src/
│   ├── App.jsx            ← Aplicação completa (componentes + lógica)
│   ├── lib/
│   │   └── supabase.js    ← Cliente Supabase (env vars)
│   ├── index.css           ← Tailwind directives
│   └── main.jsx            ← Entry point
├── supabase/
│   └── migrations/
│       └── 001_initial_schema.sql  ← Schema completo do banco
├── docs/
│   └── STEP_BY_STEP_INTEGRATION.md ← Guia de webhooks
├── .env                    ← Variáveis de ambiente
├── resync-orders.mjs       ← Script de re-sync de pedidos
├── vite.config.js
├── tailwind.config.js
└── package.json

ℹ

Single-file architecture: Todo o frontend está em App.jsx (~2300 linhas). Isso é intencional — facilita deploy e manutenção sem configuração complexa de roteamento.

🔐

Autenticação & Roles

Como o sistema gerencia login, sessões, criação de contas e permissões baseadas em roles.

Fluxo de login

O sistema abre por padrão na tela de login. Ambos admins e vendedores acessam pelo mesmo ponto de entrada com email + senha.

Entrada

LoginScreen

→

Supabase

signInWithPassword

→

Profile

Role check

→

UI

Admin / Vendedor

Primeiro acesso (Admin)

Na tela de login existe o link "Primeira vez? Criar conta de administrador". Ao clicar:

Chave de convite é solicitada (ex: TRIPSAMPA-2026-ALPHA)
Onboarding wizard de 5 etapas guia a criação da conta admin
Após conclusão, o admin é logado automaticamente

⚠

A chave de convite é sempre exigida ao clicar em "Criar conta". Os flags de localStorage são limpos para garantir que o fluxo completo seja refeito.

Conta de vendedor

Vendedores não criam conta sozinhos. O admin cria a conta na aba "Vendedores" e recebe credenciais temporárias (email + senha gerada). O vendedor faz login normalmente e vê seu portal restrito.

Gerenciamento de sessão

A sessão usa o Supabase Auth. O AuthProvider escuta onAuthStateChange para reagir a eventos de login/logout. Detalhe técnico importante:

🔑

saveVendedor: Quando o admin cria um vendedor, signUp() troca a sessão para o novo usuário. O sistema salva a sessão admin antes, e restaura após a criação usando um flag _skipAuthEvents para evitar que o listener de auth reaja à troca temporária.

Row Level Security (RLS)

Todas as 7 tabelas possuem RLS ativado. Políticas resumidas:

Tabela	Admin	Vendedor
`profiles`	Lê/edita todos	Lê/edita próprio
`leads`	CRUD completo	Lê próprios leads
`packages`	CRUD completo	Lê ativos
`parcelas`	CRUD completo	Segue acesso do lead
`configuracoes`	CRUD completo	Sem acesso

📊

Dashboard & Métricas

O painel de visão geral mostra os KPIs mais importantes em tempo real.

Filtros de período

✓

O dashboard possui filtros de Semana, Mês e Tudo. Permitem visualizar KPIs e passageiros recentes apenas do período selecionado. Ideal para acompanhamento semanal/mensal de resultados.

Métricas do admin

Faturamento

Soma de valor_pago de todos os leads com status pago no período selecionado.

Comissões

Para cada lead pago com vendedor, calcula: valor_pago × (comissao_percentual / 100). Dinâmico por vendedor.

Novos Leads

Contagem de leads com status novo no período.

Vendas

Contagem de leads com status pago no período.

ℹ

Comissão dinâmica: O sistema busca o comissao_percentual individual de cada vendedor (padrão 5%). Não usa valor fixo — se um vendedor tem 7%, o cálculo reflete isso.

Tabela de passageiros recentes

Abaixo dos KPIs, exibe os últimos 5 passageiros (filtrados pelo período selecionado) com nome, pacote, status e valor. Serve como snapshot rápido da atividade.

👥

Passageiros

Gestão completa de passageiros/leads com CRUD, busca, filtro e responsive design.

Funcionalidades

Busca por nome, telefone ou email em tempo real
Filtro por status — Novo, Pendente, Pago, Cancelado
Filtro por pacote — filtra passageiros por viagem específica
Criar/Editar via slide panel lateral com todos os campos
Excluir com diálogo de confirmação
Passageiros adicionais (acompanhantes) — ao editar/criar um passageiro, é possível adicionar acompanhantes com nome, telefone e RG
Edição pós-compra — qualquer campo pode ser alterado após a compra: poltrona, local de embarque, hospedagem, documentos, etc.
Responsivo — tabela no desktop, cards no mobile

Campos do passageiro

Campo	Tipo	Observação
Nome *	texto	Obrigatório
Telefone	texto	Formatado como (XX) XXXXX-XXXX
Email	email	Opcional
CPF	texto	Para listas de embarque
RG	texto	Para lista do ônibus
Órgão Emissor (RG)	texto	Ex: SSP/SP — exibido na lista do ônibus
Pacote	select	Vinculado a `packages`
Vendedor	select	"Orgânico" se sem vendedor
Status	enum	novo / pendente / pago / cancelado
Valor Total / Pago	decimal	Valores financeiros
Poltrona	inteiro	Número do assento
Local de Embarque	texto	Ex: Terminal Tietê, Metrô Barra Funda
Hospedagem	texto	Hotel, quarto — quando a viagem inclui hospedagem
Passeios	texto	Passeios inclusos — quando a viagem inclui passeios
Observações	textarea	Notas livres

Passageiros adicionais (acompanhantes)

Quando uma compra inclui mais de uma pessoa, o admin pode adicionar acompanhantes ao passageiro principal:

Clique em "+ Adicionar" na seção "Passageiros adicionais" dentro do formulário de edição
Cada acompanhante tem: Nome, Telefone e RG
Os acompanhantes são salvos na tabela acompanhantes do banco de dados
Podem ser adicionados/removidos a qualquer momento editando o passageiro principal

ℹ

A maioria dos passageiros chega automaticamente via WooCommerce. O CRUD manual existe para ajustes, vendas por WhatsApp ou cadastros presenciais. Campos como local de embarque, hospedagem e passeios são preenchidos manualmente pelo admin conforme a necessidade de cada viagem.

🤝

Vendedores & Comissões

Cadastro de vendedores com criação automática de conta, link de referência e cálculo de comissão individual.

Criando um vendedor

O fluxo completo de criação acontece dentro do painel admin:

Admin clica em "+ Novo" na aba Vendedores
Preenche nome, email, telefone, código de referência e % de comissão
O sistema cria uma conta Supabase Auth com senha temporária gerada automaticamente
Um modal exibe as credenciais (email + senha) para o admin copiar e enviar ao vendedor
O vendedor usa essas credenciais para fazer login e acessar seu portal

Card do vendedor

Cada vendedor exibe em seu card:

Nome, email e badge de comissão (%)
Link de referência copiável: tripsampaviagens.com.br?ref=codigo
Métricas: total de leads, vendas confirmadas e comissão acumulada

Cálculo de comissão

comissão = leads.filter(status === 'pago' && vendedor_id)
    .reduce((sum, lead) => {
        const pct = vendedor.comissao_percentual / 100;
        return sum + (lead.valor_pago * pct);
    }, 0);

✓

O percentual é individual por vendedor (padrão 5%). Pode ser alterado a qualquer momento editando o vendedor. A mudança reflete imediatamente no dashboard.

📦

Pacotes & Operacional

Pacotes de viagem sincronizados do WooCommerce e listas de embarque exportáveis.

Pacotes

A tela de pacotes é somente leitura. Os pacotes são criados e gerenciados no WooCommerce e sincronizados automaticamente via webhook. Cada card mostra:

Destino, nome completo e preço
Data da viagem
Barra de ocupação (vendas / capacidade do ônibus)
Vagas disponíveis
Botão "Ver passageiros" — navega direto para a lista de passageiros filtrada por aquele pacote

Filtro de mês nos pacotes

A tela de pacotes possui filtros: Este mês, Próximo mês e Todos. Filtra os pacotes pela data de viagem, facilitando foco nas viagens mais próximas.

Operacional — Listas de embarque

Na aba Operacional, o admin seleciona um pacote e acessa duas listas:

Lista Guia

Nome, telefone, documentos (CPF/RG), observações, passeios e hospedagem de cada passageiro. Pensada para o guia no dia da viagem.

Lista Ônibus

Nome, CPF, RG, órgão emissor e número da poltrona. Pensada para a empresa de transporte.

Ambas podem ser exportadas em CSV com codificação UTF-8 (com BOM para compatibilidade com Excel). O CSV inclui todos os campos da lista correspondente.

⚠

As listas mostram apenas passageiros com status pago. Passageiros pendentes ou cancelados não aparecem nas listas operacionais.

✨

Portal do Vendedor

Interface dedicada para vendedores acompanharem resultados e gerarem links de venda.

Primeiro acesso

Na primeira vez que um vendedor faz login, um tutorial interativo de 4 etapas explica:

Boas-vindas personalizadas com o nome do vendedor
Como funcionam os links de venda
Como acompanhar vendas e comissão
Dicas finais (alterar senha, usar links corretos, etc.)

O tutorial pode ser pulado e não aparece novamente após ser concluído (flag em localStorage).

Telas do vendedor

Dashboard pessoal com 4 KPIs: total de leads, vendas confirmadas, valor total vendido e comissão acumulada. A comissão usa o percentual individual do vendedor. Possui filtros de período (Semana / Mês / Tudo) para o vendedor acompanhar seus resultados por período.

Exibe um link geral (tripsampaviagens.com.br?ref=codigo) e links por pacote (tripsampaviagens.com.br/produto/slug?ref=codigo). Cada link tem botão de copiar com feedback visual.

Lista de todos os clientes que compraram via link do vendedor. Mostra nome, telefone, pacote, status e valor. Tabela no desktop, cards no mobile. Somente leitura.

Formulário para o vendedor trocar a senha temporária. Requer mínimo de 6 caracteres e confirmação.

🛒

WooCommerce & Webhooks

Como a loja WooCommerce se conecta ao sistema via Edge Functions e webhooks.

Arquitetura da integração

Cliente compra

WooCommerce

→

Webhook POST

JSON do pedido

→

Edge Function

woocommerce-order

→

Insere

leads table

Edge Functions

Recebe o JSON completo do pedido WooCommerce e:

1. Extrai dados do cliente (billing: nome, email, telefone, CPF)

2. Busca ref nos meta_data do pedido

3. Se encontra ref, busca o vendedor correspondente na tabela profiles

4. Busca o pacote correspondente via product_id ou sku

5. Cria o lead com status pago (se completed) ou pendente

6. Define origem como ref:codigo ou site

Recebe dados de produto e faz upsert na tabela packages:

→ Mapeia product.name → nome, product.price → preco

→ Usa woocommerce_id como chave de conflito para atualizar produtos existentes

→ Suporta meta_data customizado para capacidade_onibus e data_viagem

Captura de referral (?ref=)

No WordPress, um snippet em functions.php captura o parâmetro ?ref= da URL:

Armazena em WooCommerce session e cookie de 30 dias
No checkout, injeta como order meta_data (chaves ref e _ref)
A Edge Function lê esse meta_data para atribuir ao vendedor

Webhooks necessários no WooCommerce

Nome	Evento	URL
Novo Pedido	Order created	`.../functions/v1/woocommerce-order`
Pedido Atualizado	Order updated	`.../functions/v1/woocommerce-order`
Produto Criado	Product created	`.../functions/v1/woocommerce-product`
Produto Atualizado	Product updated	`.../functions/v1/woocommerce-product`

Script de re-sync

O arquivo resync-orders.mjs permite importar pedidos em lote (ex: todos de Fevereiro). Ele busca pedidos da API WooCommerce e envia cada um para a Edge Function.

node resync-orders.mjs

⚠

A Edge Function faz INSERT. Se rodar o resync duas vezes, pode criar duplicatas. Verifique com: SELECT woocommerce_order_id, COUNT(*) FROM leads GROUP BY woocommerce_order_id HAVING COUNT(*) > 1;

🗄

Banco de Dados

Schema PostgreSQL completo com 7 tabelas, views otimizadas, triggers e RLS.

Tabelas principais

profiles

id (PK, FK→auth.users) email nome telefone role (admin|vendedor|guia) referral_code (UNIQUE) comissao_percentual ativo

leads

id (PK) nome email telefone cpf / rg orgao_emissor_rg novo package_id (FK) vendedor_id (FK) status woocommerce_order_id valor_total / valor_pago poltrona origem local_embarque novo hospedagem novo passeios novo

packages

id (PK) woocommerce_id (UNIQUE) nome destino data_viagem preco capacidade_onibus status slug (UNIQUE)

parcelas

id (PK) lead_id (FK) numero valor data_vencimento status

acompanhantes

id (PK) lead_id (FK) nome cpf rg telefone novo

configuracoes / notificacoes

Tabelas auxiliares para settings e WhatsApp

Views

View	Uso
`v_vendas_detalhadas`	Joins leads + packages + profiles com cálculo de comissão
`v_metricas_vendedor`	Agrupado por vendedor: total leads, vendas, comissão
`v_lista_guia`	Lista de embarque para guia (passageiros pagos)
`v_lista_onibus`	Lista para empresa de transporte (CPF, RG, poltrona)

Triggers

update_updated_at() — Atualiza campo updated_at em INSERT/UPDATE
generate_referral_code() — Gera código de referência automático para novos vendedores

📖

Passo a Passo

Guia prático de como operar o sistema no dia a dia — para admins e vendedores.

Para o Administrador

1. Acesse a aba Vendedores no menu lateral

2. Clique no botão "+ Novo"

3. Preencha: nome, email, telefone, código de referência e % de comissão

4. Clique em "Salvar"

5. Um modal exibirá o email e a senha temporária

6. Clique em "Copiar credenciais" e envie ao vendedor via WhatsApp

A maioria dos passageiros chega automaticamente via WooCommerce. Para ajustes manuais:

→ Criar: Clique "+ Novo", preencha os dados e salve

→ Editar: Clique no ícone de lápis ao lado do passageiro

→ Mudar status: Edite e altere o dropdown de status (útil para marcar pagamentos)

→ Excluir: Clique no ícone de lixeira. Confirmação será solicitada.

1. Vá na aba Operacional

2. Selecione o pacote desejado no dropdown

3. Alterne entre "Lista Guia" e "Lista Ônibus"

4. Clique em "Exportar CSV"

O arquivo será baixado automaticamente e pode ser aberto no Excel.

O Dashboard (Visão Geral) mostra faturamento total, comissões totais, novos leads e vendas.

Para ver comissão individual, vá na aba Vendedores — cada card mostra a comissão acumulada.

Para alterar o percentual de comissão, edite o vendedor e ajuste o campo "Comissão (%)".

Para o Vendedor

1. Acesse o sistema com o email e senha temporária que o admin enviou

2. Um tutorial interativo de 4 etapas irá aparecer — siga ou pule

3. Vá na aba "Alterar Senha" e defina uma senha pessoal

1. Vá na aba "Gerar Links"

2. Copie o link geral ou o link de um pacote específico

3. Compartilhe com seus clientes via WhatsApp, Instagram, etc.

4. Quando alguém compra pelo seu link, a venda aparece automaticamente em "Meus Leads"

"Meu Painel" mostra seus KPIs em tempo real: leads, vendas, valor vendido e comissão acumulada.

"Meus Leads" lista todos os clientes que compraram pelo seu link, com status atualizado.

⭐

Boas Práticas

Regras, convenções e dicas importantes para operar o sistema corretamente no dia a dia.

"Email" é uma credencial — não um email real

⚠

O campo "Email" no sistema é uma credencial de acesso, não necessariamente um endereço de email funcional. Ele serve como identificador único para login. Não é necessário que seja um email real que recebe mensagens.

O sistema não envia emails (nem confirmação, nem recuperação de senha). O "email" é usado exclusivamente como login. Por isso, siga a convenção abaixo para manter tudo organizado.

Convenção obrigatória de credenciais

👤

Conta de Admin

Use o prefixo admin@
Ex: admin@tripsampa

🤝

Conta de Vendedor

Use o prefixo vendedor@
Ex: vendedor@joao, vendedor@maria

✓

Isso é mais que uma sugestão — é a forma recomendada de uso. Seguir essa convenção facilita a identificação de quem é quem no banco, evita confusão e mantém o sistema organizado. O que define o nível de acesso é a role (admin/vendedor), não o "email".

Dados em produção

O sistema está populado com dados reais a partir de 1º de Fevereiro de 2026. Todos os pedidos do WooCommerce desde essa data foram importados via webhook e script de re-sync.

ℹ

Conforme o tempo passa e mais dados acumulam, os filtros de período (semana, mês, tudo) se tornam essenciais. O sistema possui filtros de tempo no Dashboard e nas páginas de dados para consultar vendas da semana, do mês ou de todo o período.

Criação de contas

Sempre crie a conta de admin primeiro, usando a chave de convite
Contas de vendedores são criadas pelo admin na aba Vendedores
O vendedor nunca cria a própria conta — ele recebe credenciais do admin
A senha temporária deve ser alterada no primeiro acesso

Operacional do dia a dia

Se um pedido foi cancelado, mude o status para "Cancelado" em vez de excluir. Isso mantém o histórico e evita inconsistências com o WooCommerce.

O script resync-orders.mjs pode criar duplicatas se executado mais de uma vez. Antes de rodar, verifique se os dados já existem com a query:

SELECT woocommerce_order_id, COUNT(*) FROM leads GROUP BY woocommerce_order_id HAVING COUNT(*) > 1;

Defina o percentual de comissão no momento da criação do vendedor. Se alterar depois, o cálculo será retroativo (aplica o novo % sobre todas as vendas pagas). Padrão: 5%.

As listas de embarque (guia e ônibus) mostram apenas passageiros com status "Pago". Exporte o mais perto possível da viagem para ter dados atualizados. Recomendação: na véspera.

Após a compra, o admin pode editar qualquer passageiro: trocar poltrona, alterar local de embarque, atualizar documentos, adicionar acompanhantes, etc. Basta clicar no ícone de lápis na lista de passageiros.

Sobre os filtros de período

O sistema oferece filtros de semana, mês e todos nas seguintes telas:

Tela	Filtros disponíveis
Dashboard (Admin)	Esta semana / Este mês / Tudo
Meu Painel (Vendedor)	Esta semana / Este mês / Tudo
Pacotes	Este mês / Todos
Passageiros	Busca + filtro por status

⚙

Configuração & Deploy

Como configurar o ambiente de desenvolvimento e colocar o sistema em produção.

Variáveis de ambiente

Crie um arquivo .env na raiz do projeto:

VITE_SUPABASE_URL=https://SEU-PROJETO.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...

🔑

Nunca commite o .env em repositórios públicos. A anon key é pública (segura com RLS), mas o service_role_key das Edge Functions é secreto.

Rodando localmente

# Instalar dependências
npm install

# Iniciar dev server
npm run dev

# Acessar em http://localhost:5173

Deploy em produção

# Build para produção
npm run build

# Output em dist/ — serve com qualquer host estático
# (Vercel, Netlify, Cloudflare Pages, etc.)

Chaves de convite válidas

Para criar contas de admin, use uma destas chaves:

TRIPSAMPA-2026-TEST
TRIPSAMPA-2026-ALPHA
TRIPSAMPA-2026-BETA
TRIPSAMPA-2026-GAMMA

Cada chave só pode ser usada uma vez (controle via localStorage).

Checklist de deploy

Supabase: Schema aplicado, RLS ativado, Edge Functions deployed
WooCommerce: 4 webhooks configurados, ref capture em functions.php
Frontend: .env com credenciais corretas, build limpo
DNS: Frontend acessível no domínio desejado
Teste: Criar vendedor, gerar link, testar compra, verificar atribuição

Documentação técnica do projeto Trip Sampa.
Arquitetado, desenvolvido e entregue por Elastre — Fevereiro 2026.