Agent-Recipient

[!info] Overview The Agent-Recipient REST API manages the relationship between agents and service providers (recipients). This entity defines which recipients are available to which agents and controls commission structures, fees, and integration parameters.

📋 Table of Contents

• [[#Quick Reference|Quick Reference]]

• [[#Data Models|Data Models]]

• [[#API Endpoints|API Endpoints]]

  • [[#Create Agent-Recipient|Create Agent-Recipient]]

  • [[#Update Agent-Recipient|Update Agent-Recipient]]

  • [[#Partial Update|Partial Update]]

  • [[#Get All Agent-Recipients|Get All Agent-Recipients]]

  • [[#Get with Criteria|Get with Criteria]]

  • [[#Get V2 (Projection)|Get V2 (Projection)]]

  • [[#Export to Excel|Export to Excel]]

  • [[#Get Single Agent-Recipient|Get Single Agent-Recipient]]

  • [[#Count Agent-Recipients|Count Agent-Recipients]]

  • [[#Delete Agent-Recipient|Delete Agent-Recipient]]

• [[#Examples|Request & Response Examples]]

• [[#Error Handling|Error Handling]]

• [[#Validation Rules|Validation Rules]]

• [[#Commission System|Commission System]]

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: pkbillmsAgentRecipient

• Controller: AgentRecipientResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

Method	Endpoint	Description	Status
POST	/api/agent-recipients	Create new relationship	201
PUT	/api/agent-recipients/{id}	Full update	200
PATCH	/api/agent-recipients/{id}	Partial update	200
GET	/api/agent-recipients	Get all with criteria	200
GET	/api/agent-recipients/v2	Get with projection	200
GET	/api/agent-recipients/excel	Get for Excel export	200
GET	/api/agent-recipients/criteria	Get by agent/recipient name	200
GET	/api/agent-recipients/{id}	Get by ID	200
GET	/api/agent-recipients/count	Count by criteria	200
DELETE	/api/agent-recipients/{id}	Delete relationship	204

---

Data Models

Agent-Recipient DTO Structure

[!note] Data Transfer Object Defines agent-to-recipient relationship with commission configuration and integration parameters.

@ApiModel(description = "Доступные поставщики агенту")
public class AgentRecipientDTO extends AbstractAuditingDTO {
    private Long id;
    private Double agentCommission;       // Agent commission % (0-100)
    private Double agentFee;              // Agent reward % (0-100)
    private Double systemCommissionUp;    // System commission (on top) %
    private Double systemCommissionDown;  // System commission (from amount) %
    private Double systemFee;             // System reward % (0-100)
    private Boolean active;               // Active status
    private Integer eposPort;             // EPOS port (0-65535)
    private String eposMerchant;          // Merchant ID (max 32)
    private String eposTerminal;          // Terminal ID (max 32)
    private String requestGroup;          // Request group (max 64)
    private String jsonParams;            // Additional JSON params (LOB)
    private AgentDTO agent;               // Associated agent
    private RecipientDTO recipient;       // Associated recipient
    private SettingDTO setting;           // Configuration settings
    private SettingTypeDTO settingType;   // Setting type
    private RecipientGroupDTO recipientGroup; // Recipient group
}

Field Specifications

Field	Type	Required	Range/Max	DB Column	Description
id	Long	❌ Auto	-	id	Primary key
agentCommission	Double	❌	0-100	agent_commission	Agent commission % from customer payment
agentFee	Double	❌	0-100	agent_fee	Agent reward % from system
systemCommissionUp	Double	❌	max 100	system_commission_up	System commission added on top
systemCommissionDown	Double	❌	0-100	system_commission_down	System commission from customer payment
systemFee	Double	❌	0-100	system_fee	System reward % from provider
active	Boolean	✅	-	active	Active/Inactive status
eposPort	Integer	❌	0-65535	epos_port	SvGate EPOS port
eposMerchant	String	❌	32	epos_merchant	SvGate Merchant ID
eposTerminal	String	❌	32	epos_terminal	SvGate Terminal ID
requestGroup	String	❌	64	request_group	Request grouping identifier
jsonParams	String	❌	LOB	json_params	Additional JSON parameters
agent	AgentDTO	❌	-	agent_id	Associated agent
recipient	RecipientDTO	❌	-	recipient_id	Associated recipient
setting	SettingDTO	❌	-	setting_id	Configuration settings
settingType	SettingTypeDTO	❌	-	-	Setting type reference
recipientGroup	RecipientGroupDTO	❌	-	recipient_group_id	Recipient group

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

[!info] Relationships

• Agent: @ManyToOne - Each relationship belongs to one agent

• Recipient: @ManyToOne - Each relationship provides access to one recipient

• Setting: @ManyToOne (Optional) - Configuration settings

• RecipientGroup: @ManyToOne (Optional) - Group categorization

---

API Endpoints

Create Agent-Recipient

[!example] POST /api/agent-recipients Creates a new agent-recipient relationship with commission configuration.

Request

Headers:

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

Body:

{
  "agentCommission": 1.5,
  "agentFee": 0.5,
  "systemCommissionUp": 0.3,
  "systemCommissionDown": 0.2,
  "systemFee": 0.8,
  "active": true,
  "eposPort": 8080,
  "eposMerchant": "MERCHANT_001",
  "eposTerminal": "TERMINAL_001",
  "requestGroup": "GROUP_A",
  "jsonParams": "{\"timeout\":30000,\"retryCount\":3}",
  "agent": {
    "id": 1
  },
  "recipient": {
    "id": 5
  },
  "setting": {
    "id": 10
  },
  "recipientGroup": {
    "id": 2
  }
}

[!warning] Validation Rules

• id must be null (auto-generated)

• active is required

• Commission values must be between 0-100 (except systemCommissionUp which can be negative for discounts)

• eposPort must be 0-65535

• String fields must respect max length

• Agent and Recipient should exist if specified

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/agent-recipients/1

{
  "id": 1,
  "agentCommission": 1.5,
  "agentFee": 0.5,
  "systemCommissionUp": 0.3,
  "systemCommissionDown": 0.2,
  "systemFee": 0.8,
  "active": true,
  "eposPort": 8080,
  "eposMerchant": "MERCHANT_001",
  "eposTerminal": "TERMINAL_001",
  "requestGroup": "GROUP_A",
  "jsonParams": "{\"timeout\":30000,\"retryCount\":3}",
  "agent": {
    "id": 1,
    "shortName": "AGENT_MAIN"
  },
  "recipient": {
    "id": 5,
    "shortName": "UZCARD_PAY"
  },
  "setting": {
    "id": 10,
    "key": "payment_config"
  },
  "recipientGroup": {
    "id": 2,
    "name": "Financial Services"
  },
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T10:30:00Z"
}

❌ Error (400 - ID exists):

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

❌ Error (400 - Validation):

{
  "type": "https://www.jhipster.tech/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "fieldErrors": [
    {
      "objectName": "agentRecipientDTO",
      "field": "agentCommission",
      "message": "must be less than or equal to 100"
    }
  ]
}

---

Update Agent-Recipient

[!example] PUT /api/agent-recipients/{id} Completely updates an existing agent-recipient relationship.

Path Parameters

• id (Long) - Agent-Recipient relationship identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "agentCommission": 2.0,
  "agentFee": 0.7,
  "systemCommissionUp": 0.5,
  "systemCommissionDown": 0.3,
  "systemFee": 1.0,
  "active": true,
  "agent": {
    "id": 1
  },
  "recipient": {
    "id": 5
  }
}

[!warning] Validation

• Body id must not be null

• Path id must match body id

• Agent-Recipient must exist in database

• All commission ranges must be valid

Response

✅ Success (200 OK):

{
  "id": 1,
  "agentCommission": 2.0,
  "agentFee": 0.7,
  "systemCommissionUp": 0.5,
  "systemCommissionDown": 0.3,
  "systemFee": 1.0,
  "active": true,
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T14:20:00Z"
}

❌ Errors:

Status	Detail	Message
400	Invalid id	error.idnull
400	Invalid ID	error.idinvalid
400	Entity not found	error.idnotfound

---

Partial Update

[!example] PATCH /api/agent-recipients/{id} Updates only specified fields. Null fields are ignored.

Path Parameters

• id (Long) - Agent-Recipient identifier

Request

Headers:

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

Body (Example - toggle active and update commissions):

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

[!tip] Partial Update Behavior

• Only non-null fields are updated

• Other fields remain unchanged

• Perfect for status toggles or commission adjustments

• Relationships can be partially updated

Response

✅ Success (200 OK):

{
  "id": 1,
  "agentCommission": 1.8,
  "agentFee": 0.7,
  "active": false,
  "lastModifiedDate": "2024-01-29T15:45:00Z"
}

---

Get All Agent-Recipients

[!example] GET /api/agent-recipients 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., id,asc)

• unPaged - Boolean for unpaged results

Filters (AgentRecipientCriteria):

• id.equals, id.in

• agentId.equals - Filter by agent ID

• recipientId.equals - Filter by recipient ID

• active.equals - Filter by status

• agentCommission.greaterThan, agentCommission.lessThan

• settingId.equals

• recipientGroupId.equals

Example Requests

GET /api/agent-recipients?page=0&size=10&sort=id,desc
GET /api/agent-recipients?active.equals=true
GET /api/agent-recipients?agentId.equals=1&active.equals=true
GET /api/agent-recipients?recipientId.in=5,6,7

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "agentCommission": 1.5,
    "agentFee": 0.5,
    "systemCommissionUp": 0.3,
    "systemCommissionDown": 0.2,
    "systemFee": 0.8,
    "active": true,
    "agent": {
      "id": 1,
      "shortName": "AGENT_MAIN"
    },
    "recipient": {
      "id": 5,
      "shortName": "UZCARD_PAY"
    }
  },
  {
    "id": 2,
    "agentCommission": 2.0,
    "agentFee": 0.6,
    "active": true,
    "agent": {
      "id": 1,
      "shortName": "AGENT_MAIN"
    },
    "recipient": {
      "id": 8,
      "shortName": "PAYME_MERCHANT"
    }
  }
]

---

Get V2 (Projection)

[!example] GET /api/agent-recipients/v2 Retrieves paginated list with projection interface for optimized queries.

Query Parameters

Pagination only:

• page - Page number (0-indexed)

• size - Items per page

• sort - Sort criteria

Example Request

GET /api/agent-recipients/v2?page=0&size=20&sort=id,desc

Response

✅ Success (200 OK):

[
  {
    "id": 1,
    "agentId": 1,
    "recipientId": 5,
    "agentCommission": 1.5,
    "agentFee": 0.5,
    "active": true
  }
]

[!info] Projection Interface This endpoint uses AgentRecipientInfo projection for better performance. Returns minimal fields without full relationship objects.

---

Export to Excel

[!example] GET /api/agent-recipients/excel Retrieves all agent-recipients for Excel export with read-only DTO.

Query Parameters

Same as [[#Get All Agent-Recipients]] but returns AgentRecipientReadOnlyDto.

Example Request

GET /api/agent-recipients/excel?active.equals=true&sort=id,asc

Response

✅ Success (200 OK):

[
  {
    "id": 1,
    "agentShortName": "AGENT_MAIN",
    "recipientShortName": "UZCARD_PAY",
    "agentCommission": 1.5,
    "agentFee": 0.5,
    "systemCommissionUp": 0.3,
    "systemCommissionDown": 0.2,
    "systemFee": 0.8,
    "active": true,
    "eposPort": 8080,
    "eposMerchant": "MERCHANT_001",
    "eposTerminal": "TERMINAL_001"
  }
]

[!tip] Use Case Use this endpoint when exporting data to Excel or other reporting formats.

---

Get Single Agent-Recipient

[!example] GET /api/agent-recipients/{id} Retrieves a single agent-recipient relationship by ID.

Path Parameters

• id (Long) - Agent-Recipient identifier

Request

GET /api/agent-recipients/1
Authorization: Bearer {token}

Response

✅ Success (200 OK):

{
  "id": 1,
  "agentCommission": 1.5,
  "agentFee": 0.5,
  "systemCommissionUp": 0.3,
  "systemCommissionDown": 0.2,
  "systemFee": 0.8,
  "active": true,
  "eposPort": 8080,
  "eposMerchant": "MERCHANT_001",
  "eposTerminal": "TERMINAL_001",
  "requestGroup": "GROUP_A",
  "jsonParams": "{\"timeout\":30000,\"retryCount\":3}",
  "agent": {
    "id": 1,
    "shortName": "AGENT_MAIN",
    "fullName": "Main Agent Office"
  },
  "recipient": {
    "id": 5,
    "shortName": "UZCARD_PAY",
    "serviceId": "SRV_UZCARD_001"
  },
  "setting": {
    "id": 10,
    "key": "payment_config",
    "value": "enabled"
  },
  "recipientGroup": {
    "id": 2,
    "name": "Financial Services"
  }
}

❌ Error (404 Not Found):

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

---

Count Agent-Recipients

[!example] GET /api/agent-recipients/count Returns count of agent-recipients matching criteria.

Query Parameters

Same filtering parameters as [[#Get All Agent-Recipients]]

Example Requests

GET /api/agent-recipients/count
GET /api/agent-recipients/count?active.equals=true
GET /api/agent-recipients/count?agentId.equals=1
GET /api/agent-recipients/count?recipientId.equals=5&active.equals=true

Response

✅ Success (200 OK):

87

---

Delete Agent-Recipient

[!example] DELETE /api/agent-recipients/{id} Deletes an agent-recipient relationship by ID.

Path Parameters

• id (Long) - Agent-Recipient identifier

Request

DELETE /api/agent-recipients/1
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content
X-pkbillmsApp-alert: pkbillmsApp.pkbillmsAgentRecipient.deleted
X-pkbillmsApp-params: 1

[!danger] Delete Warning Deleting an agent-recipient relationship will:

• Remove agent's access to the recipient

• Affect commission calculations for future transactions

• Not affect historical transactions

---

Examples

Example 1: Create Agent-Recipient for Financial Service

[!example]- Setup Uzcard for Agent Request:

curl -X POST http://localhost:8080/api/agent-recipients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "agentCommission": 1.5,
    "agentFee": 0.5,
    "systemCommissionUp": 0.3,
    "systemCommissionDown": 0.2,
    "systemFee": 0.8,
    "active": true,
    "eposPort": 8443,
    "eposMerchant": "UZCARD_MERCHANT_001",
    "eposTerminal": "TERMINAL_MAIN_001",
    "requestGroup": "FINANCIAL_GROUP",
    "jsonParams": "{\"apiEndpoint\":\"https://api.uzcard.uz\",\"timeout\":30000}",
    "agent": {"id": 1},
    "recipient": {"id": 5},
    "recipientGroup": {"id": 2}
  }'

Example 2: Update Commission Rates

[!example]- Adjust Agent Commission Request:

curl -X PATCH http://localhost:8080/api/agent-recipients/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "agentCommission": 2.0,
    "systemCommissionDown": 0.3
  }'

Response:

{
  "id": 1,
  "agentCommission": 2.0,
  "agentFee": 0.5,
  "systemCommissionDown": 0.3,
  "active": true,
  "lastModifiedDate": "2024-01-29T17:30:12.456Z"
}

Example 3: Find Agent's Recipients

[!example]- Get All Active Recipients for Agent Request:

curl -X GET "http://localhost:8080/api/agent-recipients?\
agentId.equals=1&\
active.equals=true&\
page=0&\
size=50&\
sort=recipient.shortName,asc" \
  -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/agent-recipients",
  "message": "error.code",
  "params": "additionalInfo"
}

HTTP Status Codes

Code	Type	Description	Common Causes
400	Bad Request	Invalid request	Validation failure, ID mismatch, invalid commission
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 agent-recipient pair
500	Server Error	Internal error	Database error, exception

Validation Error Example

[!bug] Commission Validation Error

{
  "type": "https://www.jhipster.tech/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "path": "/api/agent-recipients",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "agentRecipientDTO",
      "field": "agentCommission",
      "message": "must be less than or equal to 100"
    },
    {
      "objectName": "agentRecipientDTO",
      "field": "eposPort",
      "message": "must be less than or equal to 65535"
    }
  ]
}

---

Validation Rules

Required Fields

[!check] Mandatory Fields

• ✅ active - Active status flag (true/false)

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"A new agentRecipient cannot already have an ID"
id	Not null for PUT/PATCH	"Invalid id"
agentCommission	@DecimalMin(0), @DecimalMax(100)	"must be greater than or equal to 0", "must be less than or equal to 100"
agentFee	@DecimalMin(0), @DecimalMax(100)	"must be greater than or equal to 0", "must be less than or equal to 100"
systemCommissionUp	@DecimalMax(100)	"must be less than or equal to 100" (can be negative)
systemCommissionDown	@DecimalMin(0), @DecimalMax(100)	"must be greater than or equal to 0", "must be less than or equal to 100"
systemFee	@DecimalMin(0), @DecimalMax(100)	"must be greater than or equal to 0", "must be less than or equal to 100"
active	@NotNull	"must not be null"
eposPort	@Min(0), @Max(65535)	"must be greater than or equal to 0", "must be less than or equal to 65535"
eposMerchant	@Size(max=32)	"size must be between 0 and 32"
eposTerminal	@Size(max=32)	"size must be between 0 and 32"
requestGroup	@Size(max=64)	"size must be between 0 and 64"

Business Rules

[!info] Business Validation

• Agent and Recipient combination should be unique

• At least one commission/fee should be configured

• EPOS parameters are required if integration is enabled

• Commission values should make business sense (total shouldn't exceed 100%)

---

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/agent-recipients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "agentCommission": 1.5,
    "agentFee": 0.5,
    "systemCommissionUp": 0.3,
    "systemCommissionDown": 0.2,
    "systemFee": 0.8,
    "active": true,
    "agent": {"id": 1},
    "recipient": {"id": 5}
  }'

Update

curl -X PUT http://localhost:8080/api/agent-recipients/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "agentCommission": 2.0,
    "agentFee": 0.6,
    "active": true,
    "agent": {"id": 1},
    "recipient": {"id": 5}
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/agent-recipients/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/agent-recipients?active.equals=true&page=0&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get V2 (Projection)

curl -X GET "http://localhost:8080/api/agent-recipients/v2?page=0&size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

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

Count

curl -X GET "http://localhost:8080/api/agent-recipients/count?agentId.equals=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

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