Response field

[!info] Overview The ResponseField REST API manages response field configurations for payment transaction results in the pkbillms billing system. ResponseFields define which data fields are returned from backend services, their visibility, formatting, and display order with multilingual support.

📋 Table of Contents

Quick Reference

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

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/response-fields

Create new response field

201

PUT

/api/response-fields/{id}

Full update

200

PATCH

/api/response-fields/{id}

Partial update

200

GET

/api/response-fields

Get all with pagination

200

GET

/api/response-fields/{id}

Get by ID

200

GET

/api/response-fields/count

Count by criteria

200

DELETE

/api/response-fields/{id}

Delete response field

204

Data Models

ResponseField Specifications

Field

Type

Required

Max/Range

Description

id

Long

❌ Auto

Primary key

name

String

✅

128

Response field name (account_id, phone, etc.)

visibility

Visibility

❌

ENUM

UI visibility setting

ord

Integer

❌

Display order

requestType

RequestType

❌

ENUM

Transaction type association

type

ResponseFieldType

❌

ENUM

Field data type

amountRatio

Integer

❌

Amount fraction (1=sum, 100=tiyin)

active

Boolean

❌

Activation status

recipient

RecipientDTO

✅

Payment recipient reference

labels

Set

✅

Multilingual labels

Visibility Enum

public enum Visibility {
    HIDDEN,    // Hidden from UI
    PRINTER,   // Visible on printer receipts
    MONITOR,   // Visible on monitor/screen
    ALL        // Visible everywhere
}

RequestType Enum

public enum RequestType {
    CHECK,           // Transaction check
    INFO,            // Information request
    PAY,             // Payment transaction
    STATUS,          // Status inquiry
    CANCEL,          // Cancellation
    DEPOSIT,         // Deposit operation
    RECONCILE,       // Reconciliation
    CREDIT,          // Credit transaction
    DEBIT,           // Debit transaction
    P2P_CREDIT,      // P2P credit
    P2P_DEBIT,       // P2P debit
    P2P_COMMISSION,  // P2P commission
    CONFIRM,         // Confirmation
    ALL              // All request types
}

ResponseFieldType Enum

public enum ResponseFieldType {
    TEXT,    // Text data
    AMOUNT,  // Monetary amount
    DATE     // Date/time
}

API Endpoints

Create ResponseField

POST /api/response-fields
Creates a new response field configuration.

Request

Headers:

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

Body:

{
  "name": "account_balance",
  "visibility": "ALL",
  "ord": 1,
  "requestType": "CHECK",
  "type": "AMOUNT",
  "amountRatio": 100,
  "active": true,
  "recipient": {
    "id": 5
  },
  "labels": [
    {
      "lang": "EN",
      "text": "Account Balance"
    },
    {
      "lang": "RU",
      "text": "Баланс счета"
    },
    {
      "lang": "UZ",
      "text": "Hisob balansi"
    }
  ]
}

[!warning] Validation Rules
id must be null (auto-generated)
name, recipient, and labels are required
name max length is 128 characters
At least one label translation required

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/response-fields/1

{
  "id": 1,
  "name": "account_balance",
  "visibility": "ALL",
  "ord": 1,
  "requestType": "CHECK",
  "type": "AMOUNT",
  "amountRatio": 100,
  "active": true,
  "recipient": {
    "id": 5,
    "shortName": "MOBILE_OPERATOR"
  },
  "labels": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Account Balance"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "Баланс счета"
    },
    {
      "id": 3,
      "lang": "UZ",
      "text": "Hisob balansi"
    }
  ]
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "detail": "A new responseField cannot already have an ID",
  "message": "error.idexists",
  "entityName": "pkbillmsResponseField",
  "errorKey": "idexists"
}

Update ResponseField

[!example] PUT /api/response-fields/{id} Updates an existing response field (full update).

Request

Headers:

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

Body:

{
  "id": 1,
  "name": "account_balance",
  "visibility": "MONITOR",
  "ord": 2,
  "requestType": "CHECK",
  "type": "AMOUNT",
  "amountRatio": 100,
  "active": true,
  "recipient": {
    "id": 5
  },
  "labels": [
    {
      "lang": "EN",
      "text": "Account Balance"
    }
  ]
}

