API Reference · Gestão organizacional

Códigos de ação

Cada código é uma permissão configurável por cliente e o nome do comando no livro de atos. Sem regra de permissão configurada, ninguém pode (RN-ORG-012). "Próprio" indica que a pessoa pode agir sobre o próprio cadastro sem a permissão, nas condições da coluna.

Leituras de estrutura, cargos, níveis, colegiados e designações ficam abertas a qualquer usuário autenticado do cliente. Leituras de remuneração nunca ficam abertas: exigem o código próprio (RN-ORG-112). Leituras de calendários de férias ficam abertas a qualquer usuário autenticado do cliente.

Códigos de ação do desenvolvimento e da comunicação

Mesmas convenções da tabela anterior. "Sempre" indica comando em que a autorização é uma condição conferida no serviço, não uma permissão configurável.

Leituras abertas a qualquer usuário autenticado do cliente: ciclos, patamares por cargo, cursos por cargo, mural de elogios, o próprio feed de comunicados e os próprios questionários abertos.

Rotas da base de cadastro

Toda escrita é POST, exige o cabeçalho Idempotency-Key e registra o comando no livro de atos. Parâmetro :id é um identificador no formato UUID; texto fora desse formato devolve 400. Recusa por regra devolve 422 e fica gravada no livro; registro inexistente dentro de um comando também devolve 422 (RN-ORG-007), e em leitura devolve 404. Parâmetro on é uma data; sem ele vale o dia de hoje. Leitura sem código de ação (—) fica aberta a qualquer usuário autenticado do cliente.

Estrutura

Escritórios

Pessoas

Vínculos

Cargos e níveis

Documentos

Admissão

Promoção e mudança de trilha

Lideranças

Colegiados

Desligamento

Rotas da remuneração

Valem as mesmas convenções das rotas da base de cadastro. Dinheiro trafega como texto decimal com 2 casas (por exemplo "1234.50"), nunca como número; o coeficiente tem até 4 casas. Toda consulta de remuneração exige o código indicado, é gravada no registro de consulta antes de devolver o dado (RN-ORG-113) e, sem permissão configurada, ninguém consulta, nem o administrador (RN-ORG-112).

Índices e tabela de níveis

Gratificações

Registro de consultas

Rotas da rotina

Valem as mesmas convenções das rotas da base de cadastro. Instantes trafegam em UTC; datas, como AAAA-MM-DD. O pedido de registro de ponto não aceita horário: o horário é o do servidor (RN-ORG-154), e campo desconhecido no corpo devolve 400. Consultas por período usam from e to, com limite de 366 dias (93 no relatório de unidade). Irregularidades, ausências e saldos são calculados na consulta (RN-ORG-160).

Catálogos, regras e configurações

Arranjo de trabalho e ponto

Irregularidades e ausências

Banco de horas

Pedidos

Atestados

Férias

Rotas do desenvolvimento e da comunicação

Valem as mesmas convenções das rotas anteriores. Toda escrita exige o cabeçalho Idempotency-Key e devolve o resultado do ato, com avisos e fatos. Datas trafegam como AAAA-MM-DD.

Catálogos, regras e configurações

Nenhuma ação deste grupo é de fluxo de aprovação. A promoção continua a mesma ação de fluxo; ganha apenas o requisito configurável development.promotion.evaluation.

Habilidades e competência

Ciclos de avaliação

A conta segue o desenho de média ponderada em dois níveis (RN-ORG-232, RN-ORG-233): primeiro por fonte dentro de cada habilidade, depois por habilidade dentro de cada grupo e por grupo na nota geral. O resultado nunca é gravado: é calculado a cada leitura (RN-ORG-236).

Experiência

Feedback e elogios

Plano de desenvolvimento

Cursos e treinamento

Comunicados

Questionários e aniversariantes

Pendências

Entradas, saídas e erros de cada operação seguem o contrato gerado pelo servidor e serão transcritos para as tabelas de Entrada, Saída e Erros depois da aprovação editorial das regras RN-ORG-021 a RN-ORG-056, RN-ORG-100 a RN-ORG-114 e RN-ORG-150 a RN-ORG-208 e RN-ORG-220 a RN-ORG-259 e RN-ORG-300 a RN-ORG-313.

