Configuração de Fluxos de Onboarding

Acessando o Módulo

Faça login no dashboard da sua Organization
Acesse o menu Onboarding > Fluxos
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

No detalhe do fluxo, clique em Adicionar Etapa
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

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

Método 2: Criar Manualmente

Crie um novo step com o mesmo step_key
Selecione o idioma diferente
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:

No detalhe do flow, clique em Duplicar
Informe novo nome
Escolha se quer incluir traduções
O sistema copia:
- Todos os steps
- Configurações
- Hierarquia
- (Opcional) Traduções

Nota: O novo flow terá nova public_key

Ativando/Desativando Fluxos

Para desativar temporariamente:

Edite o flow
Desmarque is_active
Salve

Efeitos:

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

Para reativar:

Marque is_active novamente
API volta a funcionar normalmente

Versionamento de Fluxos

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

Duplique o flow existente
Adicione sufixo no nome (ex: “Onboarding v2”)
Faça as alterações necessárias
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:

Use a API pública para testar
Simule diferentes cenários:
- Usuário completa tudo
- Usuário pula etapas
- Usuário abandona no meio
Teste em diferentes idiomas
Valide os dados coletados
Verifique métricas e analytics

Checklist de Publicação

Antes de usar em produção:

Próximos Passos

Agora que seu fluxo está configurado: