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
    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[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",
      "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",
    "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.

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 - 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"
}

Eventos de Webhook

Os eventos user.login.* notificam alterações no login (conta gov.br) do usuário. O payload é centrado no usuário e inclui o estado atual do login no campo login.

Quando o usuário pertence a múltiplas organizações, o evento é entregue uma vez por organização (uma requisição por tenant).

  • Name
    user.login.updated
    Description

    O login do usuário foi atualizado.

  • Name
    user.login.connected
    Description

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

  • Name
    user.login.disconnected
    Description

    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).

Propriedades do payload

  • Name
    id
    Type
    number
    Description

    ID do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo do usuário.

  • Name
    login
    Type
    object
    Description

    Estado atual do login. Contém id, type, status, service, connected, connected_at, disconnected_at e step.

  • Name
    created_at
    Type
    string
    Description

    Data de criação do usuário (ISO 8601).

  • Name
    updated_at
    Type
    string
    Description

    Data da última atualização do usuário (ISO 8601).

user.login.connected

{
  "type": "user.login.connected",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "login": {
      "id": 7,
      "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-01T00:00:00.000Z",
    "updated_at": "2026-05-07T12:34:56.000Z"
  }
}

user.login.disconnected

{
  "type": "user.login.disconnected",
  "data": {
    "id": 42,
    "external_uid": "EXT_USER_42",
    "login": {
      "id": 7,
      "type": "password",
      "status": "incomplete",
      "service": "govbr",
      "connected": false,
      "connected_at": "2026-05-01T08:12:00.000Z",
      "disconnected_at": "2026-05-07T12:34:56.000Z",
      "step": "otp"
    },
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2026-05-07T12:34:56.000Z"
  }
}

Essa página foi útil?