Códigos de ação das metas

Mesmas convenções das tabelas anteriores.

Rotas das metas

Valem as mesmas convenções das rotas anteriores. Toda escrita é POST, exige o cabeçalho Idempotency-Key e devolve o resultado do ato, com avisos e fatos. Datas trafegam como AAAA-MM-DD. O valor-alvo trafega como texto decimal com ponto, por exemplo "1250.50", nunca como número (RN-ORG-304).

Catálogo e regra configurável

Metas

Fatos publicados: goal.created, goal.revised, goal.closed e goal.reversed (RN-ORG-313).

Datas no passado

Criação (periodStart), revisão (validFrom) e encerramento (closedOn) com data anterior à véspera de hoje são recusados com 422 DATE_IN_PAST, salvo se o corpo trouxer retroactive: true e um motivo. Na criação o motivo vai em reason; na revisão e no encerramento, o próprio reason do ato serve de motivo da retroatividade. retroactive: false ou ausente não basta.

Listas de metas vigentes

GET /v1/units/:id/goals e GET /v1/people/:id/goals aceitam limit (1 a 200, padrão 50) e cursor. A próxima página vem no cabeçalho Next-Cursor, vazio na última; o cursor é opaco. Cursor malformado, com caractere nulo ou vazio responde 400 CURSOR_INVALID. A ordem é por código do indicador e, depois, por identificador da meta.

Erros das metas

Recusas de negócio respondem 422 com o código abaixo e ficam registradas como recusa do ato.

Formato do valor-alvo: até 14 dígitos inteiros e até 4 decimais, em texto. Número JSON, vírgula e expoente respondem 400; casas além das do indicador respondem 422 GOAL_TARGET_INVALID.

Contrato de comparação com o realizado

GET /v1/goals/:id devolve o histórico da meta: goalId, targetKind, unitId, personId, indicatorCode, indicatorName, measureUnit, direction, scale, periodStart, periodEnd, closedOn, closeReason, reversedAt, reverseReason e versions[], cada versão com version, target, reason, validFrom e validTo. Meta de outro cliente ou inexistente responde 404.

Este sistema guarda só o alvo. O Hub e o nead-hub-api leem as metas vigentes e medem o realizado com as métricas deles.

1. Ler GET /v1/units/:id/goals?on=AAAA-MM-DD ou GET /v1/people/:id/goals?on=AAAA-MM-DD. Cada item traz goalId, targetKind, unitId ou personId, indicatorCode, indicatorName, measureUnit, direction, scale, periodStart, periodEnd, closedOn, effectiveEnd, target, version e versionValidFrom.
2. O nead-hub-api mantém a correspondência entre o código do indicador, definido no catálogo do cliente, e a métrica que ele mede. Indicador sem correspondência fica sem estado de meta.
3. A janela do realizado vai de periodStart até effectiveEnd (o encerramento, se houver, senão o fim do período), com os dois dias incluídos.
4. O estado final usa o alvo vigente em effectiveEnd (ler com on=effectiveEnd). Antes disso, a meta está em andamento.
5. target e o realizado se comparam como decimais exatos, nunca como números em ponto flutuante: higher-is-better → batida se realizado ≥ alvo; lower-is-better → batida se realizado ≤ alvo. Igual ao alvo é batida.
6. Os fatos goal.created, goal.revised, goal.closed e goal.reversed avisam mudanças para quem guarda cópia.

Rotas da implantação de cliente

Valem as mesmas convenções das rotas da base de cadastro.

Criação de cliente com modelo

O corpo aceita templateOn, data no formato AAAA-MM-DD, opcional. O modelo é aplicado com vigência desde essa data; sem ela, desde o dia da criação (RN-ORG-321). Data em outro formato devolve 400.

Leituras de integração

Leituras para o servidor do Hub (RN-ORG-333). Todas exigem people.read. As três últimas usam o dia de hoje quando on não é informado.

Lista de todo o cliente só é permitida a quem tem a permissão configurada sem depender de unidade.

Camadas do domínio

• Overview do domínio
• Entidades e relacionamentos
• Histórias do usuário
• Sitemap
• Regras de negócio
• API Reference