Habilitar.me

Usuários

A API de Usuários permite gerenciar os usuários (pessoa física) da organização, incluindo o cadastro no SNE.

Propriedades

  • Name
    id
    Type
    number
    Description

    ID único do usuário.

  • Name
    tax_id
    Type
    string
    Description

    CPF (11 dígitos) do usuário.

  • Name
    name
    Type
    string
    Description

    Nome do usuário.

  • Name
    email
    Type
    string
    Description

    Email do usuário.

  • Name
    phone
    Type
    string
    Description

    Telefone do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    status
    Type
    string
    Description

    Status do vínculo do usuário na organização. Valores possíveis:

    ValorDescrição
    activeAtivo na organização; dados disponíveis e webhooks enviados
    inactiveInativo; dados indisponíveis na API (endpoints relacionados retornam 403) e webhooks suprimidos para a organização
    pendingEstado inicial ao criar o vínculo; comporta-se como ativo (dados e webhooks disponíveis)
  • Name
    sne
    Type
    object
    Description

    Informações do Sistema de Notificação Eletrônica (SNE).

    • Name
      status
      Type
      string
      Description

      Status do SNE. Valores possíveis:

      ValorDescrição
      activeCadastro ativo no SNE
      inactiveCadastro inativo no SNE
      unavailableSNE não disponível
      unknownStatus desconhecido
      pendingCadastro pendente no SNE
      cancelingCancelamento em andamento
    • Name
      sign_up_date
      Type
      string
      Description

      Data de cadastro no SNE no formato "YYYY-MM-DD".

    • Name
      cancel_date
      Type
      string
      Description

      Data de cancelamento do SNE no formato "YYYY-MM-DD".

    • Name
      synced_at
      Type
      string
      Description

      Data da última sincronização com o SNE no formato ISO 8601.

  • Name
    login
    Type
    object
    Description

    Login associado ao usuário.

    • Name
      id
      Type
      number
      Description

      ID do login.

    • Name
      type
      Type
      string
      Description

      Tipo de credencial do login. Valores possíveis:

      ValorDescrição
      certificateCertificado digital
      passwordUsuário e senha (gov.br)
    • Name
      status
      Type
      string
      Description

      Status do login. Valores possíveis:

      ValorDescrição
      failFalha no login
      successLogin bem-sucedido
      incompleteLogin incompleto
      processingProcessando
      voidedAnulado
    • Name
      service
      Type
      string
      Description

      Serviço externo associado ao login.

      ValorDescrição
      govbrgov.br
    • Name
      connected
      Type
      boolean
      Description

      Indica se a sessão de login está atualmente ativa.

    • Name
      connected_at
      Type
      string
      Description

      Data e hora da última conexão bem-sucedida (ISO 8601).

    • Name
      disconnected_at
      Type
      string
      Description

      Data e hora da última desconexão (ISO 8601).

    • Name
      step
      Type
      string
      Description

      Etapa atual do processo de conexão. Em caso de falha, permanece com o valor da etapa em que o erro ocorreu.

      ValorDescrição
      credentialsAguardando credenciais
      usernameValidando usuário
      passwordValidando senha
      certificateValidando certificado
      otpAguardando OTP
      completedConexão concluída
  • Name
    created_at
    Type
    string
    Description

    Data de criação do usuário no formato ISO 8601.

  • Name
    updated_at
    Type
    string
    Description

    Data da última atualização do usuário no formato ISO 8601.

GET/v1/users

Listar Usuários

Retorna uma lista paginada de todos os usuários da organização.

Parâmetros de Paginação

  • Name
    pagination[page]
    Type
    integer
    Description

    Número da página (começando em 1). Use junto com pagination[size].

  • Name
    pagination[size]
    Type
    integer
    Description

    Tamanho da página (número de itens por página, máximo 100). Use junto com pagination[page].

