Guia de integração WorkMeter · Factorial (OAuth) 🔗

Para quem é este guia: administradores de empresa que querem conectar sua conta do Factorial com o WorkMeter para sincronizar automaticamente funcionários, calendários, feriados e ausências.

1. O que a integração faz 🔗

WorkMeter e Factorial cobrem áreas complementares do ciclo de vida do empregado. Factorial gerencia RH (admissões/demissões, calendários, férias e ausências) e WorkMeter mede a atividade e o tempo de trabalho. Conectá-los evita a dupla entrada de dados e melhora a qualidade da informação operacional.

Nesta fase, o fluxo de dados é unidirecional: Factorial → WorkMeter. Uma vez conectada a integração, o WorkMeter recebe automaticamente:

Dado	Detalhe
👤 Admissões e demissões de funcionários	O quadro do WorkMeter se mantém alinhado com o Factorial.
📅 Calendários e feriados	Dias úteis e feriados por funcionário.
🌴 Ausências	Férias, licenças médicas e permissões. É fundamental para que o WorkMeter calcule corretamente o tempo esperado.

A sincronização é realizada em tempo real (por meio de webhooks do Factorial a cada alteração) e é complementada com uma reconciliação noturna que garante a consistência.

🔒 Segurança. A conexão usa o padrão OAuth 2.0: o WorkMeter nunca conhece as senhas dos seus usuários do Factorial, apenas recebe um token revogável e com permissões limitadas (privilégio mínimo). Toda a comunicação viaja criptografada por HTTPS e você pode revogar o acesso a qualquer momento pelo Factorial ou pelo WorkMeter.

2. Antes de começar (requisitos) 🔗

Verifique se você cumpre estes requisitos:

• Sua conta do WorkMeter tem a função time@work (controle de ponto). O cartão do Factorial só aparece em contas com esta função.
• Você é administrador no WorkMeter.
• Você é administrador no Factorial (apenas administradores podem criar aplicações OAuth).
• Você tem acesso ao painel de produção do Factorial.

Durante o processo, você vai lidar com três dados. Anote-os em um local seguro:

Dado	De onde vem	Para que serve
URI de redirecionamento	Fornecida pelo WorkMeter (é sempre a mesma, veja abaixo)	É registrada no Factorial ao criar o app
Client ID	Gerado pelo Factorial ao criar o app	É inserido no WorkMeter
Client secret	Gerado pelo Factorial ao criar o app	É inserido no WorkMeter

📌 A URI de redirecionamento do WorkMeter (produção) é:

> https://timework.workmeter.com/api/Integration/factorial/Callback

É idêntica para todos os clientes. Você também pode copiá-la diretamente do assistente do WorkMeter (Passo 4, tela Credenciais, com o botão de copiar 📋).

3. Resumo do processo 🔗

1. Faça login no Factorial (no Factorial)
2. Crie a aplicação OAuth no Factorial (no Factorial) — ele fornece o Client ID e o Client secret, e você registra a URI de redirecionamento do WorkMeter nela
3. Abra o WorkMeter → Configuração → Integrações (no WorkMeter)
4. Conecte no assistente e autorize (no WorkMeter) — e em seguida vincule os funcionários e os tipos de dia (ausências)

Os passos 1 e 2 são feitos no Factorial; os passos 3 e 4 (e o mapeamento posterior) no WorkMeter. Recomendamos ter as duas abas abertas ao mesmo tempo.

4. Passo 1 · Faça login no Factorial 🔗

1. Abra uma nova aba do navegador e entre na sua conta do Factorial: https://app.factorialhr.com
2. Faça login com um usuário administrador.

📸

5. Passo 2 · Crie uma aplicação OAuth no Factorial 🔗

A aplicação OAuth é a que autoriza o WorkMeter a ler os dados do Factorial.

1. Com a sessão de administrador iniciada, vá ao repositório de aplicações OAuth de produção:

   https://api.factorialhr.com/oauth/applications
   

1. Clique em «New application» (Nova aplicação).
2. Preencha o formulário:

Campo	O que colocar
Name (Nome)	`WorkMeter` (ou o nome que preferir para identificá-la)
Redirect URI	`https://timework.workmeter.com/api/Integration/factorial/Callback`
Confidentiality (Confidencialidade)	Aplicação segura / confidential (WorkMeter é uma aplicação de servidor que protege o segredo).
Scopes (Permissões)	Marque: `Employees`, `Time off`, `Time tracking` e `Company holidays`

O que cada permissão concede:

