Glossário¶
Definições dos principais termos usados na API e na documentação Pontotel.
Entidades Principais¶
Afastamento¶
Registro de ausência justificada do colaborador (atestados, licenças, afastamentos previdenciários etc.). Evita apontamento de faltas na folha durante o período de ausência.
Ver: Afastamentos →
Empregado¶
O cadastro do colaborador dentro da Pontotel. Concentra dados de identificação, estrutura organizacional (local, empregador) e parametrizações de rotina (escala/jornada/regras de cálculo). É a entidade central do domínio de RH.
Diferença-chave: empregado é quem trabalha; usuário é quem acessa o sistema.
Ver: Empregados →
Empregador¶
Representa a empresa empregadora (pessoa jurídica ou física) identificada por CNPJ ou CPF. É a entidade raiz — todos os locais, empregados e grupos pertencem a um empregador.
Ver: Empregadores →
Escala¶
Estrutura que define a sequência de dias trabalhados e folgas ao longo de um ciclo (ex.: 6×1, 12×36, 5×2). Para cada dia da escala é atribuída uma jornada. Depende de jornadas cadastradas previamente.
Ver: Escalas →
Férias¶
Registro do período de descanso remunerado do colaborador. Sincronizar férias com a Pontotel evita inconsistências em folha e relatórios.
Ver: Férias →
Grupo¶
Mecanismo de agrupamento para organizar locais de trabalho (e/ou usuários) em "pastas" operacionais. Facilita a seleção em massa para relatórios e filtros de folha.
Ver: Grupos →
Jornada¶
Define os horários dentro de um dia de trabalho: entrada, saída, intervalos e se há trabalho previsto. Pode ser "com trabalho" ou "sem trabalho" (folga/descanso). Deve ser cadastrada antes da escala.
Ver: Jornadas →
Local de Trabalho¶
Unidade organizacional onde o colaborador está alocado. Não precisa ser um local físico — pode representar departamentos, equipes ou filiais. Define região e fuso horário que impactam feriados e timestamps de marcações.
Ver: Locais de Trabalho →
Marcação de Ponto¶
Registro de entrada ou saída de um empregado em um determinado momento. Sempre associada a um empregado e com timestamp obrigatoriamente com fuso horário (ISO 8601).
Ver: Marcações →
Usuário¶
A identidade de acesso ao sistema Pontotel (login). Pode ser um gestor, administrador de RH, ou colaborador. Quando representa um colaborador, deve ser vinculado ao empregado para garantir consistência dos dados (nome, e-mail etc.).
Diferença-chave: usuário é quem acessa; empregado é quem trabalha.
Ver: Usuários →
Termos Técnicos¶
Bearer Token¶
Método de autenticação usado na API. O token JWT é obtido via POST /login/ e enviado no header Authorization: Bearer {token} em todas as requisições subsequentes. Válido por 1 hora.
Business Key (Chave de Negócio)¶
Identificador com significado funcional usado para integração entre sistemas: CNPJ (empregador), CPF (empregado), matrícula (empregado). Preferível ao ID interno para mapear registros entre sistemas.
CPF¶
Cadastro de Pessoa Física — documento de identificação único de pessoa física no Brasil. Usado como chave de negócio para empregados.
CNPJ¶
Cadastro Nacional de Pessoa Jurídica — identificador único de empresas no Brasil. Usado como chave de negócio para empregadores.
Dirty Reload¶
Estratégia do servidor de desenvolvimento MkDocs (--dirtyreload) que re-renderiza apenas as páginas modificadas. Não detecta mudanças em mkdocs.yml — nestas situações é necessário reiniciar o servidor.
ERP¶
Enterprise Resource Planning — sistema de gestão empresarial (ex.: SAP, TOTVS Protheus). Em integrações, o ERP costuma ser o "sistema master" para dados de cadastro de colaboradores.
Fuso Horário¶
Offset UTC aplicado a timestamps de marcações. Essencial para consistência em empresas com operações em múltiplas regiões do Brasil (ou internacionais). Configurado por local de trabalho.
ISO 8601¶
Padrão internacional de representação de datas e horas. Formato usado na API: 2025-01-31T08:05:00-03:00. Sempre inclua o offset do fuso horário.
Idempotência¶
Propriedade de uma operação que pode ser executada múltiplas vezes sem efeito colateral adicional além da primeira execução. Importante em integrações para garantir que retentativas não dupliquem dados.
JWT¶
JSON Web Token — formato do token de autenticação utilizado pela API Pontotel.
Matrícula¶
Identificador interno do colaborador dentro da empresa. Quando padronizado como chave de integração, permite mapeamento estável entre o sistema de RH e a Pontotel.
Paginação¶
Mecanismo de divisão de grandes listagens em páginas. A API retorna count, next, previous e results. Use page e page_size como query parameters.
Rate Limit¶
Limite de requisições por unidade de tempo. Produção: 500 req/hora, 50 req/minuto. Sandbox: 1000 req/hora, 100 req/minuto. Headers X-RateLimit-* informam o consumo atual.
Sandbox¶
Ambiente de testes isolado em sandbox-apis.pontotel.com.br. Dados não afetam produção. Use para desenvolvimento e validação de integrações antes de ir a ar.
Sincronização Incremental¶
Estratégia de sincronização que transfere apenas registros modificados desde a última execução bem-sucedida. Mais eficiente que a sincronização completa para uso regular.