Parâmetros de Filtro

  • Name
    filters[name]
    Type
    object
    Description

    Filtra por nome do usuário.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $contains
      Type
      string
      Description

      Contém o valor especificado.

    • Name
      $startsWith
      Type
      string
      Description

      Começa com o valor especificado.

  • Name
    filters[tax_id]
    Type
    object
    Description

    Filtra por CPF do usuário.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $contains
      Type
      string
      Description

      Contém o valor especificado.

  • Name
    filters[email]
    Type
    object
    Description

    Filtra por email do usuário.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $contains
      Type
      string
      Description

      Contém o valor especificado.

  • Name
    filters[sne][status]
    Type
    object
    Description

    Filtra por status do SNE.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado (active, inactive, unavailable, unknown, pending, canceling).

  • Name
    filters[status]
    Type
    object
    Description

    Filtra por status do vínculo do usuário na organização.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado (active, inactive, pending).

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[external_uid]
    Type
    object
    Description

    Filtra por identificador externo do usuário.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[login][status]
    Type
    object
    Description

    Filtra por status do login do usuário.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado (incomplete, processing, success, fail, voided).

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[login][step]
    Type
    object
    Description

    Filtra pela etapa atual do login do usuário (ex.: credentials, username, password, certificate, otp, completed).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[login][connected]
    Type
    object
    Description

    Filtra pelo estado da sessão do login do usuário.

    • Name
      $eq
      Type
      boolean
      Description

      Igual ao valor especificado (true ou false).

  • Name
    filters[login][connected_at]
    Type
    object
    Description

    Filtra pela data da última conexão do login (ISO 8601).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

    • Name
      $gt
      Type
      string
      Description

      Posterior ao valor especificado.

    • Name
      $gte
      Type
      string
      Description

      Maior ou igual ao valor especificado.

    • Name
      $lt
      Type
      string
      Description

      Anterior ao valor especificado.

    • Name
      $lte
      Type
      string
      Description

      Menor ou igual ao valor especificado.

  • Name
    filters[login][disconnected_at]
    Type
    object
    Description

    Filtra pela data da última desconexão do login (ISO 8601).

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

    • Name
      $gt
      Type
      string
      Description

      Posterior ao valor especificado.

    • Name
      $gte
      Type
      string
      Description

      Maior ou igual ao valor especificado.

    • Name
      $lt
      Type
      string
      Description

      Anterior ao valor especificado.

    • Name
      $lte
      Type
      string
      Description

      Menor ou igual ao valor especificado.

Request

GET
/v1/users
curl -G https://api.habilitar.me/v1/users \
  -H "x-api-key: {api_key}" \
  -d "pagination[page]=1" \
  -d "pagination[size]=10"

Response

{
  "data": [
    {
      "id": 1,
      "tax_id": "12345678901",
      "name": "João da Silva",
      "email": "joao@example.com",
      "phone": "+5511999999999",
      "external_uid": "EXT_USR_12345",
      "status": "active",
      "sne": {
        "status": "active",
        "sign_up_date": "2024-01-15",
        "cancel_date": null,
        "synced_at": "2024-01-20T10:30:00.000Z"
      },
      "login": {
        "id": 1,
        "type": "password",
        "status": "success",
        "service": "govbr",
        "connected": true,
        "connected_at": "2026-05-07T12:34:56.000Z",
        "disconnected_at": null,
        "step": "completed"
      },
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-20T14:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 1
  },
  "total": 1
}
GET/v1/users/:id

Detalhar Usuário

Retorna os detalhes de um usuário específico por ID.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

GET
/v1/users/:id
curl https://api.habilitar.me/v1/users/1 \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "id": 1,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "external_uid": "EXT_USR_12345",
    "status": "active",
    "sne": {
      "status": "active",
      "sign_up_date": "2024-01-15",
      "cancel_date": null,
      "synced_at": "2024-01-20T10:30:00.000Z"
    },
    "login": {
      "id": 1,
      "type": "password",
      "status": "success",
      "service": "govbr",
      "connected": true,
      "connected_at": "2026-05-07T12:34:56.000Z",
      "disconnected_at": null,
      "step": "completed"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 123 not found"
}
GET/v1/users/:id/drivers-license

Detalhar CNH do Usuário

Retorna os detalhes completos da CNH vigente do usuário. A resposta utiliza o mesmo formato do detalhamento em CNHs.

Se o usuário estiver com status igual a inactive, este endpoint retorna 403 Forbidden. Consulte GET /v1/users/:id para confirmar o status do usuário. 404 indica CNH inexistente para um usuário ativo.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

GET
/v1/users/:id/drivers-license
curl https://api.habilitar.me/v1/users/1/drivers-license \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "id": 1,
    "license": "12345678901",
    "name": "JOÃO DA SILVA",
    "tax_id": "12345678900",
    "points": {
      "value": 0,
      "limit": 40,
      "synced_at": "2026-05-29T07:12:07.324Z"
    },
    "status": "active",
    "class": "b",
    "current": true,
    "renach": "1234567890",
    "commercial_driver": true,
    "probationary_license": false,
    "current_license_state": "SC",
    "domain_license_state": "SC",
    "issuer_license_state": "SP",
    "issue_date": "2024-09-24",
    "expiration_date": "2027-09-18",
    "first_license_date": "2019-11-21",
    "files": {
      "photo": "data:image/jpeg;base64,<base64-payload>",
      "front": "data:image/jpeg;base64,<base64-payload>",
      "back": "data:image/jpeg;base64,<base64-payload>",
      "qr_code": "data:image/jpeg;base64,<base64-payload>"
    },
    "user": {
      "id": 1,
      "external_uid": "EXT_USR_12345"
    },
    "created_at": "2026-05-28T15:10:51.038Z"
  }
}

