Configuração de Fluxos de Onboarding¶

Guia completo para criar e configurar fluxos de onboarding no dashboard administrativo.

Acessando o Módulo¶

1. Faça login no dashboard da sua Organization
2. Acesse o menu Onboarding > Fluxos
3. Clique em Novo Fluxo para começar

Criando um Novo Fluxo¶

Passo 1: Informações Básicas¶

Nome
- Nome descritivo do fluxo (ex: "Onboarding de Clientes Premium")
- Usado para identificação interna
- Não precisa ser único

Slug
- Identificador único do fluxo (gerado automaticamente)
- Formato: onboarding-clientes-premium
- Pode ser editado manualmente

Descrição
- Explicação detalhada do propósito do fluxo
- Uso interno para documentação
- Opcional mas recomendado

Tipo de Fluxo
- LINEAR: Sequência fixa de passos
- MODULE_BASED: Baseado em módulos selecionados
- CONDITIONAL: Com ramificações e condições

Idioma Padrão
- Idioma principal do fluxo
- Usado como fallback quando tradução não existe
- Recomendado: pt-BR

Passo 2: Configurações Avançadas¶

Configurações do Fluxo (JSON)

{
  "default_language": "pt-BR",
  "redirect_url": "https://app.example.com/dashboard",
  "allow_restart": true,
  "track_analytics": true
}

Opções disponíveis:
- default_language: idioma padrão do conteúdo
- redirect_url: URL de redirecionamento ao concluir
- allow_restart: permite recomeçar o onboarding
- track_analytics: ativa coleta de métricas detalhadas

Configurações de Acesso
- Público: pode ser acessado via API key sem autenticação adicional
- Ativo: quando desativado, o fluxo não fica disponível na API

Passo 3: Chave Pública e Segurança¶

Ao salvar o fluxo, uma Public Key única é gerada automaticamente:

Exemplo: f47ac10b-58cc-4372-a567-0e02b2c3d479

Use esta chave para:
- Acessar a API pública
- Integrar com sua aplicação
- Iniciar onboarding de clientes

⚠️ Importante: A public_key é uma chave pública que fica exposta no frontend do seu cliente.

Passo 4: Configurar Origens Permitidas (Recomendado)¶

Para proteger seu endpoint, configure quais domínios podem acessar:

Campo: Origens Permitidas (allowed_origins)

["https://app.meucliente.com", "https://www.meucliente.com"]

Comportamento:
- Se vazio → aceita requisições de qualquer origem
- Se configurado → valida o header Origin das requisições
- Requisições sem Origin (server-to-server) → sempre permitidas

Exemplo de configuração para desenvolvimento e produção:

[
  "https://app.producao.com",
  "https://www.producao.com",
  "http://localhost:3000"
]

Adicionando Etapas (Steps)¶

Criando uma Nova Etapa¶

1. No detalhe do fluxo, clique em Adicionar Etapa
2. Preencha os campos obrigatórios:

step_key (Identificador estrutural)
- Chave única dentro do flow
- Formato: welcome, configure-api, first-action
- Usado para rastrear progresso (independente de idioma)
- Não mude após criar, pois afeta progresso dos usuários

Idioma
- Idioma desta versão do step
- Para criar tradução, use o mesmo step_key com idioma diferente

Título
- Título da etapa exibido ao usuário
- Exemplo: "Bem-vindo ao AtendeAqui!"

Descrição
- Resumo do que o usuário deve fazer
- Exemplo: "Vamos configurar sua conta em 3 passos simples"

Conteúdo (Markdown)

# Bem-vindo!

Estamos felizes em tê-lo aqui. Vamos começar sua jornada:

## Próximos passos

1. Configure seu perfil
2. Adicione sua equipe
3. Crie seu primeiro ticket

> **Dica**: Este processo leva apenas 5 minutos!

