Consulta de status e relatório

Toda carga aceita pela API retorna um identificador (Guid). Com ele é possível acompanhar o processamento e, ao final, consultar um relatório resumido das alterações.

Headers comuns:

• Authorization: Bearer {access_token}

GET /v3/cargas/{cargaId}

Consulta a situação de um pedido de carga específico (cargas de patriarca ou de órgão avulso).

GET /v3/cargas/{cargaId}

Parâmetros de rota

Nome	Tipo	Obrigatório	Descrição
cargaId	GUID	Sim	Identificador do pedido de carga.

Resposta

• 200 OK com um objeto CargaViewModel (descrito abaixo).
• Erros de validação/autorização retornam 4xx.

Esse endpoint é pensado para ser usado em consulta periódica (polling) até a carga ser concluída ou falhar.

Para importações iniciais, use o endpoint equivalente GET /v3/importacoes-iniciais/{cargaId}.

GET /v3/cargas/{cargaId}/relatorio

Retorna o relatório resumido de uma carga, com os totais de inclusões, alterações e remoções calculados no processamento (ou na simulação, quando a carga foi enviada com dryRun=true).

GET /v3/cargas/{cargaId}/relatorio

Parâmetros de rota

Nome	Tipo	Obrigatório	Descrição
cargaId	GUID	Sim	Identificador do pedido de carga.

Resposta

• 200 OK com um objeto RelatorioCarga (descrito abaixo).
• Erros de validação/autorização retornam 4xx.

Objeto CargaViewModel

Objeto de status retornado pelas consultas de carga.

{
  "Guid": "3f7c2b7e-0a8e-4f5b-a12b-2a3b4c5d6e7f",
  "Tipo": 7,
  "OrganizacaoRaiz": "8f1d9f5b-0a8e-4f5b-a12b-2a3b4c5d6e7f",
  "Status": 5,
  "DataSolicitacaoInicialUtc": "2026-08-27T12:00:00Z",
  "DataUltimaAtualizacaoUtc": "2026-08-27T12:05:00Z",
  "MensagemErro": null,
  "Finalizada": true
}

Campo	Tipo	Descrição
Guid	string (GUID)	Identificador do pedido de carga.
Tipo	inteiro (enum)	Tipo da carga. Veja a tabela TipoCarga abaixo.
OrganizacaoRaiz	string (GUID)	Patriarca ou órgão raiz ao qual a carga pertence.
Status	inteiro (enum)	Situação atual do processamento. Veja a tabela StatusCarga abaixo.
DataSolicitacaoInicialUtc	string (data UTC)	Momento em que o pedido de carga foi recebido.
DataUltimaAtualizacaoUtc	string (data UTC)	Momento da última mudança de situação.
MensagemErro	string ou null	Mensagem de erro, quando o processamento falhou.
Finalizada	boolean	true quando o processamento terminou (com sucesso ou erro).

Valores de Tipo (TipoCarga)

Os enums são serializados como inteiros. Valores usados pela v3:

Valor	Nome	Descrição
3	InicialOrganograma	Importação inicial de organograma.
4	InicialLotacoes	Importação inicial de lotações.
5	InicialLotacoesPacote	Importação inicial de lotações em pacote.
7	CargaOrganograma	Carga de organograma de patriarca.
8	CargaLotacoes	Carga de lotações de patriarca.
9	CargaLotacoesPacote	Carga de lotações em pacote (patriarca).
10	GrupoCarga	Pacote completo de patriarca.
11	CargaOrgaoAvulsoOrganograma	Carga de organograma de órgão avulso.
12	CargaOrgaoAvulsoLotacoes	Carga de lotações de órgão avulso.
13	CargaOrgaoAvulsoLotacoesPacote	Carga de lotações em pacote (órgão avulso).
14	GrupoCargaOrgaoAvulso	Pacote completo de órgão avulso.

Os valores 0, 1, 2 e 6 pertencem a versões anteriores da API e não são gerados pelos endpoints da v3.

Valores de Status (StatusCarga)

Valor	Nome	Descrição
0	AguardandoAnaliseInicial	Pedido recebido, aguardando validação e análise.
1	AguardandoOrganograma	Aguardando processamento no Organograma.
2	OrganogramaFinalizado	Etapa de organograma concluída.
3	AguardandoAcessoCidadao	Aguardando processamento no Acesso Cidadão.
4	AcessoCidadaoFinalizado	Etapa do Acesso Cidadão concluída.
5	Finalizado	Carga concluída com sucesso.
6	Erro	Carga finalizada com erro (veja MensagemErro).
7	AguardandoAcessoCidadaoLotacao	Aguardando processamento de lotações no Acesso Cidadão.
8	AguardandoOrganogramaCargaInicial	Importação inicial aguardando o Organograma.
9	AguardandoLotacaoCargaInicial	Importação inicial aguardando a etapa de lotação.
10	AguardandoLotacaoCargaInicialPacote	Pacote de importação inicial aguardando a etapa de lotação.

Para encerrar o polling, observe o campo Finalizada: quando true, a carga chegou a um estado final (Finalizado ou Erro).

Objeto RelatorioCarga

Relatório resumido das alterações de uma carga.

{
  "CargaId": "3f7c2b7e-0a8e-4f5b-a12b-2a3b4c5d6e7f",
  "Tipo": "organograma",
  "Modo": 0,
  "GeradoEm": "2026-08-27T12:05:00+00:00",
  "Totais": { "Inseridos": 13, "Alterados": 3, "Removidos": 4 },
  "PorEntidade": [
    {
      "Entidade": "orgao",
      "Totais": { "Inseridos": 3, "Alterados": 1, "Removidos": 0 },
      "Observacao": null
    },
    {
      "Entidade": "unidade",
      "Totais": { "Inseridos": 10, "Alterados": 2, "Removidos": 4 },
      "Observacao": null
    }
  ],
  "PorOrgao": null
}

Campo	Tipo	Descrição
CargaId	string (GUID)	Identificador da carga.
Tipo	string	Tipo da carga: "organograma", "lotacoes", "pacote-completo" ou "importacao-inicial".
Modo	inteiro (enum)	0 = Aplicar (carga executada); 1 = Avaliacao (simulação com dryRun=true).
GeradoEm	string (data)	Momento em que o relatório foi gerado.
Totais	objeto	Totais gerais: Inseridos, Alterados e Removidos (inteiros).
PorEntidade	array	Totais por tipo de entidade. Cada item tem Entidade, Totais e Observacao (string ou null).
PorOrgao	array ou null	Detalhamento por órgão, quando aplicável (pacotes). Cada item tem OrgaoId, OrgaoNome, Totais, PorEntidade, Sucesso e Erro.

Valores possíveis de Entidade: "orgao", "unidade", "setor", "ocupacao", "lotacaoServidor", "lotacaoComissao", "lotacaoTerceiro" e "grupo".