Agent

[!info] Overview The Agent REST API manages payment agents (initiators) in the pkbillms billing system. Agents are entities authorized to initiate payment transactions through API integration with authentication and IP filtering capabilities.

📋 Table of Contents

• Quick Reference

• Data Models

• API Endpoints

  • Create Agent

  • Create Agent with User

  • Update Agent

  • Partial Update

  • Get All Agents

  • Get Simple Agents

  • Get Single Agent

  • Count Agents

  • Soft Delete Agent

  • Hard Delete Agent

• Error Handling

• Validation Rules

• Security & Authentication

---

Quick Reference

[!abstract] API Configuration

• Base URL: /api

• Entity Name: pkbillmsAgent

• Controller: AgentResource

• Framework: Spring Boot + JHipster

• Auth: Required (Spring Security)

• Content-Type: application/json

Endpoints Summary

Method	Endpoint	Description	Status
POST	/api/agents	Create new agent	201
POST	/api/agents/save-with-user	Create agent with user account	201
PUT	/api/agents/{id}	Full update	200
PATCH	/api/agents/{id}	Partial update	200
GET	/api/agents	Get all with criteria	200
GET	/api/agents/simple	Get simple key-value list	200
GET	/api/agents/{id}	Get by ID	200
GET	/api/agents/count	Count by criteria	200
DELETE	/api/agents/{id}	Soft delete agent	204
DELETE	/api/agents/hard/{id}	Hard delete agent	204

---

Data Models

Agent DTO Structure

[!note] Data Transfer Object Represents a payment agent with API authentication and multilingual support.

@ApiModel(description = "Агент, инициатор оплаты")
public class AgentDTO extends AbstractAuditingDTO {
    private Long id;
    private String shortName;         // Display name (max 64)
    private Integer amountRatio;      // Amount precision (1=sum, 100=tiyin)
    private String apiKey;            // API authentication key (max 64)
    private Set<Integer> currencies;  // Allowed currencies (max 64 chars)
    private Set<String> ipAddresses;  // IP whitelist (max 32 chars)
    private byte[] logo;              // Logo binary data (LOB)
    private String logoContentType;   // Logo MIME type
    private Integer ord;              // Display order
    private Boolean active;           // Active status
    private String phoneNumber;       // Contact phone (max 32)
    private String inn;               // Tax ID (max 32)
    private String orgName;           // Organization name (max 64)
    private String email;             // Email address (4-254 chars, unique)
    private AgentState state;         // Agent state enum
    private Set<I18nDTO> titles;      // Multilingual titles
}

Field Specifications

Field	Type	Required	Max/Range	DB Column	Description
id	Long	❌ Auto	-	id	Primary key
shortName	String	✅	64	short_name	Display name
amountRatio	Integer	✅	-	amount_ratio	Precision (1 or 100)
apiKey	String	✅	64	api_key	API authentication key
currencies	Set	✅	64 chars	currencies	Allowed currency codes
ipAddresses	Set	❌	32 chars	ip_addresses	IP whitelist
logo	byte[]	❌	LOB	logo	Logo image binary
logoContentType	String	❌	-	logo_content_type	MIME type
ord	Integer	❌	-	ord	Display order
active	Boolean	✅	-	active	Active/Inactive
phoneNumber	String	❌	32	phone_number	Contact phone
inn	String	❌	32	inn	Tax ID (INN/VAT)
orgName	String	❌	64	org_name	Organization name
email	String	❌	4-254	email	Email (unique)
state	AgentState	❌	ENUM	state	Agent state
titles	Set	✅	-	rel_agent__title	Multilingual titles

AgentState Enum

public enum AgentState {
    NEW  
	ACTIVE  
	DELETED
}

DetailedAgentDTO

[!note] Extended DTO for User Creation Used when creating an agent with an associated user account.

public class DetailedAgentDTO {
    private AgentDTO agentDTO;           // Agent data
    private String userLogin;            // User login
    private String userPassword;         // User password
    private Set<String> authorities;     // User roles/authorities
}

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 Agent

POST /api/agents

Creates a new payment agent entity.

Request

Headers:

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

Body:

{
  "shortName": "AGENT_MAIN",
  "amountRatio": 100,
  "apiKey": "sk_live_abc123xyz789def456ghi012jkl345",
  "currencies": [860, 840, 978],
  "ipAddresses": ["192.168.1.100", "10.0.0.50", "172.16.0.10"],
  "ord": 1,
  "active": true,
  "phoneNumber": "[phone]",
  "inn": "123456789",
  "orgName": "Main Payment Agent LLC",
  "email": "[email protected]",
  "state": "ACTIVE",
  "titles": [
    {
      "lang": "EN",
      "text": "Main Agent"
    },
    {
      "lang": "RU",
      "text": "Главный агент"
    },
    {
      "lang": "UZ",
      "text": "Asosiy agent"
    }
  ]
}

[!warning] Validation Rules

• id must be null (auto-generated)

• shortName, amountRatio, apiKey, currencies, active, titles are required

• email must be unique if provided

• currencies and ipAddresses are stored as comma-separated values

• String fields must respect max length

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/agents/1

{
  "id": 1,
  "shortName": "AGENT_MAIN",
  "amountRatio": 100,
  "apiKey": "sk_live_abc123xyz789def456ghi012jkl345",
  "currencies": [860, 840, 978],
  "ipAddresses": ["192.168.1.100", "10.0.0.50", "172.16.0.10"],
  "ord": 1,
  "active": true,
  "phoneNumber": "[phone]",
  "inn": "123456789",
  "orgName": "Main Payment Agent LLC",
  "email": "[email protected]",
  "state": "ACTIVE",
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Main Agent"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "Главный агент"
    },
    {
      "id": 3,
      "lang": "UZ",
      "text": "Asosiy agent"
    }
  ],
  "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 agent cannot already have an ID",
  "message": "error.idexists"
}

---

Create Agent with User

[!example] POST /api/agents/save-with-user Creates a new agent with an associated user account in one transaction.

Request

Headers:

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

Body:

{
  "agentDTO": {
    "shortName": "BRANCH_AGENT_01",
    "amountRatio": 100,
    "apiKey": "sk_live_branch01_xyz789abc456",
    "currencies": [860],
    "active": true,
    "phoneNumber": "[phone]",
    "email": "[email protected]",
    "state": "PENDING",
    "titles": [
      {
        "lang": "en",
        "text": "Branch Agent 01"
      }
    ]
  },
  "userLogin": "branch01",
  "userPassword": "SecureP@ssw0rd123",
  "authorities": ["ROLE_AGENT", "ROLE_USER"]
}

[!warning] User Creation Rules

• User login must be unique

• Password must meet security requirements

• Authorities are assigned to the user

• User is automatically linked to the agent

Response

✅ Success (201 Created):

{
  "id": 2,
  "shortName": "BRANCH_AGENT_01",
  "amountRatio": 100,
  "apiKey": "sk_live_branch01_xyz789abc456",
  "currencies": [860],
  "active": true,
  "phoneNumber": "[phone]",
  "email": "[email protected]",
  "state": "PENDING",
  "titles": [...],
  "createdBy": "admin",
  "createdDate": "2024-01-29T11:00:00Z"
}

[!info] Use Case This endpoint is useful for:

• Onboarding new agents

• Creating agent accounts with system access

• Automated agent provisioning

---

Update Agent

[!example] PUT /api/agents/{id} Completely updates an existing agent.

Path Parameters

• id (Long) - Agent identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "shortName": "AGENT_MAIN_UPDATED",
  "amountRatio": 100,
  "apiKey": "sk_live_updated_key_987654321",
  "currencies": [860],
  "active": true,
  "email": "[email protected]",
  "state": "ACTIVE",
  "titles": [...]
}

[!warning] Validation

• Body id must not be null

• Path id must match body id

• Agent must exist in database

• Email must be unique (if changed)

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "AGENT_MAIN_UPDATED",
  "apiKey": "sk_live_updated_key_987654321",
  "currencies": [860],
  "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/agents/{id} Updates only specified fields. Null fields are ignored.

