Widgets

Você pode conectar os usuários do seu sistema com a habilitar.me através do widget de login.

Com um fluxo de login customizado e seguro, o seu usuário poderá compartilhar as informações da CNH dele com você.

Gerenciamento

Gerencie os widgets da sua organização através do Console da habilitar.me.

Após a criação, é disponibilizado um link de acesso que permite você incluir no seu código, ou compartilhar com seus usuários.

Veja abaixo as customizações disponíveis para o widget de login.

Customizações

Name
Nome da Organização
Description
Nome da organização que será exibido no widget.
Name
Cor Principal
Description
Cor de botões de links do widget.
Name
Logo
Description
Logo da organização que será exibida no widget.

O widget pode ser incorporado na sua aplicação como um iframe na web ou como uma WebView em aplicações nativas (React Native, Flutter, etc.). Em todos os casos, o widget emite eventos via postMessage para que a sua aplicação reaja a ações do usuário, como login concluído ou certificado registrado.

Todos os eventos possuem o prefixo hme: no campo type.

Tipos de eventos

Name
hme:login:success
Description
O usuário completou o fluxo de login com sucesso. Inclui redirect_url com a URL de redirecionamento configurada no widget.
Name
hme:login:completed
Description
O login foi concluído com sucesso. Ao receber este evento, a WebView deve ser fechada e o usuário redirecionado para a próxima página.
Name
hme:login:expired
Description
A sessão de login expirou por inatividade (mais de 5 minutos sem conclusão). Ao receber este evento, a WebView deve ser fechada.
Name
hme:login:error
Description
Ocorreu um erro durante o fluxo de login, como senha incorreta, sistema indisponível, entre outros. Inclui message com a descrição do erro.
Name
hme:auth:success
Description
O usuário foi autenticado com sucesso (via token, API externa ou fingerprint). Inclui redirect_url com a URL de destino.
Name
hme:certificate:success
Description
O certificado digital foi registrado com sucesso. Inclui company e certificate com os dados do certificado.
Name
hme:certificate:error
Description
Ocorreu um erro na validação do certificado digital. Inclui message com a descrição do erro.

Payload dos eventos

Todos os eventos incluem os campos type e external_uid. Os campos adicionais variam conforme o tipo do evento.

Name
type
Type
string
Description
Tipo do evento com prefixo hme:.
Name
external_uid
Type
string
Description
Identificador único externo do usuário no seu sistema, conforme enviado na autenticação via API.
Name
redirect_url
Type
string
Description
URL de redirecionamento configurada no widget. Presente nos eventos login:success e auth:success.
Name
company
Type
object
Description
Dados da empresa associada ao certificado. Presente em certificate:success.
Name
certificate
Type
object
Description
Dados do certificado digital. Presente em certificate:success.
Name
message
Type
string
Description
Mensagem de erro. Presente em login:error e certificate:error.

Exemplo: login:completed

{
  "type": "hme:login:completed",
  "external_uid": "user_12345"
}

Exemplo: login:expired

{
  "type": "hme:login:expired",
  "external_uid": "user_12345"
}

Exemplo: login:error

{
  "type": "hme:login:error",
  "external_uid": "user_12345",
  "message": "Senha incorreta"
}

Exemplo: certificate:success

{
  "type": "hme:certificate:success",
  "external_uid": "user_12345",
  "company": {
    "id": 1,
    "name": "Empresa Exemplo Ltda",
    "tax_id": "12345678000190"
  },
  "certificate": {
    "status": "active",
    "issue_date": "2025-01-01",
    "expiration_date": "2026-01-01"
  }
}

Recebendo eventos

Abaixo estão exemplos de como receber os eventos do widget em cada plataforma.

Listener de eventos

window.addEventListener('message', (event) => {
  if (!event.data?.type?.startsWith('hme:')) return

  const { type, external_uid, redirect_url, message } = event.data

  switch (type) {
    case 'hme:login:success':
      console.log('Login concluído', external_uid, redirect_url)
      break
    case 'hme:login:completed':
      console.log('Login finalizado', external_uid)
      window.location.href = redirect_url
      break
    case 'hme:login:expired':
      console.log('Sessão expirada', external_uid)
      document.getElementById('widget-iframe').remove()
      break
    case 'hme:login:error':
      console.log('Erro no login', external_uid, message)
      break
    case 'hme:auth:success':
      console.log('Autenticação concluída', external_uid, redirect_url)
      break
    case 'hme:certificate:success':
      console.log('Certificado registrado', external_uid, event.data.company)
      break
    case 'hme:certificate:error':
      console.log('Erro no certificado', external_uid, message)
      break
  }
})

Quando o widget não está incorporado em um iframe ou WebView (acesso direto), o redirecionamento é feito normalmente via navegação do navegador para a URL configurada.