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.

Impacto 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.

Impacto 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.

Impacto 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).

Impacto 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: - RH — perfil de RH com acesso a todos os locais - Gestor — perfil administrativo (gestão, supervisão) - Empregado — perfil restrito a visualização de folha de ponto pessoal

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 (rh, gestor e/ou empregado)
      → 7. Férias / Afastamentos (conforme necessidade)

Diferença: Usuário vs. Empregado¶

Diferença: Jornada vs. Escala¶

Checklist para integrações¶

• Chaves únicas definidas e estáveis (código do empregador, local e empregado)
• Jornadas cadastradas antes das escalas
• Região e fuso horário do local de trabalho configurados corretamente (impacta feriados e timestamps)

Próximos Passos¶

• Glossário →
• Identificadores →
• Filtros e Query Parameters →