Pular para o conteúdo principal

Conceitos e fluxo de carga

Carga completa por escopo​

O CargaRH trabalha sempre com carga completa, nunca com “diff”.

Em cada chamada você pode enviar:

  • para um patriarca: toda a estrutura daquele patriarca (todos os orgãos e a estrutura de unidades de cada um);
  • para um órgão: todas as lotações daquele órgão (seguindo a hierarquia de unidades);
  • para um pacote de órgãos: vários objetos de carga de orgão, como específicado acima, mas em pacotes com mais de um orgão;
  • para um pacote completo: organograma e lotações juntos, em uma única carga.

O sistema compara o conteúdo enviado com o que já existe e faz:

  • inclusões para o que é novo;
  • atualizações para o que mudou;
  • exclusões para o que deixou de existir na carga.
Importante

Tudo o que NÃO for enviado dentro do escopo da carga pode ser considerado para exclusão. Cada carga deve representar a visão completa e atual do seu sistema para aquele patriarca/órgão.

Patriarca, órgãos e unidades​

  • Patriarca: raiz lógica de uma estrutura organizacional (por exemplo, “Governo do ES”, "Prefeitura de Vitória").
  • Órgão: é a unidade administrativa de primeiro nível dentro de um patriarca, responsável por um conjunto próprio de competências (por exemplo: secretaria, autarquia, fundação, instituto, etc.), que agrupa setores e lotações. Secretarias que não possuem CNPJ próprio podem (e devem) ser modeladas como órgãos, desde que sejam reconhecidas na estrutura oficial do ente como unidades administrativas com competências próprias.
  • Unidade: unidades internas do órgão (departamentos, gerências etc.).

A carga de organograma envia todos os órgãos do patriarca e, dentro de cada órgão, suas unidades e a relação hierárquica entre elas.

Lotações, ocupações, comissões e gestores​

No CargaRH:

  • você cadastra ocupações (cargos/funções) que podem ser usadas em lotações. Podem ser dos tipos:
    • servidor (gerente, analista, técnico, etc.)
    • comissão (presidente, membro, suplente, etc.);
  • uma lotação de servidor liga:
    • um CPF
    • a uma unidade
    • e a uma ocupação;
  • uma comissão agrupa pessoas em ocupações específicas dentro daquele órgão;
  • uma lotação em comissão liga um CPF a uma comissão e a uma ocupação do tipo comissão;
  • um gestor é um vínculo que indica qual CPF é gestor de determinada unidade, com determinada ocupação. Não é necessário que o gestor esteja lotado na unidade que ele gerencia. Caso ele não esteja lotado na unidade que ele gerencia, a unidade da lotação de gestor deve ser informada separadamente junto com a informação de gestão.

Essas estruturas são enviadas juntas na carga de lotações.

Importação inicial × carga regular​

A importação inicial é usada uma única vez, na primeira carga de um patriarca, quando a estrutura ainda não existe nos sistemas corporativos. Como não há ChaveExterna cadastrada, ela identifica órgãos e unidades pelas siglas:

  • POST /v3/importacoes-iniciais/patriarcas/{patriarcaId}/organograma
  • POST /v3/importacoes-iniciais/patriarcas/{patriarcaId}/lotacoes
  • POST /v3/importacoes-iniciais/patriarcas/{patriarcaId}/lotacoes/pacote

Depois da importação inicial, a expectativa é que as atualizações sejam feitas de forma manual. Caso exista sistema responsável por carga futura, o correto é usar as cargas regulares (abaixo), que identificam as entidades pela ChaveExterna do seu sistema.

Cargas por patriarca​

Os endpoints de patriarca são usados quando a autorização do CargaRH tem escopo para o patriarca inteiro:

  • POST /v3/cargas/patriarcas/{patriarcaId}/organograma
  • POST /v3/cargas/patriarcas/{patriarcaId}/orgaos/{orgaoId}/organograma
  • POST /v3/cargas/patriarcas/{patriarcaId}/lotacoes
  • POST /v3/cargas/patriarcas/{patriarcaId}/lotacoes/pacote
  • POST /v3/cargas/patriarcas/{patriarcaId}/pacote-completo

Enquanto uma carga estiver em processamento para um patriarca, novas cargas para o mesmo patriarca vão ser recusadas. Por isso, quando há muitos órgãos, recomenda-se usar o endpoint de pacote de lotações (ou o pacote completo) para enviar várias lotações de órgão de uma vez, sem repetir órgãos na lista.

Cargas por órgão avulso​

Alguns órgãos dentro de um patriarca (por exemplo, empresas públicas como Banestes ou Cesan) possuem gestão própria de suas informações de RH.

Para esses casos:

  • a carga por patriarca ignora esse órgão;

  • o cadastro do órgão é mantido manualmente no Organograma;

  • existem uma autorização e endpoints específicos para ele:

  • POST /v3/cargas/orgaos/{orgaoId}/organograma

  • POST /v3/cargas/orgaos/{orgaoId}/lotacoes

  • POST /v3/cargas/orgaos/{orgaoId}/pacote-completo

Assim, o órgão avulso controla suas informações de forma independente, sem depender da carga do patriarca inteiro.

Simulação (dryRun)​

Todos os endpoints de envio de carga aceitam o parâmetro de query dryRun=true. Nesse modo, a carga passa pelas mesmas validações e o sistema calcula as inclusões, alterações e exclusões que seriam feitas, mas nada é persistido.

O resultado da simulação pode ser consultado pelo endpoint de relatório da carga, que também está disponível para cargas efetivamente aplicadas.

Consulta de status e relatório​

Toda carga gera um identificador (Guid) que pode ser usado para consultar o status do processamento:

  • GET /v3/cargas/{cargaId} — status de uma carga específica;
  • GET /v3/cargas/{cargaId}/relatorio — relatório resumido das alterações;
  • GET /v3/cargas/patriarcas/{patriarcaId}?limit= — últimas cargas de um patriarca;
  • GET /v3/cargas/orgaos/{orgaoId}?limit= — últimas cargas de um órgão avulso;
  • GET /v3/importacoes-iniciais/{cargaId} — status de uma importação inicial;
  • GET /v3/importacoes-iniciais/patriarcas/{patriarcaId}?limit= — últimas importações iniciais.

Isso permite que o sistema integrador acompanhe o resultado das cargas sem intervenção manual.

Última atualização em