API: visão geral

A API do Organograma ES permite que sistemas autorizados consultem a estrutura organizacional: patriarcas, órgãos e unidades.

Características

Item	Valor
Endereço base	https://apiv2.organograma.es.gov.br
Versão	v2 (no caminho: /v2/...)
Operações	Somente consulta (GET)
Formato	JSON, com nomes de propriedades em camelCase
Autenticação	OAuth 2.0, client credentials, com token do Acesso Cidadão. Veja API: autenticação
Paginação	Não há. Cada consulta devolve a lista completa
Documentação interativa	https://apiv2.organograma.es.gov.br/swagger
Especificação OpenAPI	https://apiv2.organograma.es.gov.br/openapi/v2.json

A API não altera dados. Alterações na estrutura são feitas na administração ou chegam por carga.

Recursos

Método	Caminho	Retorna
GET	/v2/patriarcas/{id}	Um patriarca
GET	/v2/patriarcas/{id}/orgaos	Os órgãos do patriarca
GET	/v2/orgaos/{id}	Um órgão
GET	/v2/orgaos/{id}/unidades	Todas as unidades do órgão, em lista plana
GET	/v2/unidades/{id}	Uma unidade

Os detalhes de cada recurso estão em API: endpoints.

Identificadores

Todos os recursos são consultados pelo identificador (GUID). Guarde os identificadores no seu sistema, não as siglas: veja Conceitos.

O identificador do patriarca da sua instituição é informado na liberação do acesso à API.

Registros vigentes

A API devolve somente registros ativos. Um órgão ou uma unidade excluído deixa de aparecer nas listas, e a consulta pelo identificador dele responde 404.

Se o seu sistema guarda identificadores, trate o 404 como "registro não vigente" e não como erro de integração.

Atualização dos dados

As alterações feitas na administração ou recebidas por carga chegam à API em alguns minutos. Para manter uma cópia local da estrutura, recomenda-se sincronizar periodicamente (por exemplo, uma vez por dia ou a cada hora) em vez de consultar a API a cada operação do seu sistema.

Respostas de erro

Os erros seguem o formato Problem Details (RFC 7807), com Content-Type: application/problem+json.

Status	Significado
200	Sucesso
401	Token ausente, inválido ou expirado
403	Token válido, mas sem o escopo exigido ou emitido para outro ambiente
404	Registro não encontrado ou não vigente
500	Falha interna. Tente novamente mais tarde e, se persistir, acione o suporte

Exemplo:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "Falha ao buscar órgão.",
  "status": 500
}

Boas práticas

• Reutilize o token até perto da expiração; não peça um token novo a cada chamada.
• Guarde em cache as respostas e sincronize periodicamente.
• Não dependa da ordem dos itens nas listas.
• Ignore propriedades desconhecidas: novas propriedades podem ser acrescentadas sem mudança de versão.