[!warning] Validation Rules
id must match path parameter
id must not be null
ResponseField must exist in database

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "account_balance",
  "visibility": "MONITOR",
  "ord": 2,
  "requestType": "CHECK",
  "type": "AMOUNT",
  "amountRatio": 100,
  "active": true,
  "recipient": {
    "id": 5,
    "shortName": "MOBILE_OPERATOR"
  },
  "labels": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Account Balance"
    }
  ]
}

❌ Error (400 - Invalid ID):

{
  "status": 400,
  "detail": "Invalid ID",
  "message": "error.idinvalid",
  "entityName": "pkbillmsResponseField",
  "errorKey": "idinvalid"
}

❌ Error (400 - Not found):

{
  "status": 400,
  "detail": "Entity not found",
  "message": "error.idnotfound",
  "entityName": "pkbillmsResponseField",
  "errorKey": "idnotfound"
}

Partial Update

[!example] PATCH /api/response-fields/{id} Partially updates response field properties.

Request

Headers:

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

Body:

{
  "id": 1,
  "active": false,
  "visibility": "HIDDEN",
  "ord": 5
}

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "account_balance",
  "visibility": "HIDDEN",
  "ord": 5,
  "active": false,
  "requestType": "CHECK",
  "type": "AMOUNT"
}

❌ Error (404 - Not Found):

HTTP/1.1 404 Not Found

Get All ResponseFields

[!example] GET /api/response-fields Retrieves all response fields with pagination and filtering.

Request

Headers:

Authorization: Bearer {token}

Query Parameters:

Parameter

Type

Required

Description

page

Integer

❌

Page number (default: 0)

size

Integer

❌

Page size (default: 20)

sort

String

❌

Sort field and direction

unPaged

Boolean

❌

Disable pagination

Example:

GET /api/response-fields?page=0&size=10&sort=ord,asc

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 15

[
  {
    "id": 1,
    "name": "account_balance",
    "visibility": "ALL",
    "ord": 1,
    "requestType": "CHECK",
    "type": "AMOUNT",
    "amountRatio": 100,
    "active": true,
    "recipient": {
      "id": 5,
      "shortName": "MOBILE_OPERATOR"
    },
    "labels": [
      {
        "lang": "EN",
        "text": "Account Balance"
      }
    ]
  },
  {
    "id": 2,
    "name": "transaction_date",
    "visibility": "ALL",
    "ord": 2,
    "requestType": "PAY",
    "type": "DATE",
    "active": true,
    "recipient": {
      "id": 5,
      "shortName": "MOBILE_OPERATOR"
    },
    "labels": [
      {
        "lang": "EN",
        "text": "Transaction Date"
      }
    ]
  }
]

ResponseFieldCriteria - Advanced Filtering

[!abstract] JHipster Criteria Filtering ResponseFieldCriteria provides powerful filtering capabilities for querying response fields. All filter parameters support multiple operators for precise data retrieval.

Available Filter Types

String Filters:

Operator

Description

Example

equals

Exact match

name.equals=account_balance

notEquals

Not equal

name.notEquals=temp_field

in

Match any value

name.in=account_id,phone,login

notIn

Not in list

name.notIn=hidden,test

contains

Partial match

name.contains=balance

doesNotContain

Doesn't contain

name.doesNotContain=temp

specified

Field exists/null

name.specified=true

Numeric Filters (Long, Integer):

Operator

Description

Example

equals

Exact match

id.equals=5

notEquals

Not equal

amountRatio.notEquals=1

in

Match any value

id.in=1,2,3,4,5

notIn

Not in list

id.notIn=99,100

greaterThan

Greater than

ord.greaterThan=5

lessThan

Less than

ord.lessThan=10

greaterOrEqualThan

Greater or equal

amountRatio.greaterOrEqualThan=100

lessOrEqualThan

Less or equal

amountRatio.lessOrEqualThan=100

specified

Field exists/null

ord.specified=true

Boolean Filters:

Operator

Description

Example

equals

Exact match

active.equals=true

notEquals

Not equal

active.notEquals=false

specified

Field exists/null

active.specified=true

Enum Filters (Visibility, RequestType, ResponseFieldType):

Operator

Description

Example

equals

Exact match

visibility.equals=ALL

notEquals

Not equal

visibility.notEquals=HIDDEN

in

Match any value

requestType.in=CHECK,PAY,STATUS

notIn

Not in list

visibility.notIn=HIDDEN

specified

Field exists/null

requestType.specified=true