[Documentação completa](https://docs.example.com)

Ordem (order)
- Número que define a sequência
- Menor número = primeiro passo
- Exemplo: 1, 2, 3, 4...

Configurações de Comportamento¶

Obrigatório (is_required)
- True: Usuário precisa completar para finalizar o flow
- False: Etapa opcional

Pode Pular (can_skip)
- True: Usuário pode pular esta etapa
- False: Etapa não pode ser pulada
- Se is_required=True e can_skip=True, o usuário pode pular mas não completa o flow

Tipo de Passo (step_type)
- INFO: Apenas informação/leitura
- ACTION: Requer ação do usuário
- VALIDATION: Validação de algo externo
- FORM: Formulário a ser preenchido

Configurações Avançadas (step_config)¶

Exemplo para formulário:

{
  "form_fields": [
    {
      "name": "company_name",
      "type": "text",
      "required": true,
      "label": "Nome da Empresa"
    },
    {
      "name": "employees",
      "type": "select",
      "options": ["1-10", "11-50", "51-200", "200+"],
      "label": "Número de Funcionários"
    }
  ],
  "submit_button": "Continuar",
  "icon": "building"
}

Exemplo para validação:

{
  "validation_type": "api_connection",
  "validation_url": "/api/validate-connection",
  "retry_button": "Tentar Novamente",
  "help_text": "Verifique se a API key está correta"
}

Criando Traduções¶

Método 1: Duplicar e Traduzir¶

1. No detalhe do step, clique em Criar Tradução
2. Selecione o idioma de destino
3. O sistema copia o step mantendo o mesmo step_key
4. Traduza os campos de texto:
5. Título
6. Descrição
7. Conteúdo (Markdown)
8. step_config (se tiver textos)

Método 2: Criar Manualmente¶

1. Crie um novo step com o mesmo step_key
2. Selecione o idioma diferente
3. Preencha o conteúdo traduzido

Exemplo:

Step 1 (pt-BR):
- step_key: welcome
- language: pt-BR
- title: "Bem-vindo!"
- content: "Olá! Estamos felizes..."

Step 1 (en-US):
- step_key: welcome
- language: en-US  
- title: "Welcome!"
- content: "Hello! We're happy..."

Boas Práticas de Tradução¶

✅ Faça:
- Mantenha o mesmo step_key em todas as traduções
- Use a mesma order em todos os idiomas
- Mantenha consistência em is_required e can_skip
- Traduza textos em step_config também

❌ Evite:
- Mudar step_key entre traduções
- Ter ordem diferente entre idiomas
- Deixar campos vazios nas traduções
- Traduzir literalmente sem contexto cultural

Organizando Hierarquia¶

Parent Step (Passo Pai)¶

Para criar sub-etapas:

1. Configuração Inicial (parent: null)
   1.1 Perfil da Empresa (parent: configuracao-inicial)
   1.2 Adicionar Logo (parent: configuracao-inicial)
2. Configurar Integrações (parent: null)
   2.1 Conectar E-mail (parent: configurar-integracoes)
   2.2 Conectar WhatsApp (parent: configurar-integracoes)

No campo parent_step_key:
- Deixe vazio para steps de primeiro nível
- Informe o step_key do pai para sub-steps

Duplicando Fluxos¶

Para criar variação de um fluxo existente:

1. No detalhe do flow, clique em Duplicar
2. Informe novo nome
3. Escolha se quer incluir traduções
4. O sistema copia:
5. Todos os steps
6. Configurações
7. Hierarquia
8. (Opcional) Traduções

Nota: O novo flow terá nova public_key

Ativando/Desativando Fluxos¶

Para desativar temporariamente:
1. Edite o flow
2. Desmarque is_active
3. Salve

Efeitos:
- API pública retorna erro 404
- Usuários não podem iniciar novo progresso
- Progresso existente não é afetado

Para reativar:
1. Marque is_active novamente
2. API volta a funcionar normalmente

Versionamento de Fluxos¶

Não existe versionamento automático. Para criar nova versão:

1. Duplique o flow existente
2. Adicione sufixo no nome (ex: "Onboarding v2")
3. Faça as alterações necessárias
4. Ative a nova versão e desative a antiga

⚠️ Atenção: Usuários em progresso no flow antigo continuam no flow antigo. Não altere flows com usuários ativos sem considerar o impacto.

Testando o Fluxo¶

Antes de publicar para clientes:

1. Use a API pública para testar
2. Simule diferentes cenários:
3. Usuário completa tudo
4. Usuário pula etapas
5. Usuário abandona no meio
6. Teste em diferentes idiomas
7. Valide os dados coletados
8. Verifique métricas e analytics

Checklist de Publicação¶

Antes de usar em produção:

• [ ] Nome e descrição claros
• [ ] Todos os steps têm conteúdo completo
• [ ] Ordem dos steps está correta
• [ ] Steps obrigatórios identificados
• [ ] Traduções criadas (se aplicável)
• [ ] Testado via API
• [ ] Webhooks configurados (se aplicável)
• [ ] Analytics habilitado
• [ ] is_active = True
• [ ] allowed_origins configurado (produção)
• [ ] public_key pronta para uso

Próximos Passos¶

Agora que seu fluxo está configurado:

• Como Usar a API Pública
• Métricas e Indicadores
• Visão Geral do Onboarding