Response - 403

{
  "error": "Forbidden",
  "message": "User is inactive for this organization"
}

Response - 404

{
  "error": "Not Found",
  "message": "Driver license for user with id 123 not found"
}
POST/v1/users

Criar Usuário

Cria um novo usuário (pessoa física) na organização.

Corpo da Requisição

  • Name
    name
    Type
    string
    Required
    obrigatório
    Description

    Nome do usuário.

  • Name
    tax_id
    Type
    string
    Required
    obrigatório
    Description

    CPF do usuário (11 dígitos, com validação de checksum).

  • Name
    email
    Type
    string
    Description

    Email do usuário.

  • Name
    phone
    Type
    string
    Description

    Telefone do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

Request

POST
/v1/users
curl -X POST https://api.habilitar.me/v1/users \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "name": "João da Silva",
    "tax_id": "12345678901",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "external_uid": "EXT_USR_12345"
  }'

Response - 201

{
  "data": {
    "id": 1,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "email": "joao@example.com",
    "phone": "+5511999999999",
    "external_uid": "EXT_USR_12345",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Response - 400

{
  "error": "Bad Request",
  "message": "tax_id must be a valid Brazilian CPF"
}

Response - 409

{
  "error": "Conflict",
  "message": "A user with this tax_id already exists"
}
PUT/v1/users/:id

Atualizar Usuário

Atualiza os dados de um usuário específico.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Corpo da Requisição

  • Name
    name
    Type
    string
    Description

    Nome do usuário.

  • Name
    email
    Type
    string
    Description

    Email do usuário.

  • Name
    phone
    Type
    string
    Description

    Telefone do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

Request

PUT
/v1/users/:id
curl -X PUT https://api.habilitar.me/v1/users/1 \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "name": "João da Silva Júnior",
    "email": "novo@example.com"
  }'

Response - 200

{
  "data": {
    "id": 1,
    "tax_id": "12345678901",
    "name": "João da Silva Júnior",
    "email": "novo@example.com",
    "phone": "+5511999999999",
    "external_uid": "EXT_USR_12345",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Response - 400

{
  "error": "Bad Request",
  "message": "At least one field must be provided for update"
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 123 not found"
}
DELETE/v1/users/:id

Remover Usuário

Remove um usuário da organização e seus dados relacionados.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

DELETE
/v1/users/:id
curl -X DELETE https://api.habilitar.me/v1/users/1 \
  -H "x-api-key: {api_key}"

Response - 200

{
  "message": "User with id 1 successfully deleted"
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 1 not found"
}
POST/v1/users/:id/sne

Cadastrar no SNE

Inicia o processo de cadastro do usuário no Sistema de Notificação Eletrônica (SNE).

Fluxo Assíncrono: Esta requisição inicia o processo de cadastro. O status será atualizado conforme o processamento.

Regras

  • O usuário não pode estar com sne.status igual a "active" ou "pending"
  • O usuário deve possuir um login com login.status igual a "success"

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

POST
/v1/users/:id/sne
curl -X POST https://api.habilitar.me/v1/users/1/sne \
  -H "x-api-key: {api_key}"

Response - 201

{
  "data": {
    "status": "pending",
    "sign_up_date": "2024-01-15"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 123 not found"
}

Response - 409

{
  "error": "Conflict",
  "message": "User is already registered or has a pending registration in SNE"
}

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "User must have a login with status 'success' to sign up for SNE"
}
DELETE/v1/users/:id/sne

Cancelar SNE

Inicia o processo de cancelamento do cadastro do usuário no Sistema de Notificação Eletrônica (SNE).

Fluxo Assíncrono: Esta requisição inicia o processo de cancelamento. O status será atualizado conforme o processamento.

Regras

  • O usuário deve estar com sne.status igual a "active" para poder cancelar
  • O usuário deve possuir um login com login.status igual a "success"

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

DELETE
/v1/users/:id/sne
curl -X DELETE https://api.habilitar.me/v1/users/1/sne \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "status": "canceling",
    "cancel_date": "2024-06-15"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 123 not found"
}

Response - 422 - SNE não ativo

{
  "error": "Unprocessable Entity",
  "message": "User must have active SNE status to cancel"
}

Response - 422 - Login inválido

{
  "error": "Unprocessable Entity",
  "message": "User must have a login with status 'success' to cancel SNE"
}
POST/v1/users/:id/activate

Ativar Usuário

Ativa o vínculo do usuário na organização. Quando ativo, a organização passa a receber webhooks do usuário e tem acesso aos seus dados (CNH, veículos, infrações, etc.).

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

POST
/v1/users/:id/activate
curl -X POST https://api.habilitar.me/v1/users/1/activate \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "status": "active"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 123 not found"
}
POST/v1/users/:id/deactivate

Desativar Usuário

Desativa o vínculo do usuário na organização.

Enquanto inativo, a organização deixa de receber webhooks do usuário e os dados dele (CNH, veículos, infrações, etc.) ficam indisponíveis na API.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único do usuário.

Request

POST
/v1/users/:id/deactivate
curl -X POST https://api.habilitar.me/v1/users/1/deactivate \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "status": "inactive"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "User with id 123 not found"
}