ResponseFieldCriteria Parameters

public class ResponseFieldCriteria implements Serializable, Criteria {
    private LongFilter id;
    private StringFilter name;
    private VisibilityFilter visibility;
    private IntegerFilter ord;
    private RequestTypeFilter requestType;
    private ResponseFieldTypeFilter type;
    private IntegerFilter amountRatio;
    private BooleanFilter active;
    private LongFilter recipientId;        // Filter by recipient
    private LongFilter labelId;            // Filter by label I18n
}

Common Query Examples

Filter by Recipient:

GET /api/response-fields?recipientId.equals=5

Filter by Request Type:

GET /api/response-fields?requestType.equals=PAY&recipientId.equals=5

Filter Active Fields:

GET /api/response-fields?active.equals=true&recipientId.equals=5

Filter by Visibility:

GET /api/response-fields?visibility.equals=ALL&active.equals=true

Filter by Type:

GET /api/response-fields?type.equals=AMOUNT&requestType.equals=CHECK

Search by Name:

GET /api/response-fields?name.contains=balance&recipientId.equals=5

Filter Amount Ratio:

GET /api/response-fields?amountRatio.equals=100&type.equals=AMOUNT

Complex Filter (AND operation):

GET /api/response-fields?recipientId.equals=5&requestType.in=CHECK,PAY&active.equals=true&visibility.equals=ALL&sort=ord,asc

Combining Filters

[!tip] Multiple Criteria All criteria are combined with AND logic. Use .in operator for OR logic on same field.

Example:

# AND: Recipient=5 AND Active=true AND Visibility=ALL
GET /api/response-fields?recipientId.equals=5&active.equals=true&visibility.equals=ALL

# OR (same field): RequestType=CHECK OR RequestType=PAY
GET /api/response-fields?requestType.in=CHECK,PAY&recipientId.equals=5

Get Single ResponseField

[!example] GET /api/response-fields/{id} Retrieves a single response field by ID.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/response-fields/1

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "account_balance",
  "visibility": "ALL",
  "ord": 1,
  "requestType": "CHECK",
  "type": "AMOUNT",
  "amountRatio": 100,
  "active": true,
  "recipient": {
    "id": 5,
    "shortName": "MOBILE_OPERATOR",
    "gateway": {
      "id": 1,
      "name": "GATEWAY_1"
    }
  },
  "labels": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Account Balance"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "Баланс счета"
    },
    {
      "id": 3,
      "lang": "UZ",
      "text": "Hisob balansi"
    }
  ]
}

❌ Error (404 - Not found):

HTTP/1.1 404 Not Found

Count ResponseFields

[!example] GET /api/response-fields/count Counts response fields matching criteria.

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Any ResponseFieldCriteria filters.

Example:

GET /api/response-fields/count?recipientId.equals=5&active.equals=true

Response

✅ Success (200 OK):

Delete ResponseField

[!example] DELETE /api/response-fields/{id} Deletes a response field.

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/response-fields/1

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

Error Handling

Error Response Format

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "path": "/api/response-fields",
  "message": "error.validation",
  "entityName": "pkbillmsResponseField",
  "errorKey": "validation",
  "fieldErrors": [
    {
      "objectName": "responseFieldDTO",
      "field": "name",
      "message": "must not be null"
    }
  ]
}

HTTP Status Codes

Code

Description

When

200

Successful GET/PUT/PATCH

201

Created

Successful POST

204

No Content

Successful DELETE

400

Bad Request

Validation error

401

Unauthorized

Missing/invalid authentication

403

Forbidden

Insufficient permissions

404

Not Found

Resource doesn't exist

500

Internal Server Error

Server error

Validation Rules

Required Fields

[!check] Mandatory Fields
✅ name - Response field name
✅ recipient - Payment recipient reference
✅ labels - At least one label translation

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new responseField cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

name

@NotNull, @Size(max=128)

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

recipient

@NotNull

"must not be null"

labels

@NotNull

"must not be null"

Business Rules

