Recipient group

[!info] Overview The RecipientGroup REST API manages recipient groups (supplier groups) in the pkbillms billing system. Recipient groups organize payment recipients into logical collections for easier management and categorization.

📋 Table of Contents

Quick Reference

[!abstract] API Configuration
Base URL: /api
Entity Name: pkbillmsRecipientGroup
Controller: RecipientGroupResource
Framework: Spring Boot + JHipster
Auth: Required (Spring Security)
Content-Type: application/json

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/recipient-groups

Create new recipient group

201

PUT

/api/recipient-groups/{id}

Full update

200

PATCH

/api/recipient-groups/{id}

Partial update

200

GET

/api/recipient-groups

Get all with criteria

200

GET

/api/recipient-groups/{id}

Get by ID

200

GET

/api/recipient-groups/count

Count by criteria

200

DELETE

/api/recipient-groups/{id}

Delete recipient group

204

Data Models

RecipientGroup DTO Structure

[!note] Data Transfer Object Represents a group of payment recipients with organizational metadata.

@ApiModel(description = "Группа поставщиков")
public class RecipientGroupDTO implements Serializable {
    private Long id;
    private String name;              // Group name (max 64)
    private Boolean active;           // Active status
    private String more;              // Additional information
    private Set<RecipientDTO> recipients;  // Associated recipients
}

Field Specifications

Field

Type

Required

Max/Range

DB Column

Description

id

Long

❌ Auto

Primary key

name

String

✅

name

Group name

active

Boolean

✅

active

Active/Inactive status

more

String

❌

Additional information

recipients

Set

✅

rel_table

Associated recipients

Audit Fields (Inherited)

[!success] Auto-managed These fields are automatically populated by the system.

Field

Type

Description

createdBy

String

Creator username

createdDate

Instant

Creation timestamp

lastModifiedBy

String

Last modifier

lastModifiedDate

Instant

Last modification

API Endpoints

Create RecipientGroup

POST /api/recipient-groups
Creates a new recipient group entity.

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "name": "Mobile Operators",
  "active": true,
  "more": "Group containing all mobile network operators in Uzbekistan",
  "recipients": [
    {
      "id": 1
    },
    {
      "id": 2
    },
    {
      "id": 3
    }
  ]
}

[!warning] Validation Rules
id must be null (auto-generated)
name is required (max 64 characters)
active is required
recipients is required (must contain at least one recipient)
Recipients must exist in the database

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/recipient-groups/1

{
  "id": 1,
  "name": "Mobile Operators",
  "active": true,
  "more": "Group containing all mobile network operators in Uzbekistan",
  "recipients": [
    {
      "id": 1,
      "name": "Beeline",
      "active": true
    },
    {
      "id": 2,
      "name": "Ucell",
      "active": true
    },
    {
      "id": 3,
      "name": "UMS",
      "active": true
    }
  ]
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "detail": "A new recipientGroup cannot already have an ID",
  "message": "error.idexists"
}

Update RecipientGroup

PUT /api/recipient-groups/{id}
Completely updates an existing recipient group.

Path Parameters

id (Long) - RecipientGroup identifier

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "name": "Mobile Network Providers",
  "active": true,
  "more": "Updated group description for all mobile operators",
  "recipients": [
    {
      "id": 1
    },
    {
      "id": 2
    },
    {
      "id": 3
    },
    {
      "id": 4
    }
  ]
}

[!warning] Validation
Body id must not be null
Path id must match body id
RecipientGroup must exist in database
All recipients must exist in database

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Mobile Network Providers",
  "active": true,
  "more": "Updated group description for all mobile operators",
  "recipients": [
    {
      "id": 1,
      "name": "Beeline"
    },
    {
      "id": 2,
      "name": "Ucell"
    },
    {
      "id": 3,
      "name": "UMS"
    },
    {
      "id": 4,
      "name": "Mobiuz"
    }
  ]
}

❌ Errors:

Status

Detail

Message

400

Invalid id

error.idnull

400

Invalid ID

error.idinvalid

400

Entity not found

error.idnotfound

Partial Update

PATCH /api/recipient-groups/{id}
Updates only specified fields. Null fields are ignored.

Path Parameters

id (Long) - RecipientGroup identifier

Request