Eventos de conexão

user.login.connected

O login do usuário foi conectado com sucesso: transição de desconectado para conectado.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre true neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que o login ficou. Em uma conexão bem-sucedida é completed. Os valores possíveis estão em Propriedades.

  • Name
    connected_at
    Type
    string
    Description

    Data e hora da conexão que gerou o evento (ISO 8601).

  • Name
    disconnected_at
    Type
    string
    Description

    Data e hora da desconexão anterior (ISO 8601), ou null se esta é a primeira conexão do login.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora do evento (ISO 8601).

user.login.connected

{
  "type": "user.login.connected",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": true,
    "step": "completed",
    "connected_at": "2026-05-07T12:34:56.000Z",
    "disconnected_at": null,
    "occurred_at": "2026-05-07T12:34:56.000Z"
  }
}

user.login.disconnected

O login do usuário foi desconectado: transição de conectado para desconectado, por exemplo após uma falha de autenticação ou expiração de sessão.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que o login estava no momento da desconexão. Os valores possíveis estão em Propriedades.

  • Name
    connected_at
    Type
    string
    Description

    Data e hora da última conexão bem-sucedida, anterior a esta desconexão (ISO 8601).

  • Name
    disconnected_at
    Type
    string
    Description

    Data e hora da desconexão que gerou o evento (ISO 8601).

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora do evento (ISO 8601).

user.login.disconnected

{
  "type": "user.login.disconnected",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "connected_at": "2026-05-01T08:12:00.000Z",
    "disconnected_at": "2026-05-07T12:34:56.000Z",
    "occurred_at": "2026-05-07T12:34:56.000Z"
  }
}

user.login.started

