Modelo de Dados¶

Visão Geral¶

A API Pontotel organiza seus dados em entidades hierárquicas e interdependentes. Compreender esse modelo é essencial para planejar uma integração consistente.

Grafo de Entidades¶

graph TD
    EMPLOYER["🏢 Empregador"]
    LOCAL["📍 Local de Trabalho"]
    GRUPO["📁 Grupo"]
    JORNADA["⏰ Jornada"]
    ESCALA["📅 Escala"]
    EMP["👤 Empregado"]
    USR["🔑 Usuário"]
    FERIAS["🏖️ Férias"]
    AFASTA["🏥 Afastamento"]
    MARCA["🕐 Marcação de Ponto"]

    EMPLOYER --> LOCAL
    EMPLOYER --> GRUPO
    GRUPO --> LOCAL
    LOCAL --> EMP
    JORNADA --> ESCALA
    ESCALA --> EMP
    EMP --> USR
    EMP --> FERIAS
    EMP --> AFASTA
    EMP --> MARCA

Descrição das Entidades¶

🏢 Empregador¶

Representa a empresa empregadora (CNPJ/CPF). É a raiz organizacional — todos os locais, grupos e empregados pertencem a um empregador.

Role na integração: Base para separar dados em cenários multi-CNPJ. O "código do empregador" deve ser alinhado ao ERP/folha.

📍 Local de Trabalho¶

Unidade organizacional onde o colaborador é alocado. Não precisa ser um local físico — pode representar departamentos, equipes ou filiais.

Role na integração: Define região/fuso horário que impacta feriados e timestamps de marcações. É filtro principal em relatórios.

📁 Grupo¶

Mecanismo de agrupamento para organizar locais de trabalho (e/ou usuários), criando "views" operacionais para relatórios e filtros.

Exemplo: "Filiais do Sul", "Equipe de Vendas SP".

⏰ Jornada¶

Define os horários dentro do dia: entrada, saída, intervalos e se há trabalho previsto.

• Com trabalho: tem previsão de entrada/saída e duração.
• Sem trabalho: não prevê comparecimento; ausência não gera falta.

⚠️ Dependência: Jornadas devem ser cadastradas antes das escalas.

📅 Escala¶

Define a sequência de dias trabalhados e folgas ao longo do tempo (ex.: 6×1, 12×36, 5×2). Para cada dia, a escala aponta qual jornada será seguida.

Role na integração: O colaborador é associado a uma escala para automatizar a rotina. Mudanças de escala impactam folha e compliance.

👤 Empregado¶

O cadastro central do colaborador na Pontotel — concentra dados de identificação, estrutura organizacional (local, empregador) e parametrizações de rotina (escala/jornada).

Role na integração: É a entidade mais sincronizada. Base para vincular usuários, registros de ponto, férias e afastamentos.

🔑 Usuário¶

A identidade de acesso ao sistema (login). Na prática: usuário é quem acessa, empregado é quem trabalha.

Em muitos cenários o usuário é vinculado a um empregado para que o colaborador possa registrar ponto com seus próprios dados.

Tipos: - Gestão — perfil administrativo (RH, supervisão) - Funcionário — perfil restrito para registro de ponto pessoal - Coletivo — para dispositivos compartilhados (quando aplicável)

🏖️ Férias / 🏥 Afastamentos¶

Registros de ausências programadas (férias) ou justificadas (atestados, licenças). Evitam inconsistências na folha e apontamentos incorretos.

🕐 Marcação de Ponto¶

Registro de entrada/saída do empregado. Sempre associado a um empregado e com timestamp no fuso horário correto (ISO 8601 com offset).

Dependências Operacionais¶

A ordem de cadastro imposta pelas dependências entre entidades é:

1
2
3
4
5
6
7
8

1. Empregador
   → 2. Local de Trabalho
      → (opcional) Grupo
   → 3. Jornadas
      → 4. Escalas
   → 5. Empregados
      → 6. Usuários (gestão e/ou funcionário)
      → 7. Férias / Afastamentos (conforme necessidade)

Diferença: Usuário vs. Empregado¶

Diferença: Jornada vs. Escala¶

Checklist de Consistência (para integrações)¶

• Chaves únicas definidas e estáveis (código do empregador, local e empregado)
• Jornadas cadastradas antes das escalas
• Usuário "funcionário" vinculado ao empregado para evitar divergência de dados
• Região e fuso horário do local de trabalho configurados corretamente (impacta feriados e timestamps)
• E-mail do usuário padronizado conforme política corporativa (evitar colisões)

Próximos Passos¶

• Glossário →
• Padrões de Identificação →
• Filtros e Query Parameters →