Path Parameters

• id (Long) - Agent identifier

Request

Headers:

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

Body (Example - toggle active and update state):

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

[!tip] Partial Update Behavior

• Only non-null fields are updated

• Other fields remain unchanged

• Perfect for status toggles or single field updates

• API keys can be rotated without changing other data

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "AGENT_MAIN_UPDATED",
  "active": false,
  "state": "ACTIVE",
  "lastModifiedDate": "2024-01-29T15:45:00Z"
}

---

Get All Agents

[!example] GET /api/agents 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., shortName,asc)

• unPaged - Boolean for unpaged results

Filters (AgentCriteria):

• id.equals, id.in

• shortName.contains, shortName.equals

• active.equals - Filter by status

• state.equals, state.in - Filter by state

• email.contains

• inn.equals

• apiKey.equals - Find by API key

Example Requests

GET /api/agents?page=0&size=10&sort=shortName,asc
GET /api/agents?active.equals=true
GET /api/agents?state.equals=ACTIVE&active.equals=true
GET /api/agents?shortName.contains=BRANCH

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "shortName": "AGENT_MAIN",
    "amountRatio": 100,
    "apiKey": "sk_live_abc123xyz789def456ghi012jkl345",
    "currencies": [860, 840, 978],
    "active": true,
    "state": "ACTIVE",
    "email": "[email protected]",
    "titles": [...]
  },
  {
    "id": 2,
    "shortName": "BRANCH_AGENT_01",
    "amountRatio": 100,
    "currencies": [860],
    "active": true,
    "state": "NEW",
    "email": "[email protected]",
    "titles": [...]
  }
]

---

Get Simple Agents

[!example] GET /api/agents/simple Retrieves simplified key-value list for dropdowns and selection lists.

Query Parameters

• Same criteria as [[#Get All Agents]]

• Pagination supported

Example Request

GET /api/agents/simple?active.equals=true&sort=shortName,asc

Response

✅ Success (200 OK):

[
  {
    "key": 1,
    "value": "AGENT_MAIN"
  },
  {
    "key": 2,
    "value": "BRANCH_AGENT_01"
  },
  {
    "key": 3,
    "value": "BRANCH_AGENT_02"
  }
]

[!tip] Use Case Perfect for:

• Dropdown selections in UI

• Autocomplete fields

• Report filters

• Minimal data transfer

---

Get Single Agent

[!example] GET /api/agents/{id} Retrieves a single agent by ID with all relationships.

Path Parameters

• id (Long) - Agent identifier

Request

GET /api/agents/1
Authorization: Bearer {token}

Response

✅ Success (200 OK):

{
  "id": 1,
  "shortName": "AGENT_MAIN",
  "amountRatio": 100,
  "apiKey": "sk_live_abc123xyz789def456ghi012jkl345",
  "currencies": [860, 840, 978],
  "ipAddresses": ["192.168.1.100", "10.0.0.50"],
  "logo": "base64encodeddata...",
  "logoContentType": "image/png",
  "ord": 1,
  "active": true,
  "phoneNumber": "[phone]",
  "inn": "123456789",
  "orgName": "Main Payment Agent LLC",
  "email": "[email protected]",
  "state": "ACTIVE",
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Main Agent"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "Главный агент"
    }
  ],
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T10:30:00Z"
}

❌ Error (404 Not Found):

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

---

Count Agents

example GET /api/agents/count Returns count of agents matching criteria.

Query Parameters

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

Example Requests

GET /api/agents/count
GET /api/agents/count?active.equals=true
GET /api/agents/count?state.equals=ACTIVE
GET /api/agents/count?shortName.contains=BRANCH

Response

✅ Success (200 OK):

45

---

Soft Delete Agent

DELETE /api/agents/{id}

Soft deletes an agent (marks as inactive, preserves data).

Path Parameters

• id (Long) - Agent identifier

Request

DELETE /api/agents/1
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

[!info] Soft Delete Behavior

• Agent is not permanently deleted

• Typically sets active = false or similar flag

• Historical data is preserved

• Agent can be reactivated