A tentativa de conexão começou. É sempre o primeiro evento da tentativa, e ainda não há etapa definida.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Sempre null neste evento: a tentativa ainda não entrou em nenhuma etapa.

  • Name
    attempt
    Type
    number
    Description

    Sempre 1 neste evento.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que a tentativa começou (ISO 8601). É o marco zero para medir a duração da tentativa.

user.login.started

{
  "type": "user.login.started",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": null,
    "attempt": 1,
    "occurred_at": "2026-08-07T13:00:00.000Z"
  }
}

user.login.step.updated

A tentativa mudou de etapa, ou repetiu a mesma etapa em uma nova tentativa — o caso de uma senha ou um código de acesso recusado. É o único evento que pode ocorrer várias vezes na mesma tentativa.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento: a tentativa está em andamento.

  • Name
    step
    Type
    string
    Description

    Etapa em que a tentativa acabou de entrar. Os valores possíveis estão em Propriedades.

  • Name
    attempt
    Type
    number
    Description

    Tentativa dentro desta etapa, começando em 1. Um valor maior que 1 significa que a etapa foi repetida — senha ou código de acesso recusado. Em password vai até 3 e em otp até 5; nas demais etapas é sempre 1.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora da mudança de etapa (ISO 8601).

user.login.step.updated

{
  "type": "user.login.step.updated",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "attempt": 1,
    "occurred_at": "2026-08-07T13:00:42.000Z"
  }
}

user.login.succeeded

A conta foi conectada com sucesso. É um dos quatro desfechos possíveis, e encerra a tentativa.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre true neste evento. É o único dos seis em que este campo é true.

  • Name
    step
    Type
    string
    Description

    Sempre completed neste evento.

  • Name
    attempt
    Type
    number
    Description

    Tentativa da última etapa, aquela que foi aceita.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que a conta foi conectada (ISO 8601).

user.login.succeeded

{
  "type": "user.login.succeeded",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": true,
    "step": "completed",
    "attempt": 1,
    "occurred_at": "2026-08-07T13:01:04.000Z"
  }
}

user.login.failed

A tentativa falhou, por recusa do gov.br ou por erro técnico. É o único dos seis eventos que traz o campo error.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que a falha ocorreu. Os valores possíveis estão em Propriedades.

  • Name
    attempt
    Type
    number
    Description

    Tentativa em curso na etapa quando a falha ocorreu. Uma senha recusada três vezes falha com attempt igual a 3.

  • Name
    error
    Type
    string
    Description

    Descrição da falha, no mesmo texto exibido ao usuário na tela de login. Presente somente neste evento.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora da falha (ISO 8601).

user.login.failed

{
  "type": "user.login.failed",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "attempt": 5,
    "error": "Não foi possível validar o código de acesso.",
    "occurred_at": "2026-08-07T13:01:36.000Z"
  }
}

user.login.abandoned

O usuário fechou a página antes de concluir a conexão. Diferente de user.login.expired, aqui houve uma ação explícita de sair.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que o usuário estava quando fechou a página. É o campo que diz onde o funil perde gente. Os valores possíveis estão em Propriedades.

  • Name
    attempt
    Type
    number
    Description

    Tentativa em curso na etapa quando a página foi fechada.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que o abandono foi detectado (ISO 8601).

user.login.abandoned

{
  "type": "user.login.abandoned",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "password",
    "attempt": 2,
    "occurred_at": "2026-08-07T13:00:58.000Z"
  }
}

user.login.expired

A página permaneceu aberta, mas o tempo para informar a senha ou o código de acesso expirou. Diferente de user.login.abandoned, aqui o usuário não fechou nada — apenas não respondeu em tempo.

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa cujo tempo de espera expirou, password ou otp — as duas etapas que aguardam algo do usuário.

  • Name
    attempt
    Type
    number
    Description

    Tentativa em curso na etapa quando o tempo expirou.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que o tempo de espera expirou (ISO 8601).

user.login.expired

{
  "type": "user.login.expired",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "attempt": 3,
    "occurred_at": "2026-08-07T13:05:12.000Z"
  }
}

Essa página foi útil?