• `Employees` → empregados, pertences e equipes.
• `Time off` → ausências: férias, licenças, permissões, tipos de ausência e políticas.
• `Company holidays` → feriados marcados pela Empresa (feriados locais, regionais, nacionais...).
• `Time tracking` → turnos, horários e registros de ponto.

1. Salve a aplicação. O Factorial mostrará o Client ID e o Client secret. Copie-os — você precisará deles no Passo 4.

⚠️ A URI de redirecionamento deve coincidir EXATAMENTE com a do WorkMeter (incluindo maiúsculas/minúsculas e sem barra final). Se não coincidir, a autorização falhará.

📸

📸

6. Passo 3 · Abra o WorkMeter → Configuração → Integrações 🔗

1. Entre no seu console do WorkMeter: https://timework.workmeter.com
2. Clique no ícone de engrenagem ⚙️ (Configuração) no canto superior direito.
3. No menu lateral de configuração, selecione Integrações.
4. Localize o cartão Factorial v1.0. No início aparece como não configurado («Configure as credenciais para começar»).

1. Clique na engrenagem ⚙️ do cartão do Factorial (ou no interruptor) para abrir o assistente de conexão.

7. Passo 4 · Conecte o Factorial pelo assistente do WorkMeter 🔗

O assistente tem três passos: Credenciais → Conectar → Conectado.

7.1 · Credenciais

Insira o Client ID e o Client secret que você copiou do Factorial no Passo 2.

ℹ️ O campo URI de redirecionamento é somente leitura e possui o botão de copiar 📋. Deve coincidir exatamente com o que você registrou no Factorial no Passo 2: `https://timework.workmeter.com/api/Integration/factorial/Callback`.

Pressione Salvar. O cartão passará para o estado Pendente e o assistente avançará para a etapa Conectar.

7.2 · Conectar (autorização OAuth)

1. Verifique o campo URL da API do Factorial. Por padrão é `https://api.factorialhr.com` (produção).

🌍 Clusters regionais. Altere este valor somente se sua conta do Factorial estiver em outra região/cluster (por exemplo `https://api.es.factorialhr.com`). Deve ser um endereço `https` do Factorial; caso contrário, você verá o erro «A URL do Factorial não é válida».

1. Pressione Conectar com o Factorial. Uma janela pop-up do Factorial será aberta solicitando sua autorização.
2. Autorize o WorkMeter nessa janela. Ao conceder a permissão, a janela se fecha e o WorkMeter detecta a conexão automaticamente.

📸 [Captura pendente — Tela de consentimento OAuth do Factorial («Autorizar WorkMeter»)]

💡 Se seu navegador bloquear a janela pop-up, o assistente mostrará o link «Abrir a página de autorização» para abri-la manualmente.

7.3 · Conectado

Quando a autorização for concluída, o assistente mostrará o status conectado:

Você verá a data da conexão, o status do token (Correto) e o número de erros recentes.

8. Passo 5 · Vincule os funcionários 🔗

Após conectar, é preciso parear cada funcionário do WorkMeter com sua ficha no Factorial para que a sincronização saiba a quem corresponde cada dado.

Em Configuração → Integrações → Factorial (engrenagem do cartão), abra a aba Funcionários:

• O WorkMeter propõe correspondências automáticas por nome e email quando possível.
• Para cada funcionário, selecione seu equivalente no Factorial no menu suspenso e clique em Mapear; ou use Confirmar para aceitar a sugestão.
• Você pode usar Confirmação em massa para aceitar de uma vez todas as sugestões com uma confiança acima de um limite.
• O contador laranja («N para confirmar») indica quantos funcionários ainda precisam ser vinculados.

ℹ️ Um funcionário do Factorial já vinculado a outro usuário do WorkMeter aparece desabilitado com a nota «Já vinculado a …» para evitar duplicados.

9. Passo 6 · Vincule os tipos de dia (ausências) 🔗

Na aba Tipos de dia são pareados os tipos de ausência do Factorial (férias, licença médica, etc.) com os tipos de dia do WorkMeter:

Para cada tipo de ausência do Factorial você pode:

• Mapear para o WorkMeter → vinculá-lo a um tipo de dia existente.
• Criar no WorkMeter → se não existir o equivalente, criar um novo e vinculá-lo na mesma etapa:

Indique o nome, uma cor e as horas esperadas por dia (as horas de trabalho previstas para esse tipo de dia; por exemplo `0` para um dia de férias).

• Ignorar → marcar um tipo de ausência que você não queira sincronizar.

⚠️ Enquanto houver tipos de dia «por mapear», essas ausências não serão sincronizadas. Verifique se todos os tipos relevantes estão confirmados.