• Transactions remain linked

---

Hard Delete Agent

[!example] DELETE /api/agents/hard/{id} Permanently deletes an agent from the database.

Path Parameters

• id (Long) - Agent identifier

Request

DELETE /api/agents/hard/1
Authorization: Bearer {token}

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

[!danger] Hard Delete Warning Permanently deletes:

• Agent entity

• Associated I18n titles

• May fail if agent has dependent relationships (AgentRecipients, Deposits)

Use with extreme caution! This cannot be undone.

---

Examples

Example 1: Create Agent for Branch Office

[!example]- Setup Branch Agent Request:

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "shortName": "TASHKENT_BRANCH_01",
    "amountRatio": 100,
    "apiKey": "sk_live_tashkent_br01_key123",
    "currencies": [860],
    "ipAddresses": ["203.0.113.10", "198.51.100.20"],
    "active": true,
    "phoneNumber": "[phone]",
    "inn": "200123456",
    "orgName": "Tashkent Branch Office",
    "email": "[email protected]",
    "state": "ACTIVE",
    "titles": [
      {"lang": "en", "text": "Tashkent Branch 01"},
      {"lang": "ru", "text": "Ташкентский филиал 01"},
      {"lang": "uz", "text": "Toshkent filiali 01"}
    ]
  }'

Example 2: Create Agent with User Account

[!example]- Onboard New Agent with Login Request:

curl -X POST http://localhost:8080/api/agents/save-with-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "agentDTO": {
      "shortName": "SAMARKAND_AGENT",
      "amountRatio": 100,
      "apiKey": "sk_live_samarkand_key456",
      "currencies": [860],
      "active": true,
      "email": "[email protected]",
      "state": "ACTIVE",
      "titles": [{"lang": "en", "text": "Samarkand Agent"}]
    },
    "userLogin": "samarkand_user",
    "userPassword": "SecurePass@2024",
    "authorities": ["ROLE_AGENT", "ROLE_USER"]
  }'

Example 3: Rotate API Key

[!example]- Update API Key for Security Request:

curl -X PATCH http://localhost:8080/api/agents/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "id": 1,
    "apiKey": "sk_live_new_rotated_key_987654"
  }'

Response:

{
  "id": 1,
  "shortName": "AGENT_MAIN",
  "apiKey": "sk_live_new_rotated_key_987654",
  "lastModifiedDate": "2024-01-29T17:30:12.456Z"
}

Example 4: Suspend Agent

[!example]- Temporarily Suspend Agent Request:

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

---

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/agents",
  "message": "error.code",
  "params": "additionalInfo"
}

HTTP Status Codes

Code	Type	Description	Common Causes
400	Bad Request	Invalid request	Validation failure, ID mismatch, duplicate email
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 shortName, email already exists
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/agents",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "agentDTO",
      "field": "shortName",
      "message": "must not be null"
    },
    {
      "objectName": "agentDTO",
      "field": "email",
      "message": "must be a well-formed email address"
    },
    {
      "objectName": "agentDTO",
      "field": "apiKey",
      "message": "size must be between 0 and 64"
    }
  ]
}

---

Validation Rules

Required Fields

[!check] Mandatory Fields

• ✅ shortName - Display name

• ✅ amountRatio - Amount precision

• ✅ apiKey - API authentication key

• ✅ currencies - Allowed currencies

• ✅ active - Active status

• ✅ titles - At least one title required

Field Constraints

Field	Rules	Error Messages
id	Null for POST	"A new agent cannot already have an ID"
id	Not null for PUT/PATCH	"Invalid id"
shortName	@NotNull, @Size(max=64)	"must not be null", "size must be between 0 and 64"
amountRatio	@NotNull	"must not be null"
apiKey	@NotNull, @Size(max=64)	"must not be null", "size must be between 0 and 64"
currencies	@NotNull, @Size(max=64)	"must not be null", "size must be between 0 and 64"
ipAddresses	@Size(max=32)	"size must be between 0 and 32"
active	@NotNull	"must not be null"
phoneNumber	@Size(max=32)	"size must be between 0 and 32"
inn	@Size(max=32)	"size must be between 0 and 32"
orgName	@Size(max=64)	"size must be between 0 and 64"
email	@Size(min=4, max=254), unique	"size must be between 4 and 254", "must be unique"
titles	@NotNull, not empty	"must not be null", "must not be empty"