[!info] Business Validation
name identifies the field in backend response (e.g., account_id, phone, balance)
visibility controls where the field is displayed (UI, printer, monitor)
requestType determines which transaction type this field belongs to
type defines data formatting (TEXT, AMOUNT, DATE)
amountRatio specifies amount division: 1 for sum, 100 for tiyin (cents)
active flag enables/disables the field in responses
ord determines display order in UI
labels must include at least one language translation

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/response-fields \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "account_balance",
    "visibility": "ALL",
    "ord": 1,
    "requestType": "CHECK",
    "type": "AMOUNT",
    "amountRatio": 100,
    "active": true,
    "recipient": {"id": 5},
    "labels": [
      {"lang": "EN", "text": "Account Balance"},
      {"lang": "RU", "text": "Баланс счета"},
      {"lang": "UZ", "text": "Hisob balansi"}
    ]
  }'

Update

curl -X PUT http://localhost:8080/api/response-fields/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "account_balance",
    "visibility": "MONITOR",
    "ord": 2,
    "requestType": "CHECK",
    "type": "AMOUNT",
    "amountRatio": 100,
    "active": true,
    "recipient": {"id": 5},
    "labels": [{"lang": "EN", "text": "Account Balance"}]
  }'

Partial Update

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

Get All

curl -X GET "http://localhost:8080/api/response-fields?page=0&size=10&sort=ord,asc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Criteria

curl -X GET "http://localhost:8080/api/response-fields?recipientId.equals=5&active.equals=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

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

Count

curl -X GET "http://localhost:8080/api/response-fields/count?recipientId.equals=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

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

📝 Notes

[!tip] Best Practices
Set appropriate visibility for each field based on requirements
Use HIDDEN for system fields not meant for user display
Set amountRatio to 100 for tiyin/cents, 1 for sum/dollars
Always provide translations for all supported languages
Use meaningful name values that match backend response keys
Set proper ord values for consistent display order
Use requestType to organize fields by transaction type

[!warning] Important
name must match the field name in backend service responses
Deleting response fields may affect transaction display
amountRatio is critical for proper amount formatting
Inactive fields (active=false) will not appear in responses
HIDDEN visibility still stores data but hides from UI

📊 Amount Ratio Explained

[!info] Amount Ratio Usage The amountRatio field determines how amounts are divided:
amountRatio = 1:
Amount is in major currency unit (sum, dollar, euro)
Example: 50000 = 50,000 sum
amountRatio = 100:
Amount is in minor currency unit (tiyin, cents)
Example: 5000000 = 50,000.00 sum (5,000,000 tiyin ÷ 100)
Common Use:
{
  "type": "AMOUNT",
  "amountRatio": 100,  // For precise cent/tiyin calculations
  "name": "total_amount"
}

PreviousField value NextAgent

Last updated 1 month ago

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagResponseField Specifications

hashtagVisibility Enum

hashtagRequestType Enum

hashtagResponseFieldType Enum

hashtagAPI Endpoints

hashtagCreate ResponseField

hashtagRequest

hashtagResponse

hashtagUpdate ResponseField

hashtagRequest

hashtagResponse

hashtagPartial Update

hashtagRequest

hashtagResponse

hashtagGet All ResponseFields

hashtagRequest

hashtagResponse

hashtagResponseFieldCriteria - Advanced Filtering

hashtagAvailable Filter Types

hashtagResponseFieldCriteria Parameters

hashtagCommon Query Examples

hashtagCombining Filters

hashtagGet Single ResponseField

hashtagRequest

hashtagResponse

hashtagCount ResponseFields

hashtagRequest

hashtagResponse

hashtagDelete ResponseField

hashtagRequest

hashtagResponse

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Rules

hashtagRequired Fields

hashtagField Constraints

hashtagBusiness Rules

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet by Criteria

hashtagGet Single

hashtagCount

hashtagDelete

hashtag📝 Notes

hashtag📊 Amount Ratio Explained

📋 Table of Contents

Quick Reference

Endpoints Summary

Data Models

ResponseField Specifications

Visibility Enum

RequestType Enum

ResponseFieldType Enum

API Endpoints

Create ResponseField

Request

Response

Update ResponseField

Request

Response

Partial Update

Request

Response

Get All ResponseFields

Request

Response

ResponseFieldCriteria - Advanced Filtering

Available Filter Types

ResponseFieldCriteria Parameters

Common Query Examples

Combining Filters

Get Single ResponseField

Request

Response

Count ResponseFields

Request

Response

Delete ResponseField

Request

Response

Error Handling

Error Response Format

HTTP Status Codes

Validation Rules

Required Fields

Field Constraints

Business Rules

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get by Criteria

Get Single

Count

Delete

📝 Notes

📊 Amount Ratio Explained