Headers:

Content-Type: application/merge-patch+json
Authorization: Bearer {token}

Body (Example - deactivate group):

{
  "id": 1,
  "active": false
}

Body (Example - update name and additional info):

{
  "id": 1,
  "name": "Telecom Providers",
  "more": "Includes mobile and internet service providers"
}

[!tip] Partial Update Behavior
Only non-null fields are updated
Other fields remain unchanged
Perfect for status toggles or single field updates
Recipients can be updated without changing other fields

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Telecom Providers",
  "active": true,
  "more": "Includes mobile and internet service providers",
  "recipients": [...]
}

Get All RecipientGroups

GET /api/recipient-groups
Retrieves paginated list with filtering criteria.

Query Parameters

Pagination:

page - Page number (0-indexed, default: 0)
size - Items per page (default: 20)
sort - Sort criteria (e.g., name,asc)
unPaged - Boolean for unpaged results

Filters (RecipientGroupCriteria):

id.equals, id.in
name.contains, name.equals
active.equals - Filter by status
recipientId.equals, recipientId.in - Filter by recipient

Example Requests

GET /api/recipient-groups?page=0&size=10&sort=name,asc
GET /api/recipient-groups?active.equals=true
GET /api/recipient-groups?name.contains=Mobile
GET /api/recipient-groups?recipientId.equals=5

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 25
Link: </api/recipient-groups?page=0&size=20>; rel="first",
      </api/recipient-groups?page=1&size=20>; rel="next"

[
  {
    "id": 1,
    "name": "Mobile Operators",
    "active": true,
    "more": "All mobile network operators",
    "recipients": [
      {
        "id": 1,
        "name": "Beeline"
      },
      {
        "id": 2,
        "name": "Ucell"
      }
    ]
  },
  {
    "id": 2,
    "name": "Utility Providers",
    "active": true,
    "more": "Electricity, gas, and water providers",
    "recipients": [
      {
        "id": 10,
        "name": "Tashkent Electric"
      },
      {
        "id": 11,
        "name": "Uzbek Gas"
      }
    ]
  }
]

Get Single RecipientGroup

GET /api/recipient-groups/{id}
Retrieves a single recipient group by ID with all relationships.

Path Parameters

id (Long) - RecipientGroup identifier

Request

GET /api/recipient-groups/1
Authorization: Bearer {token}

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Mobile Operators",
  "active": true,
  "more": "Group containing all mobile network operators in Uzbekistan",
  "recipients": [
    {
      "id": 1,
      "name": "Beeline",
      "active": true,
      "gateway": {
        "id": 1,
        "name": "Beeline Gateway"
      },
      "category": {
        "id": 5,
        "name": "Mobile Services"
      }
    },
    {
      "id": 2,
      "name": "Ucell",
      "active": true,
      "gateway": {
        "id": 2,
        "name": "Ucell Gateway"
      },
      "category": {
        "id": 5,
        "name": "Mobile Services"
      }
    }
  ]
}

❌ Error (404 Not Found):

{
  "status": 404,
  "detail": "RecipientGroup not found with id: 999"
}

Count RecipientGroups

GET /api/recipient-groups/count
Returns count of recipient groups matching criteria.

Query Parameters

Same filtering parameters as [[#Get All RecipientGroups]]

Example Requests

GET /api/recipient-groups/count
GET /api/recipient-groups/count?active.equals=true
GET /api/recipient-groups/count?name.contains=Telecom

Response

✅ Success (200 OK):

Delete RecipientGroup

DELETE /api/recipient-groups/{id}
Deletes a recipient group from the database.

Path Parameters

id (Long) - RecipientGroup identifier

Request

DELETE /api/recipient-groups/1
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

[!warning] Delete Behavior
Removes the recipient group entity
Removes many-to-many relationships with recipients
Does not delete the recipients themselves
Recipients remain available for other groups

Examples

Example 1: Create Group for Utility Providers

Setup Utility Providers Group Request:

curl -X POST http://localhost:8080/api/recipient-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Utility Providers",
    "active": true,
    "more": "Electricity, water, and gas service providers",
    "recipients": [
      {"id": 10},
      {"id": 11},
      {"id": 12}
    ]
  }'

Example 2: Update Group with New Recipients

Add Recipients to Existing Group Request:

curl -X PUT http://localhost:8080/api/recipient-groups/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "name": "Mobile Operators",
    "active": true,
    "more": "All mobile operators including new entrants",
    "recipients": [
      {"id": 1},
      {"id": 2},
      {"id": 3},
      {"id": 4},
      {"id": 5}
    ]
  }'

