Erros comuns na integração

Esta página lista os erros mais comuns ao integrar com o CargaRH e como evitá-los.

---

1. Campos obrigatórios nulos ou vazios

Sintoma

• HTTP 400 (Bad Request), com mensagens do tipo:
  • A chave externa não pode ser nula ou vazia.
  • O nome da unidade não pode ser nulo ou vazio.
  • Um CPF não pode ser nulo ou vazio.

Causas comuns

• Campos obrigatórios ausentes no JSON.
• Campos enviados como "" (string vazia) ao invés de um valor válido.
• Serialização que remove propriedades com null sem preencher os valores.

Como evitar

• Tratar todos os campos obrigatórios como required no modelo do sistema integrador.

---

2. Textos maiores que o limite

Sintoma

• HTTP 400, com mensagens parecidas com:
  • Uma chave externa deve conter no máximo 200 caracteres.
  • Um nome de órgão deve conter no máximo 100 caracteres.
  • Uma sigla de órgão deve conter no máximo 20 caracteres.
  • Uma sigla de unidade deve conter no máximo 25 caracteres.

Causas comuns

• Usar descrições muito longas como “chave externa”.
• Nomes e siglas copiados de campos livres sem qualquer limitação.
• Importação direta de textos de outro sistema sem truncar.

Como evitar

• Aplicar os mesmos limites de tamanho no sistema de origem:
  • ChaveExterna: até 200 caracteres.
  • Nome (órgão/unidade/ocupação/comissão): até 100 caracteres.
  • Sigla órgão: até 20 caracteres.
  • Sigla unidade: até 25 caracteres.

---

3. CPF inválido

Sintoma

• HTTP 400 com mensagem do tipo:
  • Esse é um valor inválido para CPF: 12345678900.

Causas comuns

• CPF com menos de 11 dígitos ou com caracteres não numéricos.
• CPF com dígitos verificadores incorretos.
• CPF gerado de teste que não passa na validação.

Como evitar

• Sempre enviar CPF apenas com números, com 11 dígitos.
• Aplicar validação de CPF no sistema de origem (mesma regra do backend):
  • remover máscara;
  • checar se há 11 dígitos;
  • validar dígitos verificadores.
• Evitar usar CPFs “inventados” em ambientes que usam regras reais.

---

4. Referências a unidades, órgãos, ocupações ou comissões inexistentes

Sintoma

• HTTP 400, com mensagens indicando que uma chave não foi encontrada ou não pertence ao escopo esperado (mensagens típicas de regra de negócio, fora dos ValueObjects).

Exemplos de situações que geram esse tipo de erro:

• ChaveExternaUnidade em uma LotacaoServidorEntrada não existe na estrutura de unidades do órgão.
• ChaveExternaOcupacao não existe na lista de ocupações enviada na mesma carga.
• ChaveExternaComissao em LotacaoComissaoEntrada não está na lista de comissões da carga.

Causas comuns

• Divergência entre as chaves usadas internamente e as chaves usadas na carga.
• Reaproveitamento indevido de chaves externas.

Como evitar

• Garantir que:
  • unidades, ocupações e comissões existam antes de criar lotações que as usem;
  • as ChaveExterna* da carga estejam exatamente iguais às usadas na carga de organograma e nas listas de ocupações/comissões.
• Manter um mapeamento confiável entre IDs internos do sistema de origem e ChaveExterna usadas no CargaRH.

---

5. Hierarquia de unidades inválida

Sintoma

• Mensagens de erro relacionadas a ChaveUnidadePai (unidade pai inexistente ou inválida).

Causas comuns

• ChaveUnidadePai apontando para uma unidade que não existe na lista de unidades do órgão.
• Referência cruzada entre órgãos (unidade pai de outro órgão).
• Ciclos na hierarquia (unidade A sendo pai de B e B sendo pai de A, direta ou indiretamente).

Como evitar

• Validar no sistema de origem:
  • se a unidade pai existe no mesmo órgão;
  • se não há ciclos na árvore de unidades.
• Gerar a estrutura de unidades a partir de uma representação hierárquica bem definida (árvore) e não a partir de linhas soltas sem validação.

---

6. Órgãos repetidos em carga de pacote

Sintoma

• HTTP 400 ao chamar POST /v3/Carga/lotacoes/pacote/{guidPatriarcaRaiz} quando a mesma ChaveExternaOrgao aparece mais de uma vez no array.

Causas comuns

• Agrupamento incorreto de lotações por órgão antes de montar o JSON.
• Duplicação de objetos CargaLotacaoEntrada para o mesmo órgão.

Como evitar

• Antes de montar a carga de pacote, agrupar as lotações por órgão e garantir um único objeto CargaLotacaoEntrada por ChaveExternaOrgao.
• Se houver risco de repetição, validar localmente (ex.: lista de chaves únicas) e bloquear a geração do JSON com duplicatas.

---

7. Inconsistência entre PatriarcaId e GUID da rota

Sintoma

• HTTP 400 ao enviar uma carga em um endpoint como:
  • POST /v3/Carga/organograma/{guidPatriarcaRaiz}
  • POST /v3/Carga/lotacoes/{guidPatriarcaRaiz}
• quando o PatriarcaId do JSON não bate com o guidPatriarcaRaiz da rota.

Causas comuns

• Reaproveitar o mesmo JSON para outro patriarca sem atualizar o campo PatriarcaId.
• Erro de mapeamento em sistemas que atendem a mais de um patriarca.

Como evitar

• Geração de JSON sempre amarrada ao patriarca da rota:
  • montar o objeto de carga já com o PatriarcaId correto;
  • usar uma única fonte para o GUID do patriarca (ex.: configuração).

---

8. Carga enviada enquanto outra ainda está em processamento

Sintoma

• HTTP 400 ou 409 indicando que há uma carga em processamento para o mesmo patriarca/órgão.

Causas comuns

• Job agendado rodando em paralelo ou em intervalo muito curto.
• Reenvio manual antes do término da carga anterior.

Como evitar

• Usar o endpoint de pacote de lotações quando houver muitos órgãos.
• Controlar no sistema de origem:
  • o identificador (Guid) da carga enviada;
  • o status retornado pelos endpoints de status e ultimasStatus.
• Não disparar nova carga automática enquanto a anterior não estiver concluída com sucesso ou erro.

---

9. JSON malformado ou tipos incorretos

Sintoma

• HTTP 400 antes mesmo de chegar às validações de negócio.

Causas comuns

• JSON inválido (vírgula sobrando, aspas faltando, tipos trocados).
• Enviar números no lugar de strings (ex.: CPF como número, GUID como número).
• Erros na serialização customizada.

Como evitar

• Usar uma biblioteca de serialização consolidada (ex.: System.Text.Json, Newtonsoft.Json) sem montar JSON “na mão”.
• Tratar todos os campos que são string no modelo C# como string também na origem, mesmo quando o conteúdo é numérico (CPF, GUID, chaves externas).