Pular para o conteúdo principal

Boas práticas de uso do CargaRH

Algumas recomendações para deixar a integração mais estável, previsível e fácil de operar.

1. Comece sempre por homologação​

  • Configure primeiro o acesso ao ambiente de homologação:
    • token do Acesso Cidadão apontando para o endpoint de homologação;
    • base de dados de teste no seu sistema de origem.
  • Valide:
    • estrutura de organograma (órgãos/unidades);
    • estrutura de lotações (ocupações, lotações, comissões, gestores);
    • mensagens de erro e tratamento no seu sistema.

Depois de estabilizar o processo, solicite habilitação em produção.

2. Defina regras claras para ChaveExterna​

  • Use chaves estáveis e não significativas demais:
    • se seu sistema tiver IDs internos, prefira usá-los como ChaveExterna;
    • não use textos enormes ou nomes completos como chave;
    • prefira códigos curtos, internos do sistema (ex.: ORG-SESA, UNID-GERH).
  • Nunca reutilize a mesma ChaveExterna para entidades diferentes.
  • Se um órgão/unidade for extinto e outro criado, crie uma nova chave.

Isso reduz risco de “mixar” dados históricos com entidades novas.

3. Replique no sistema de origem as validações de tamanho e formato​

  • Implemente as mesmas regras dos value objects:
    • limites de caracteres (200, 100, 20, 25);
    • normalização de espaços;
    • validação de CPF.
  • Valide antes de gerar a carga:
    • evita enviar dados que serão recusados de qualquer forma;
    • facilita mostrar mensagens de erro amigáveis para o usuário do seu sistema.

Sempre que possível, valide no momento do cadastro ou edição, não só na exportação.

4. Trate a carga como “foto completa” do escopo​

  • Monte a carga pensando em snapshot:
    • para aquele patriarca/órgão, a carga representa tudo que existe hoje;
    • o que não está na carga pode ser removido.
  • Evite gerar cargas “parciais” por tipo de dado (só ocupações, só algumas lotações).
  • Tenha um processo claro de:
    • extrair todos os registros;
    • transformar para o modelo do CargaRH;
    • enviar.

Se precisar de “ajustes pontuais”, faça-os no sistema de origem e deixe a próxima carga refletir a situação correta.

5. Use o endpoint de pacote para muitos órgãos​

Quando um patriarca tem muitos órgãos:

  • prefira POST /v3/Carga/lotacoes/pacote/{guidPatriarcaRaiz}:
    • envia as lotações de vários órgãos de uma vez;
    • respeitando a regra de não repetir ChaveExternaOrgao.
  • Isso reduz o número de chamadas HTTP e o tempo total de atualização.

No seu job de carga:

  1. Agrupe as lotações por órgão.
  2. Monte um array de CargaLotacaoEntrada.
  3. Envie em um único request (ou em poucos pacotes controlados, se o volume for muito grande).

6. Registre sempre o identificador da carga​

Cada chamada de carga retorna um Guid de identificação.

Boas práticas:

  • Salvar esse Guid numa tabela de log da sua integração, junto com:
    • data/hora;
    • tipo de carga (organograma, lotações, pacote, órgão avulso);
    • quem disparou (job, usuário, sistema).
  • A partir desse Guid, consultar:
    • GET /v3/Carga/{guid}/status
    • ou GET /v3/CargaOrgaoAvulso/{guid}/status

Isso facilita:

  • rastrear problemas;
  • exibir status em telas internas;
  • responder a dúvidas ou chamados.

7. Controle a frequência das cargas​

  • Evite rodar cargas em frequência desnecessariamente alta se os dados não mudam tanto.
  • Em muitos cenários, é suficiente:
    • carga diária (ou algumas vezes por dia);
    • carga adicional em horários específicos de fechamento de folha ou mudanças grandes.

Para alterações muito pontuais e raras, vale considerar:

  • carga agendada em horários de menor uso;
  • ou janelas definidas em conjunto com a equipe do PRODEST.

8. Tenha um processo de retry controlado​

Falhas podem ocorrer (rede, indisponibilidade temporária, erro de dados).

Boas práticas:

  • Diferenciar o tipo de erro:
    • problemas de dados (400) → corrigir origem antes de reenviar;
    • problemas transientes (502, 503, 504) → retry com backoff.
  • Evitar loops de retry infinito:
    • limitar tentativas;
    • registrar falhas em log e notificar alguém responsável.

9. Não corrija “na mão” o que vem do CargaRH​

  • A ideia do CargaRH é ser a fonte de alimentação principal dos sistemas Organograma/LotaçãoES.
  • Evite correções manuais diretamente nesses sistemas para dados que são alimentados por carga:
    • na próxima carga, os dados podem ser sobrescritos novamente.

Em vez disso:

  • ajuste o dado no sistema de origem;
  • deixe a próxima carga refletir a correção.

10. Separe bem ambientes de teste, homologação e produção​

  • Use bases de origem diferentes ou bem sinalizadas para:
    • testes locais;
    • homologação;
    • produção.
  • Cuidado especial com CPFs em ambientes de teste:
    • se possível, use CPFs de teste acordados com o PRODEST;
    • evite dados sensíveis reais em ambientes de desenvolvimento.

Essas práticas não são obrigatórias pela API, mas ajudam muito a reduzir falhas, facilitar suporte e manter os dados dos sistemas corporativos consistentes com o que seu sistema de origem envia.

Última atualização em