Example 3: Deactivate Group

Temporarily Deactivate Group Request:

curl -X PATCH http://localhost:8080/api/recipient-groups/2 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 2,
    "active": false
  }'

Response:

{
  "id": 2,
  "name": "Utility Providers",
  "active": false,
  "more": "Electricity, water, and gas service providers",
  "recipients": [...]
}

Example 4: Get Active Groups Only

Filter Active Groups Request:

curl -X GET "http://localhost:8080/api/recipient-groups?active.equals=true&sort=name,asc" \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": 1,
    "name": "Mobile Operators",
    "active": true,
    "recipients": [...]
  },
  {
    "id": 3,
    "name": "Transportation Services",
    "active": true,
    "recipients": [...]
  }
]

Example 5: Search Groups by Name

Find Groups Containing "Mobile" Request:

curl -X GET "http://localhost:8080/api/recipient-groups?name.contains=Mobile" \
  -H "Authorization: Bearer TOKEN"

Error Handling

Error Response Format

[!failure] RFC 7807 Problem Details All errors follow standardized format.

{
  "type": "https://www.jhipster.tech/problem/{error-type}",
  "title": "Error Title",
  "status": 400,
  "detail": "Detailed error message",
  "path": "/api/recipient-groups",
  "message": "error.code",
  "params": "additionalInfo"
}

HTTP Status Codes

Code

Type

Description

Common Causes

400

Bad Request

Invalid request

Validation failure, ID mismatch, null required fields

401

Unauthorized

Auth required

Missing/invalid token

403

Forbidden

Access denied

Insufficient permissions

404

Not Found

Resource missing

Invalid ID, deleted entity

409

Conflict

Resource conflict

Duplicate name (if enforced)

500

Server Error

Internal error

Database error, exception

Validation Error Example

[!bug] Field Validation Errors

{
  "type": "https://www.jhipster.tech/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "path": "/api/recipient-groups",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "recipientGroupDTO",
      "field": "name",
      "message": "must not be null"
    },
    {
      "objectName": "recipientGroupDTO",
      "field": "name",
      "message": "size must be between 0 and 64"
    },
    {
      "objectName": "recipientGroupDTO",
      "field": "active",
      "message": "must not be null"
    },
    {
      "objectName": "recipientGroupDTO",
      "field": "recipients",
      "message": "must not be null"
    }
  ]
}

Validation Rules

Required Fields

[!check] Mandatory Fields
✅ name - Group name
✅ active - Active status
✅ recipients - At least one recipient

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new recipientGroup cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

name

@NotNull, @Size(max=64)

"must not be null", "size must be between 0 and 64"

active

@NotNull

"must not be null"

more

Optional

No size limit

recipients

@NotNull, not empty

"must not be null", "must not be empty"

Business Rules

[!info] Business Validation
name should be descriptive and unique (recommended)
At least one recipient must be associated with the group
Recipients must exist in the database before association
Inactive groups may still maintain recipient associations
Many-to-many relationship allows recipients to belong to multiple groups

Security & Authentication

Authorization

[!abstract] Access Control

The RecipientGroup API requires proper authentication and authorization:

Required Permissions:

CREATE - Create new recipient groups
UPDATE - Modify existing groups
READ - View groups and their details
DELETE - Remove groups

Many-to-Many Relationship

[!info] Recipient Association

RecipientGroups use a many-to-many relationship with Recipients:

Join Table: rel_recipient_group__recipient

Column

Type

Description

recipient_group_id

Long

Foreign key to recipient_group

recipient_id

Long

Foreign key to recipient

Characteristics:

One recipient can belong to multiple groups
One group can contain multiple recipients
Deleting a group removes associations but not recipients
Deleting a recipient removes it from all groups

Active Status Management

[!tip] Group Lifecycle

Groups can be activated or deactivated:

Best Practices:

