Habilitar.me

Usuários

A API de Usuários permite gerenciar os usuários do console. Através desta API você pode listar, autenticar e gerenciar os usuários da sua organização.

GET/v1/console/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[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[external_uid]
    Type
    object
    Description

    Filtra por identificador externo do usuário.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

Request

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

Response

{
  "data": [
    {
      "id": "1",
      "name": "João Silva",
      "email": "joao.silva@exemplo.com",
      "external_uid": "user_12345",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "2",
      "name": "Maria Santos",
      "email": "maria.santos@exemplo.com",
      "external_uid": "user_67890",
      "created_at": "2024-01-16T14:20:00Z",
      "updated_at": "2024-01-16T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10
  },
  "total": 2
}
GET/v1/console/users/{id}

Detalhar Usuário

Retorna as informações de um usuário específico pelo ID.

Parâmetros de Rota

  • Name
    id
    Type
    string
    Required
    obrigatório
    Description

    ID único do usuário do console.

Request

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

Response

{
  "id": "1",
  "name": "João Silva",
  "email": "joao.silva@exemplo.com",
  "external_uid": "user_12345",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Response - 404

{
  "error": "Not Found",
  "message": "Console user with id 1 not found"
}
GET/v1/console/users/{id}/companies

Listar Empresas do Usuário

Retorna a lista paginada de empresas vinculadas ao usuário.

Parâmetros de Rota

  • Name
    id
    Type
    string
    Required
    obrigatório
    Description

    ID único do usuário do console.

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

Request

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

Response

{
  "data": [
    {
      "id": "comp_abc123",
      "name": "Empresa ABC Ltda",
      "tax_id": "12345678000199",
      "external_uid": "ABC123",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10
  },
  "total": 1
}

Response - 404

{
  "error": "Not Found",
  "message": "Console user with id 1 not found"
}
POST/v1/console/users/sign-in

Autenticar Usuário

Este endpoint recebe as informações do usuário e retorna um token de acesso e uma URL de redirecionamento.

Se o usuário já existir (baseado no email), o sistema gera um novo token de acesso. Se o usuário não existir, o sistema cria o usuário automaticamente e retorna o token de acesso.

As empresas informadas devem existir na organização e serão agrupadas em um company group. O console-user é vinculado à organização da chave de API e ao company group.

Corpo da Requisição

  • Name
    name
    Type
    string
    Description

    Nome completo do usuário.

  • Name
    email
    Type
    string
    Required
    obrigatório
    Description

    Endereço de email do usuário.

  • Name
    external_uid
    Type
    string
    Description

    Identificador único externo do usuário. Este valor é utilizado para identificar o usuário no seu sistema.

  • Name
    companies
    Type
    array
    Required
    obrigatório
    Description

    Lista de empresas associadas ao usuário.

    • Name
      tax_id
      Type
      string
      Required
      obrigatório
      Description

      CNPJ da empresa.

    • Name
      external_uid
      Type
      string
      Description

      Identificador único externo da empresa.

Request

POST
/v1/console/users/sign-in
curl -X POST https://api.habilitar.me/v1/console/users/sign-in \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "external_uid": "12345",
    "companies": [
      {
        "tax_id": "12345678000199",
        "external_uid": "ABC123"
      }
    ]
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "redirect_url": "https://console.habilitar.me/auth/callback?token=..."
}

Response - 400

{
  "error": "Bad Request",
  "message": "email must be a valid email address"
}
DELETE/v1/console/users/{id}/companies

Remover Empresas do Usuário

Remove o vínculo do usuário com as empresas informadas.

Parâmetros de Rota

  • Name
    id
    Type
    string
    Required
    obrigatório
    Description

    ID único do usuário do console.

Corpo da Requisição

  • Name
    companies
    Type
    string[]
    Required
    obrigatório
    Description

    Lista de CNPJs das empresas cujo acesso será removido.

Request

DELETE
/v1/console/users/{id}/companies
curl -X DELETE https://api.habilitar.me/v1/console/users/1/companies \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "companies": ["12345678000199", "98765432000188"]
  }'

Response

{
  "message": "Companies successfully removed from console user with id 1"
}

Response - 400

{
  "error": "Bad Request",
  "message": "companies must be a non-empty array"
}

Response - 404

{
  "error": "Not Found",
  "message": "Console user with id 1 not found"
}
DELETE/v1/console/users/{id}

Remover Usuário

Remove um usuário do console.

Parâmetros de Rota

  • Name
    id
    Type
    string
    Required
    obrigatório
    Description

    ID único do usuário do console.

Request

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

Response

{
  "message": "Console user with id 1 successfully deleted"
}

Response - 404

{
  "error": "Not Found",
  "message": "Console user with id 1 not found"
}

Eventos de Webhook

  • Name
    console-user.created
    Description

    Um novo usuário do console foi criado.

  • Name
    console-user.updated
    Description

    Um usuário do console foi atualizado.

Exemplo de payload

{
  "type": "console-user.created",
  "data": {
    "id": "1",
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "external_uid": "user_12345",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Essa página foi útil?