10. Sincronização: o que, quando e como forçá-la 🔗

• Em tempo real: qualquer alteração no Factorial (admissão/demissão de funcionário, nova ausência, feriado…) chega ao WorkMeter em segundos via webhooks.
• Reconciliação noturna: todas as noites o WorkMeter verifica o calendário para garantir que nada foi perdido.
• Sincronização manual: se você acabou de vincular funcionários ou tipos de dia e não quer esperar pelo processo automático, pressione Sincronizar agora na tela de configuração do Factorial. Isso afeta apenas os funcionários já vinculados e pode levar alguns minutos.

🛡️ Suas edições manuais são respeitadas. Se você modificar manualmente o calendário de um funcionário no WorkMeter, a reconciliação noturna não sobrescreverá essa alteração: ela só gerencia os dias que vêm do Factorial.

11. Verificar se tudo está funcionando 🔗

Em Configuração → Integrações, o cartão do Factorial deve mostrar o status Conectado, com Token: Correto e Erros (7d): 0:

Se o estado do token mostrar outra coisa, consulte a seção seguinte.

12. Gerenciar ou desconectar a integração 🔗

Na tela de configuração do Factorial você dispõe de:

• Substituir credenciais — para inserir um novo Client ID / Secret (por exemplo, se você rotacionou o segredo no Factorial). Requer reautorizar a conexão.
• Desconectar — corta a integração: o WorkMeter deixa de receber dados do Factorial e os webhooks, tokens e credenciais OAuth armazenados são removidos.

ℹ️ Ao desconectar, os dados já sincronizados e os links (mapeamentos) de funcionários e tipos de dia são mantidos no WorkMeter; simplesmente deixam de trocar novos dados. O que é removido são as credenciais OAuth (Client ID/Secret), então se mais tarde você reconectar terá que inseri-las novamente e reautorizar o WorkMeter no Factorial.

13. Resolução de problemas 🔗

Mensagem / sintoma	Causa	Solução
«A URL do Factorial não é válida»	O host inserido em Conectar não é um endereço válido do Factorial.	Use `https://api.factorialhr.com` (ou seu cluster regional `https://api..factorialhr.com`).
«Factorial já está conectado. Desconecte primeiro…»	Já existe uma conexão ativa para sua conta.	Desconecte a integração atual antes de iniciar uma nova.
«O navegador bloqueou a janela pop-up»	O bloqueador de pop-ups impediu abrir a autorização.	Use o link «Abrir a página de autorização» ou permita janelas pop-up para `timework.workmeter.com`.
«A autorização expirou» / «A janela … foi fechada antes de completar»	A janela do Factorial foi fechada ou o tempo esgotou.	Clique novamente em Conectar com Factorial e complete a autorização.
Estado do token: «Recomenda-se atualizar» / «Inválido ou expirado» ou aviso «A conexão com o Factorial expirou»	O token de acesso deixou de ser válido (por exemplo, após reiniciar o serviço).	Desconecte e reconecte a integração para renová-lo de forma duradoura.
O erro indica que falta registrar a URI de redirecionamento / não coincide	A Redirect URI registrada no Factorial não é exatamente a do WorkMeter.	Verifique que no Factorial consta `https://timework.workmeter.com/api/Integration/factorial/Callback`, sem barra final nem diferenças de maiúsculas.
O cartão do Factorial não aparece	A conta não tem a função time@work.	Contate seu responsável de conta do WorkMeter.

Se o problema persistir, contate o suporte do WorkMeter em https://help.workmeter.com.

14. Perguntas frequentes 🔗

O WorkMeter pode modificar dados no Factorial?
Não. Nesta fase, a integração é de somente leitura a partir do Factorial: os dados viajam apenas do Factorial para o WorkMeter.

O que acontece com as senhas dos meus usuários?
O WorkMeter não as conhece em nenhum momento. A autorização OAuth entrega um token revogável; nunca credenciais de usuário.

Posso revogar o acesso?
Sim, a qualquer momento: pelo WorkMeter com Desconectar, ou pelo Factorial eliminando/revogando o aplicativo OAuth.

Preciso criar o app OAuth do Factorial toda vez?
Não. Ele é criado uma única vez. Se você rotacionar o client secret no Factorial, use Substituir credenciais no WorkMeter.

Isso afeta os dados de atividade que o WorkMeter já mede?
Não. A integração só adiciona calendário, feriados e ausências para que o cálculo do tempo esperado seja mais preciso; a medição de atividade continua funcionando da mesma forma.