✅ Use active=false instead of deletion for historical data
✅ Inactive groups retain their recipient associations
✅ Queries can filter by active status
✅ Reactivation is simple (toggle active flag)

Additional Information Field

[!note] Flexible Metadata

The more field provides flexibility for additional data:

Use Cases:

Detailed group descriptions
Business rules or criteria
Contact information
Internal notes
JSON-formatted metadata (if needed)

Example:

{
  "name": "Premium Services",
  "active": true,
  "more": "High-priority recipients requiring expedited processing. SLA: 2 hours. Contact: [email protected]"
}

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/recipient-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "New Group",
    "active": true,
    "more": "Group description",
    "recipients": [{"id": 1}, {"id": 2}]
  }'

Update

curl -X PUT http://localhost:8080/api/recipient-groups/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "Updated Group",
    "active": true,
    "recipients": [{"id": 1}, {"id": 2}, {"id": 3}]
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/recipient-groups/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "active": false}'

Get All

curl -X GET "http://localhost:8080/api/recipient-groups?active.equals=true&page=0&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

curl -X GET http://localhost:8080/api/recipient-groups/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Count

curl -X GET "http://localhost:8080/api/recipient-groups/count?active.equals=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

curl -X DELETE http://localhost:8080/api/recipient-groups/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

📝 Notes

[!success] Key Features
Simple CRUD operations for group management
Flexible many-to-many recipient associations
Active/inactive status for lifecycle management
Pagination and filtering support
Full audit trail (created/modified by/date)

[!tip] Best Practices
Use descriptive group names
Leverage the more field for additional context
Deactivate instead of delete for data retention
Regularly review and update group memberships
Use pagination for large result sets

[!warning] Important Considerations
Deleting a group does not delete associated recipients
Recipients can belong to multiple groups simultaneously
All recipient IDs must exist before group creation/update
Group names should be unique for clarity (though not enforced by DB)

PreviousRecipient NextSetting

Last updated 1 month ago

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagRecipientGroup DTO Structure

hashtagField Specifications

hashtagAudit Fields (Inherited)

hashtagAPI Endpoints

hashtagCreate RecipientGroup

hashtagRequest

hashtagResponse

hashtagUpdate RecipientGroup

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagPartial Update

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagGet All RecipientGroups

hashtagQuery Parameters

hashtagExample Requests

hashtagResponse

hashtagGet Single RecipientGroup

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagCount RecipientGroups

hashtagQuery Parameters

hashtagExample Requests

hashtagResponse

hashtagDelete RecipientGroup

hashtagPath Parameters

hashtagRequest

hashtagResponse

hashtagExamples

hashtagExample 1: Create Group for Utility Providers

hashtagExample 2: Update Group with New Recipients

hashtagExample 3: Deactivate Group

hashtagExample 4: Get Active Groups Only

hashtagExample 5: Search Groups by Name

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Error Example

hashtagValidation Rules

hashtagRequired Fields

hashtagField Constraints

hashtagBusiness Rules

hashtagSecurity & Authentication

hashtagAuthorization

hashtagMany-to-Many Relationship

hashtagActive Status Management

hashtagAdditional Information Field

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet Single

hashtagCount

hashtagDelete

hashtag📝 Notes

📋 Table of Contents

Quick Reference

Endpoints Summary

Data Models

RecipientGroup DTO Structure

Field Specifications

Audit Fields (Inherited)

API Endpoints

Create RecipientGroup

Request

Response

Update RecipientGroup

Path Parameters

Request

Response

Partial Update

Path Parameters

Request

Response

Get All RecipientGroups

Query Parameters

Example Requests

Response

Get Single RecipientGroup

Path Parameters

Request

Response

Count RecipientGroups

Query Parameters

Example Requests

Response

Delete RecipientGroup

Path Parameters

Request

Response

Examples

Example 1: Create Group for Utility Providers

Example 2: Update Group with New Recipients

Example 3: Deactivate Group

Example 4: Get Active Groups Only

Example 5: Search Groups by Name

Error Handling

Error Response Format

HTTP Status Codes

Validation Error Example

Validation Rules

Required Fields

Field Constraints

Business Rules

Security & Authentication

Authorization

Many-to-Many Relationship

Active Status Management

Additional Information Field

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get Single

Count

Delete

📝 Notes