API: endpoints

Todos os endpoints exigem o cabeçalho Authorization: Bearer {token} (veja API: autenticação) e respondem em JSON. Os identificadores nos caminhos são GUIDs.

Os exemplos usam identificadores fictícios.

Patriarca

GET /v2/patriarcas/{id}

Retorna um patriarca.

GET /v2/patriarcas/3ca6ea0e-ca14-46fa-a911-22e616303722 HTTP/1.1
Host: apiv2.organograma.es.gov.br
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

{
  "id": "3ca6ea0e-ca14-46fa-a911-22e616303722",
  "nome": "Governo do Estado do Espírito Santo",
  "sigla": "GOVES",
  "slug": "goves",
  "publico": true,
  "idOrganizacaoRaiz": "a1b2c3d4-0000-4000-8000-000000000001"
}

Propriedade	Tipo	Descrição
id	GUID	Identificador do patriarca
nome	texto	Nome do patriarca
sigla	texto	Sigla do patriarca
slug	texto ou null	Identificador amigável (veja Visibilidade pública)
publico	booleano	Se o patriarca é exibido no site público
idOrganizacaoRaiz	GUID	Identificador do órgão raiz do patriarca

Respostas: 200, 401, 403, 404.

GET /v2/patriarcas/{id}/orgaos

Retorna todos os órgãos ativos do patriarca, incluindo o órgão raiz.

[
  {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "nome": "Governo do Estado do Espírito Santo",
    "sigla": "GOVES",
    "idPatriarca": "3ca6ea0e-ca14-46fa-a911-22e616303722"
  },
  {
    "id": "a1b2c3d4-0000-4000-8000-000000000002",
    "nome": "Secretaria de Estado de Exemplo",
    "sigla": "SEEX",
    "idPatriarca": "3ca6ea0e-ca14-46fa-a911-22e616303722"
  }
]

Os itens têm o mesmo formato de GET /v2/orgaos/{id}. Para identificar a raiz, compare o id de cada órgão com o idOrganizacaoRaiz do patriarca.

Respostas: 200 (lista vazia se o patriarca não existir), 401, 403.

Órgão

GET /v2/orgaos/{id}

Retorna um órgão.

{
  "id": "a1b2c3d4-0000-4000-8000-000000000002",
  "nome": "Secretaria de Estado de Exemplo",
  "sigla": "SEEX",
  "idPatriarca": "3ca6ea0e-ca14-46fa-a911-22e616303722"
}

Propriedade	Tipo	Descrição
id	GUID	Identificador do órgão
nome	texto	Nome do órgão
sigla	texto	Sigla do órgão
idPatriarca	GUID	Identificador do patriarca a que o órgão pertence

Respostas: 200, 401, 403, 404.

GET /v2/orgaos/{id}/unidades

Retorna todas as unidades ativas do órgão, de todos os níveis, em uma lista plana. A hierarquia é dada por idUnidadePai.

[
  {
    "id": "b2c3d4e5-0000-4000-8000-000000000010",
    "nome": "Subsecretaria de Administração",
    "sigla": "SUBAD",
    "idUnidadePai": null,
    "idOrganizacao": "a1b2c3d4-0000-4000-8000-000000000002"
  },
  {
    "id": "b2c3d4e5-0000-4000-8000-000000000011",
    "nome": "Gerência de Recursos Humanos",
    "sigla": "GRH",
    "idUnidadePai": "b2c3d4e5-0000-4000-8000-000000000010",
    "idOrganizacao": "a1b2c3d4-0000-4000-8000-000000000002"
  }
]

Os itens têm o mesmo formato de GET /v2/unidades/{id}.

Respostas: 200 (lista vazia se o órgão não existir ou não tiver unidades), 401, 403.

Unidade

GET /v2/unidades/{id}

Retorna uma unidade.

{
  "id": "b2c3d4e5-0000-4000-8000-000000000011",
  "nome": "Gerência de Recursos Humanos",
  "sigla": "GRH",
  "idUnidadePai": "b2c3d4e5-0000-4000-8000-000000000010",
  "idOrganizacao": "a1b2c3d4-0000-4000-8000-000000000002"
}

Propriedade	Tipo	Descrição
id	GUID	Identificador da unidade
nome	texto	Nome da unidade
sigla	texto	Sigla da unidade
idUnidadePai	GUID ou null	Identificador da unidade imediatamente acima; null para unidades do primeiro nível do órgão
idOrganizacao	GUID	Identificador do órgão a que a unidade pertence

Respostas: 200, 401, 403, 404.

Montar a árvore de unidades

GET /v2/orgaos/{id}/unidades devolve as unidades sem ordem definida. Para montar a árvore, agrupe pelo idUnidadePai:

public record Unidade(Guid Id, string Nome, string Sigla, Guid? IdUnidadePai, Guid IdOrganizacao);

public record No(Unidade Unidade, List<No> Filhas);

static List<No> MontarArvore(IReadOnlyCollection<Unidade> unidades)
{
    var porPai = unidades.ToLookup(u => u.IdUnidadePai);

    List<No> Filhas(Guid? idPai) => porPai[idPai]
        .OrderBy(u => u.Nome)
        .Select(u => new No(u, Filhas(u.Id)))
        .ToList();

    return Filhas(null);
}

O mesmo em JavaScript:

function montarArvore(unidades) {
  const porPai = new Map();
  for (const u of unidades) {
    const chave = u.idUnidadePai ?? null;
    if (!porPai.has(chave)) porPai.set(chave, []);
    porPai.get(chave).push(u);
  }
  const filhas = (idPai) =>
    (porPai.get(idPai) ?? [])
      .sort((a, b) => a.nome.localeCompare(b.nome, 'pt-BR'))
      .map((u) => ({ ...u, filhas: filhas(u.id) }));
  return filhas(null);
}

Percorrer a estrutura completa

Para obter toda a estrutura de uma instituição:

1. GET /v2/patriarcas/{id}/orgaos para listar os órgãos;
2. para cada órgão, GET /v2/orgaos/{id}/unidades;
3. monte a árvore de cada órgão como acima.

Faça essa sincronização periodicamente e guarde o resultado; veja boas práticas.