Usergroups API Endpoints

User Group Management

The Usergroups API provides endpoints for managing user groups in your system. These endpoints allow you to create, retrieve, update, and delete user groups, as well as manage user memberships within groups.

Base URL: https://www.venddor.com.br/api

Important: Usergroup IDs 1 and 2 are reserved for Guests and Registered users respectively. These groups don't show up in regular listings unless you refer to them directly. You cannot delete or modify these reserved groups.

GET POST /usergroups

Access all user groups or create a new user group.

Supported Methods

Method	Description
GET	Retrieve all user groups
POST	Create a new user group

GET Response Example

POST Request Example

{
  "data": [
    {
      "id": 3,
      "name": "Administrators",
      "description": "Users with full system access",
      "member_count": 5,
      "permissions": [
        "manage_users",
        "manage_products",
        "manage_orders",
        "manage_settings"
      ],
      "created_at": "2024-12-01T10:00:00Z"
    },
    {
      "id": 4,
      "name": "Sales Team",
      "description": "Sales department staff",
      "member_count": 12,
      "permissions": [
        "view_customers",
        "manage_orders",
        "view_products"
      ],
      "created_at": "2024-12-15T14:30:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "per_page": 10
  }
}

{
  "name": "Support Team",
  "description": "Customer support representatives",
  "permissions": [
    "view_customers",
    "view_orders",
    "manage_tickets",
    "respond_tickets"
  ],
  "users": [
    "user_003",
    "user_007",
    "user_012"
  ]
}

GET PUT DELETE /usergroups/:id

Access, update, or delete a specific user group by its ID.

Path Parameters

Parameter	Type	Description
id*	integer	The unique identifier of the user group

Supported Methods

Method	Description
GET	Retrieve a specific user group
PUT	Update a specific user group
DELETE	Delete a specific user group

Example PUT Request

{
  "name": "Sales and Marketing Team",
  "description": "Combined sales and marketing department",
  "permissions": [
    "view_customers",
    "manage_orders",
    "view_products",
    "manage_marketing"
  ]
}

GET /users/:id/usergroups

Retrieve all user groups that a specific user belongs to.

Path Parameters

Parameter	Type	Description
id*	string	The unique identifier of the user

Supported Methods

Method	Description
GET	Retrieve all groups that the user belongs to

Example Response

{
  "data": [
    {
      "id": 2,
      "name": "Registered users",
      "description": "Default group for all registered users",
      "permissions": [
        "view_products",
        "place_orders"
      ]
    },
    {
      "id": 4,
      "name": "Sales Team",
      "description": "Sales department staff",
      "permissions": [
        "view_customers",
        "manage_orders",
        "view_products"
      ]
    }
  ]
}

PUT DELETE /users/:user_id/usergroups/:group_id

Add a user to a group or remove a user from a group.

Path Parameters

Parameter	Type	Description
user_id*	string	The unique identifier of the user
group_id*	integer	The unique identifier of the user group

Supported Methods

Method	Description
PUT	Add user to the specified group
DELETE	Remove user from the specified group

Note: When adding a user to a group (PUT), the request body is not required. The operation is performed based on the URL path parameters alone.

Response Status Codes

Status Code	Description
`200 OK`	Operation completed successfully
`400 Bad Request`	Invalid request parameters
`403 Forbidden`	Insufficient permissions to perform the operation
`404 Not Found`	User or user group with the specified ID does not exist
`409 Conflict`	User is already a member of the group (PUT) or user is not a member of the group (DELETE)

Tip: To efficiently manage multiple user group memberships, consider using the batch operations endpoint instead of making multiple individual requests.