Business Rules

[!info] Business Validation

• shortName should be unique (recommended)

• email must be unique if provided

• apiKey should be cryptographically secure (64 chars recommended)

• currencies contains ISO 4217 numeric currency codes

• ipAddresses contains valid IPv4/IPv6 addresses

• amountRatio typically 1 (sum) or 100 (tiyin)

• At least one title must be provided

---

Security & Authentication

API Key Authentication

[!abstract] Agent API Key System

The apiKey field is used to authenticate agents when making API requests:

Key Format:

• Length: Up to 64 characters

• Recommended format: sk_live_{environment}_{random}

• Example: sk_live_production_abc123xyz789

Security Best Practices:

✅ Use cryptographically random generation
✅ Minimum 32 characters for production
✅ Include environment prefix (test/live)
✅ Rotate keys periodically
✅ Store securely (never in version control)
✅ Use different keys per environment

Key Rotation:

# Update agent's API key
PATCH /api/agents/{id}
{
  "id": 1,
  "apiKey": "sk_live_new_key_generated_securely"
}

IP Address Filtering

[!info] IP Whitelist Configuration

Agents can restrict API access to specific IP addresses:

Format:

• Stored as Set in database

• Converted to comma-separated values

• Supports both IPv4 and IPv6

Example Configuration:

{
  "ipAddresses": [
    "192.168.1.100",
    "10.0.0.50",
    "172.16.0.10",
    "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
  ]
}

Currency Restrictions

[!tip] Multi-Currency Support

Agents can be restricted to specific currencies:

Currency Codes (ISO 4217):

• 860 - UZS (Uzbekistan Sum)

• 840 - USD (US Dollar)

• 978 - EUR (Euro)

• 643 - RUB (Russian Ruble)

Example:

{
  "currencies": [860, 840],
  "// ": "Agent can only process UZS and USD"
}

Multilingual Support

[!tip] I18n Integration

Agents support multiple languages through I18n titles:

Example:

{
  "titles": [
    {"lang": "EN", "text": "Main Payment Agent"},
    {"lang": "RU", "text": "Главный платежный агент"},
    {"lang": "UZ", "text": "Asosiy to'lov agenti"}
  ]
}

Display Logic:

// Frontend selects title based on user's language
const getAgentTitle = (agent, locale) => {
  const title = agent.titles.find(t => t.lang === locale);
  return title ? title.text : agent.shortName;
};

---

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "shortName": "NEW_AGENT",
    "amountRatio": 100,
    "apiKey": "sk_live_new_agent_key123",
    "currencies": [860],
    "active": true,
    "email": "[email protected]",
    "state": "ACTIVE",
    "titles": [{"lang": "EN", "text": "New Agent"}]
  }'

Create with User

curl -X POST http://localhost:8080/api/agents/save-with-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "agentDTO": {
      "shortName": "AGENT_WITH_USER",
      "amountRatio": 100,
      "apiKey": "sk_live_key",
      "currencies": [860],
      "active": true,
      "titles": [{"lang": "EN", "text": "Agent"}]
    },
    "userLogin": "agent_user",
    "userPassword": "SecurePass123",
    "authorities": ["ROLE_AGENT"]
  }'

Update

curl -X PUT http://localhost:8080/api/agents/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "shortName": "UPDATED_AGENT",
    "amountRatio": 100,
    "apiKey": "sk_live_updated",
    "currencies": [860],
    "active": true,
    "titles": [{"lang": "EN", "text": "Updated"}]
  }'

Partial Update

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

Get All

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

Get Simple

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

Get Single

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

Count

curl -X GET "http://localhost:8080/api/agents/count?state.equals=ACTIVE" \
  -H "Authorization: Bearer YOUR_TOKEN"

Soft Delete

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

Hard Delete

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