Integração Voors

Desativada desde 2026-09-01. A ZaaZ não usa mais o Voors — a sincronização noturna foi cancelada no banco, e o link desta tela saiu do menu de Configuração. O código e o histórico de execuções continuam intactos, e a tela ainda existe em /admin/settings/voors por URL direta, mas nada dispara sozinho. A entrada de colaboradores agora é manual, pelo módulo de Migração de Dados. O restante deste artigo descreve o comportamento de quando a integração estava ativa — mantido como referência para uma eventual reativação, ou para o próximo integrador (Bitrix24, ainda não iniciado).

A integração Voors traz o quadro de colaboradores da intranet para dentro da plataforma, criando e atualizando cadastros automaticamente.

A configuração fica em Administração › Integração Voors.

Como funciona

A cada execução, para cada organização com a integração ativa:

1. A API do Voors é consultada com o token da organização
2. A resposta é gravada integralmente em uma área de armazenamento temporário
3. Departamentos e cargos que ainda não existem são criados
4. Cada colaborador é comparado com a base atual
5. Cadastros novos são criados; existentes são atualizados apenas se houver diferença
6. O resultado é registrado no histórico

O passo 5 é o que mantém a operação previsível: uma sincronização em que nada mudou no Voors não gera nenhuma escrita e não polui a auditoria.

A chamada à API tem tempo limite de 30 segundos. Se o Voors não responder nesse prazo, a execução daquela organização falha e registra o erro, sem afetar as demais.

Configuração

Token de autorização — a credencial da API do Voors, específica por organização. É enviada no cabeçalho Authorization.

Sincronização automática — quando ativa, a organização entra na execução noturna. Desativada, só sincroniza por acionamento manual.

Mapeamento de campos — define a correspondência entre os campos do Voors e as colunas do cadastro de pessoas. Sem mapeamento, os dados chegam mas não são gravados em lugar nenhum.

Campos que podem receber dados

Nome completo, papel base, status, CPF, data de nascimento, permissão de exportação, gestor (por identificador e por nome), gênero, data de admissão, data de inativação, cargo, departamento, setor, perfil de acesso e e-mail.

Campos mapeados para colunas fora dessa lista são descartados silenciosamente na gravação.

Regras de correspondência

Para decidir se um colaborador é novo ou já existe, o sistema tenta nesta ordem:

1. CPF — apenas dígitos, exigindo exatamente 11
2. E-mail — comparado com as contas de autenticação existentes

Colaboradores sem CPF, ou com CPF que não chegue a 11 dígitos, são ignorados. Não geram cadastro nem erro visível — apenas não aparecem. Se a contagem de importados vier abaixo do esperado, o CPF na origem é o primeiro lugar a investigar.

Quando não há e-mail na origem

O sistema gera um endereço interno de preenchimento, no formato voors_<cpf>@org<id>.com. Ele existe apenas para satisfazer a exigência de e-mail único do cadastro.

Esses endereços não recebem mensagem alguma. Cadastros nesse estado precisam do e-mail corrigido antes de qualquer convite, e são a causa mais comum de rejeição em envios em massa. Use o filtro de domínios corporativos para excluí-los.

Vínculo de gestor

O gestor chega como nome e é casado com um cadastro existente pelo nome completo. Divergência de grafia quebra o vínculo: o nome do líder fica registrado, mas a ligação hierárquica não se forma e a pessoa aparece solta no organograma.

Se o gestor ainda não existia na plataforma no momento da importação do liderado, não havia com quem casar. Uma nova execução, com ambos já cadastrados, costuma resolver.

Comportamentos que surpreendem

Campo vazio na origem apaga o dado aqui. Se o Voors devolve cargo em branco para alguém que tinha cargo no MIS, o campo é limpo. É intencional — reflete a remoção feita na origem. CPF e status são exceção e nunca são anulados.

Usuários criados pela sincronização nascem desativados. Eles existem, mas não conseguem entrar. Liberar o acesso exige um envio em massa, que marca os destinatários como ativados.

A troca de e-mail no Voors propaga para a credencial de login. Quando o e-mail muda na origem, a conta de autenticação é atualizada e a pessoa passa a entrar com o novo endereço. Se o novo e-mail já pertencer a outro cadastro, a atualização falha e fica registrada no log do servidor.

A numeração de matrícula segue a data de admissão. Antes da carga, os registros são ordenados por data de admissão crescente, para que a matrícula sequencial siga a ordem cronológica de contratação.

Departamentos e cargos são criados conforme aparecem. Variações de grafia na origem viram cadastros distintos. Setores não são criados automaticamente.

Agendamento

A execução automática roda diariamente às 3h (horário de Brasília), agendada no próprio banco de dados. Ela percorre todas as organizações com sincronização automática ativa.

O agendamento se autentica por um segredo compartilhado guardado no banco, não por sessão de usuário. Isso permite que rode sem ninguém logado.

O acionamento manual, pela interface, exige papel de administrador e sincroniza apenas a organização de quem acionou.

Histórico

Cada execução registra origem (manual ou automática), status, total de registros lidos, criados e atualizados, e a contagem de ativos e inativos. Falhas guardam a mensagem de erro.

Como ler:

Lidos alto, criados e atualizados zerados — funcionou e nada mudou desde a última vez. É o resultado esperado no dia a dia.

Lidos bem abaixo do quadro real — colaboradores sem CPF válido estão sendo descartados.

Criados alto em execução que deveria ser rotineira — a correspondência está falhando e duplicatas estão sendo geradas. Verifique se o formato do CPF mudou na origem.

Erro “Voors API unreachable” — a API não respondeu no prazo. Confira disponibilidade do serviço e se o token continua válido.

Nota sobre o endpoint

O endereço da API do Voors e a janela de datas consultada estão fixos no código da aplicação, não são configuráveis pela interface. Apenas o token varia por organização. Mudança de endereço na origem exige alteração de código.