Pular para o conteúdo principal

🔐 Autenticação e Acesso à API

🌐 Ambientes da API​

Antes de iniciar a integração, é importante utilizar o ambiente correto:

  • Produção: https://api.notifica.es.gov.br

  • Homologação (testes): https://api.notifica.hom.es.gov.br

⚠️ Recomendamos que toda integração seja validada primeiro no ambiente de homologação antes de ser promovida para produção.

🔑 Modelo de Autenticação​

O acesso à API do NotificaES é realizado por meio do SSO do Acesso Cidadão, utilizando o fluxo:

OAuth2 – Client Credentials (Novo)

Isso significa que a autenticação é feita entre sistemas (machine-to-machine), sem interação direta do usuário.

🏛️ ⚠️ Pré-requisitos obrigatórios (Autorização interna)​

Antes de consumir a API, é necessário:

  1. Solicitar à equipe SUSEST – Sistemas Estruturantes:

    • Liberação do seu sistema no Acesso Cidadão
    • Credenciais de acesso (Client ID e Client Secret)

  2. Garantir que seu sistema possui os escopos (scopes) necessários para as operações desejadas

  3. Antes de consumir a API, além da autenticação técnica, existe uma etapa obrigatória de autorização interna na plataforma NotificaES.

🚨 IMPORTANTE: Apenas possuir token válido não garante acesso à API.

Para que seu sistema consiga enviar notificações, é necessário que a equipe SUSEST – Sistemas Estruturantes realize as seguintes configurações internas da plataforma:

  • O sistema requisitante deve ser cadastrado e autorizado na plataforma;
  • Deve ser criado pelo menos uma categoria de notificação
  • Essa categoria será utilizada no momento do envio das notificações

⚠️ Sem categoria cadastrada, não será possível enviar notificações, mesmo com autenticação válida.

🔄 Fluxo de Autenticação​

1. Obtenção do Token​

O token de acesso deve ser obtido diretamente na API do Acesso Cidadão, utilizando o fluxo Client Credentials.

A resposta será um:

  • 🔐 JWT (JSON Web Token)

Esse token contém:

  • Permissões (scopes)
  • Tempo de expiração
  • Identificação da aplicação

2. Utilização do Token​

Após obter o token, ele deve ser enviado em todas as requisições para o NotificaES no header:

Authorization: Bearer {seu_token_jwt}

3. Expiração do Token​

  • O token possui um tempo de vida limitado
  • Após expirar, será necessário gerar um novo token

💡 Recomendação: implemente uma rotina automática de renovação de token para evitar falhas de autenticação.

⚠️ Controle de Acesso (Scopes)​

Cada endpoint da API exige permissões específicas.

🔎 IMPORTANTE: Sempre verifique na documentação de cada endpoint quais são os scopes necessários.

Caso o token não possua permissão suficiente, a API retornará erro de autorização.

🚫 Possíveis Erros relacionados a autenticação e autorização​

CódigoDescrição
401Token inválido ou expirado
403Sem permissão (scope insuficiente)

🚀 Próximo Passo​

Após configurar a autenticação, você já pode:

👉 Consumir os endpoints do sistema NotificaES

Consulte a próxima seção da documentação sobre as funcionalidades dos endpoints disponíveis na aplicação.