Gateway

Gateway API - Complete Documentation

[!info] Overview The Gateway REST API provides comprehensive CRUD operations for managing payment gateway entities in the pkbillms billing system. Built on JHipster framework.

📋 Table of Contents

Quick Reference

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

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/gateways

Create new gateway

201

PUT

/api/gateways/{id}

Full update

200

PATCH

/api/gateways/{id}

Partial update

200

GET

/api/gateways

Get all (paginated)

200

GET

/api/gateways/{id}

Get by ID

200

GET

/api/gateways/count

Count by criteria

200

DELETE

/api/gateways/{id}

Delete gateway

204

Data Models

Gateway DTO Structure

[!note] Data Transfer Object Used for API requests and responses. Includes audit fields automatically.

public class GatewayDTO extends AbstractAuditingDTO {
    private Long id;
    private String name;              // Gateway name
    private String org;               // Organization
    private Boolean active;           // Status flag
    private String mfo;               // Bank MFO/BIN
    private Long taxnr;               // Tax ID (INN)
    private String ban;               // Bank account
    private String contract;          // Contract number
    private String springBeanName;    // Bean reference
}

Field Specifications

Field

Type

Required

Max

DB Column

Description

id

Long

❌ Auto

Primary key (sequence)

name

String

✅

name

Gateway display name

org

String

✅

org

Organization name

active

Boolean

✅

active

Active/Inactive

mfo

String

✅

mfo

Bank MFO (BIN) code

taxnr

Long

❌

taxnr

Tax ID (INN)

ban

String

✅

ban

Bank account number

contract

String

✅

contract

Contract reference

springBeanName

String

❌

128

spring_bean_name

Spring Bean ID

Audit Fields (Auto-populated)

[!success] Inherited from AbstractAuditingDTO These fields are automatically managed by the system.

Field

Type

Description

createdBy

String

Username who created

createdDate

Instant

Creation timestamp

lastModifiedBy

String

Last modifier

lastModifiedDate

Instant

Last modification

API Endpoints

Create Gateway

POST /api/gateways
Creates a new payment gateway entity.

Request

Headers:

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

Body:

{
  "name": "Payme Gateway",
  "org": "Payme LLC",
  "active": true,
  "mfo": "00876",
  "taxnr": 305678901,
  "ban": "20208000123456789012",
  "contract": "PAY-2024-001",
  "springBeanName": "paymeGatewayService"
}

[!warning] Validation Rules
id must be null (auto-generated)
All required fields must be provided
String lengths must not exceed limits
@Valid annotation enforces validation

Response

✅ Success (201 Created):

{
  "id": 1,
  "name": "Payme Gateway",
  "org": "Payme LLC",
  "active": true,
  "mfo": "00876",
  "taxnr": 305678901,
  "ban": "20208000123456789012",
  "contract": "PAY-2024-001",
  "springBeanName": "paymeGatewayService",
  "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 gateway cannot already have an ID",
  "message": "error.idexists"
}

Update Gateway

[!example] PUT /api/gateways/{id} Completely updates an existing gateway. All fields required.

Path Parameters

id (Long) - Gateway identifier

Request

Headers:

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

Body:

{
  "id": 1,
  "name": "Updated Payme Gateway",
  "org": "Payme Updated LLC",
  "active": false,
  "mfo": "00999",
  "taxnr": 999888777,
  "ban": "20208000999888777666",
  "contract": "PAY-2024-002",
  "springBeanName": "updatedPaymeService"
}

[!warning] Validation
Body id must not be null
Path id must match body id
Gateway must exist in database
All required fields must be provided

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Updated Payme Gateway",
  "org": "Payme Updated LLC",
  "active": false,
  "mfo": "00999",
  "taxnr": 999888777,
  "ban": "20208000999888777666",
  "contract": "PAY-2024-002",
  "springBeanName": "updatedPaymeService",
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "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/gateways/{id} Updates only specified fields. Null fields are ignored.

Path Parameters

id (Long) - Gateway identifier

Request

Headers:

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

Body (Example - update name and status only):

{
  "id": 1,
  "name": "Partially Updated Gateway",
  "active": true
}

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

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Partially Updated Gateway",
  "org": "Payme Updated LLC",
  "active": true,
  "mfo": "00999",
  "taxnr": 999888777,
  "ban": "20208000999888777666",
  "contract": "PAY-2024-002",
  "springBeanName": "updatedPaymeService",
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T15:45:00Z"
}

Get All Gateways

[!example] GET /api/gateways Retrieves paginated list with optional filtering.

Query Parameters

Pagination:

page - Page number (0-indexed, default: 0)
size - Items per page (default: 20, max: 100)
sort - Sort criteria (e.g., name,asc)

Filters (GatewayCriteria):

id.equals, id.in
name.contains, name.equals
org.contains, org.equals
active.equals
mfo.equals
taxnr.equals
ban.contains
contract.contains

Example Requests

GET /api/gateways?page=0&size=10&sort=name,asc
GET /api/gateways?active.equals=true
GET /api/gateways?org.contains=Payme&active.equals=true
GET /api/gateways?id.in=1,2,3

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "name": "Payme Gateway",
    "org": "Payme LLC",
    "active": true,
    "mfo": "00876",
    "taxnr": 305678901,
    "ban": "20208000123456789012",
    "contract": "PAY-2024-001",
    "springBeanName": "paymeGatewayService",
    "createdBy": "admin",
    "createdDate": "2024-01-29T10:30:00Z",
    "lastModifiedBy": "admin",
    "lastModifiedDate": "2024-01-29T10:30:00Z"
  },
  {
    "id": 2,
    "name": "Click Gateway",
    "org": "Click LLC",
    "active": true,
    "mfo": "00123",
    "taxnr": 201234567,
    "ban": "20208000987654321098",
    "contract": "CLK-2024-003",
    "springBeanName": "clickGatewayService",
    "createdBy": "admin",
    "createdDate": "2024-01-29T11:00:00Z",
    "lastModifiedBy": "admin",
    "lastModifiedDate": "2024-01-29T11:00:00Z"
  }
]

[!info] Response Headers
X-Total-Count - Total matching records
Link - Pagination links (RFC 5988)

Get Single Gateway

[!example] GET /api/gateways/{id} Retrieves a single gateway by ID.

Path Parameters

id (Long) - Gateway identifier

Request

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

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "Payme Gateway",
  "org": "Payme LLC",
  "active": true,
  "mfo": "00876",
  "taxnr": 305678901,
  "ban": "20208000123456789012",
  "contract": "PAY-2024-001",
  "springBeanName": "paymeGatewayService",
  "createdBy": "admin",
  "createdDate": "2024-01-29T10:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2024-01-29T10:30:00Z"
}

❌ Error (404 Not Found):

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

Count Gateways

[!example] GET /api/gateways/count Returns count of gateways matching criteria.

Query Parameters

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

Example Requests

GET /api/gateways/count
GET /api/gateways/count?active.equals=true
GET /api/gateways/count?org.contains=Bank

Response

✅ Success (200 OK):

Delete Gateway

[!example] DELETE /api/gateways/{id} Deletes a gateway by ID.

Path Parameters

id (Long) - Gateway identifier

Request

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

Response

✅ Success (204 No Content):

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

[!danger] Cascade Delete Warning Deletion may fail (500) if gateway has dependent relationships (e.g., Deposit).

Examples

Example 1: Create New Gateway

[!example]- Create Uzcard Gateway Request:

curl -X POST http://localhost:8080/api/gateways \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "name": "Uzcard Gateway",
    "org": "Uzcard NSPK",
    "active": true,
    "mfo": "00422",
    "taxnr": 200123456,
    "ban": "20208000422111222333",
    "contract": "UZC-2024-100",
    "springBeanName": "uzcardGatewayProcessor"
  }'

Response:

{
  "id": 15,
  "name": "Uzcard Gateway",
  "org": "Uzcard NSPK",
  "active": true,
  "mfo": "00422",
  "taxnr": 200123456,
  "ban": "20208000422111222333",
  "contract": "UZC-2024-100",
  "springBeanName": "uzcardGatewayProcessor",
  "createdBy": "systemadmin",
  "createdDate": "2024-01-29T16:20:35.124Z",
  "lastModifiedBy": "systemadmin",
  "lastModifiedDate": "2024-01-29T16:20:35.124Z"
}

Example 2: Toggle Gateway Status

[!example]- Deactivate Gateway Request:

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

Response:

{
  "id": 15,
  "name": "Uzcard Gateway",
  "org": "Uzcard NSPK",
  "active": false,
  "mfo": "00422",
  "taxnr": 200123456,
  "ban": "20208000422111222333",
  "contract": "UZC-2024-100",
  "springBeanName": "uzcardGatewayProcessor",
  "lastModifiedDate": "2024-01-29T17:30:12.456Z"
}

Example 3: Search Active Bank Gateways

[!example]- Filter by Organization and Status Request:

curl -X GET "http://localhost:8080/api/gateways?\
org.contains=Bank&\
active.equals=true&\
page=0&\
size=5&\
sort=name,asc" \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": 8,
    "name": "Agrobank Gateway",
    "org": "Agrobank",
    "active": true,
    "mfo": "00811",
    "ban": "20208000811223344556",
    "contract": "AGRO-2024-05"
  },
  {
    "id": 3,
    "name": "NBU Gateway",
    "org": "National Bank",
    "active": true,
    "mfo": "00001",
    "ban": "20208000001000000001",
    "contract": "NBU-2024-MAIN"
  }
]

Error Handling

Error Response Format

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

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

HTTP Status Codes

Code

Type

Description

Common Causes

400

Bad Request

Invalid request

Validation failure, ID mismatch

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 entry, constraints

500

Server Error

Internal error

Database error, exception

Validation Error Example

[!bug] Field Validation Errors Multiple field errors returned in single response.

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

Business Logic Errors

[!bug]- ID Already Exists (POST)

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

[!bug]- Entity Not Found (PUT/PATCH/DELETE)
{
  "status": 400,
  "detail": "Entity not found",
  "message": "error.idnotfound"
}

[!bug]- ID Mismatch (PUT/PATCH)

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

Validation Rules

Field-Level Validation

Field

Rules

Error Messages

id

Null for POST

"A new gateway cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

id

Must match path

"Invalid ID"

name

@NotNull, @Size(max=64)

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

org

@NotNull, @Size(max=32)

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

active

@NotNull

"must not be null"

mfo

@NotNull, @Size(max=8)

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

taxnr

Optional

ban

@NotNull, @Size(max=32)

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

contract

@NotNull, @Size(max=64)

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

springBeanName

@Size(max=128)

"size must be between 0 and 128"

Entity-Level Validation

[!check] Validation Checklist
✅ Gateway must exist before update/patch/delete
✅ Path ID must match body ID
✅ All @NotNull fields required for POST/PUT
✅ PATCH only validates non-null fields

Pagination & Filtering

Pagination Parameters

[!tip] Standard Parameters
page - Zero-based index (default: 0)
size - Records per page (default: 20, max: 100)
sort - Format: property,direction

Examples:

?page=0&size=10
?page=2&size=25&sort=name,asc
?sort=id,desc&sort=createdDate,desc

Filtering with Criteria API

[!abstract] Comparison Operators Advanced filtering through dynamic criteria.

Operator

Description

Example

equals

Exact match

active.equals=true

notEquals

Not equal

active.notEquals=false

in

In list

id.in=1,2,3

notIn

Not in list

id.notIn=4,5,6

specified

Null check

taxnr.specified=true

greaterThan

GT (numeric/date)

id.greaterThan=10

lessThan

LT (numeric/date)

id.lessThan=100

contains

String contains

name.contains=Gateway

Filter Examples

[!example]- Common Filter Patterns
Active gateways:
?active.equals=true
Specific MFO:
?mfo.equals=00876
Multiple organizations:
?org.in=Payme LLC,Click LLC,Uzcard NSPK
With tax number:
?taxnr.specified=true
Name pattern:
?name.contains=Gateway
Complex filter:
?active.equals=true&org.contains=Bank&mfo.specified=true&sort=name,asc

Response Headers

[!info] Pagination Headers
X-Total-Count - Total number of records
Link - Navigation links (RFC 5988)

Example Link Header:

Link: </api/gateways?page=0&size=20>; rel="first",
      </api/gateways?page=1&size=20>; rel="prev",
      </api/gateways?page=3&size=20>; rel="next",
      </api/gateways?page=9&size=20>; rel="last"

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/gateways \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Test Gateway",
    "org": "Test Org",
    "active": true,
    "mfo": "00999",
    "taxnr": 123456789,
    "ban": "20208000123456789012",
    "contract": "TEST-001"
  }'

Update

curl -X PUT http://localhost:8080/api/gateways/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "Updated Gateway",
    "org": "Updated Org",
    "active": false,
    "mfo": "00888",
    "ban": "20208000987654321098",
    "contract": "UPD-002"
  }'

Partial Update

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

Get All

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

Get Single

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

Count

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

Delete

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

FieldValue API - Complete Documentation

[!info] Overview The FieldValue REST API manages predefined values and options for dynamic form fields in the pkbillms billing system. FieldValues define selectable options, pricing information, and filtering logic for field configurations with multilingual support.

📋 Table of Contents

[[#Quick Reference|Quick Reference]]
[[#Data Models|Data Models]]
[[#API Endpoints|API Endpoints]]
- [[#Create FieldValue|Create FieldValue]]
- [[#Update FieldValue|Update FieldValue]]
- [[#Partial Update|Partial Update]]
- [[#Get All FieldValues|Get All FieldValues]]
- [[#Get FieldValues by Criteria|Get FieldValues by Criteria]]
- [[#Get FieldValues V2|Get FieldValues V2]]
- [[#Get Single FieldValue|Get Single FieldValue]]
- [[#Count FieldValues|Count FieldValues]]
- [[#Delete FieldValue|Delete FieldValue]]
- [[#Cascaded Delete|Cascaded Delete FieldValue]]
[[#Examples|Request & Response Examples]]
[[#Error Handling|Error Handling]]
[[#Validation Rules|Validation Rules]]

Quick Reference

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

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/field-values

Create new field value

201

PUT

/api/field-values/{id}

Full update

200

PATCH

/api/field-values/{id}

Partial update

200

GET

/api/field-values

Get all with pagination

200

GET

/api/field-values/get

Get all (alternative)

200

GET

/api/field-values/criteria

Get by criteria + field

200

GET

/api/v2/field-values

Get V2 projection

200

GET

/api/field-values/{id}

Get by ID

200

GET

/api/field-values/count

Count by criteria

200

DELETE

/api/field-values/{id}

Delete field value

204

DELETE

/api/field-values/cascaded/{id}

Cascaded delete

200

Data Models

FieldValue Specifications

Field

Type

Required

Max/Range

Description

id

Long

❌ Auto

Primary key

value

String

✅

Param value to send to server

amount

Long

❌

Price of selected value

filterBy

String

❌

Filter by parent field

ord

Integer

❌

Display order

checkId

String

❌

Check identifier

field

FieldDTO

✅

Parent field reference

titles

Set

✅

Multilingual titles

descriptions

Set

❌

Multilingual descriptions

API Endpoints

Create FieldValue

[!example] POST /api/field-values Creates a new field value option.

Request

Headers:

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

Body:

{
  "value": "50000",
  "amount": 50000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5
  },
  "titles": [
    {
      "lang": "EN",
      "text": "50,000 UZS"
    },
    {
      "lang": "RU",
      "text": "50 000 сум"
    },
    {
      "lang": "UZ",
      "text": "50 000 so'm"
    }
  ],
  "descriptions": [
    {
      "lang": "EN",
      "text": "Standard package"
    }
  ]
}

[!warning] Validation Rules
id must be null (auto-generated)
value and field are required
value max length is 64 characters
filterBy max length is 16 characters

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/field-values/1

{
  "id": 1,
  "value": "50000",
  "amount": 50000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5,
    "name": "amount",
    "type": "AMOUNT"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "50,000 UZS"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "50 000 сум"
    },
    {
      "id": 3,
      "lang": "UZ",
      "text": "50 000 so'm"
    }
  ],
  "descriptions": [
    {
      "id": 4,
      "lang": "EN",
      "text": "Standard package"
    }
  ]
}

❌ Error (400 - ID exists):

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

Update FieldValue

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

Request

Headers:

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

Body:

{
  "id": 1,
  "value": "50000",
  "amount": 55000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5
  },
  "titles": [
    {
      "lang": "EN",
      "text": "55,000 UZS"
    }
  ]
}

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

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "value": "50000",
  "amount": 55000,
  "filterBy": "mobile",
  "ord": 1,
  "field": {
    "id": 5,
    "name": "amount"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "55,000 UZS"
    }
  ]
}

❌ Error (400 - Invalid ID):

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

❌ Error (400 - Not found):

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

Partial Update

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

Request

Headers:

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

Body:

{
  "id": 1,
  "amount": 60000,
  "ord": 2
}

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "value": "50000",
  "amount": 60000,
  "ord": 2,
  "field": {
    "id": 5
  }
}

❌ Error (404 - Not Found):

HTTP/1.1 404 Not Found

Get All FieldValues

[!example] GET /api/field-values Retrieves all field values 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/field-values?page=0&size=10&sort=ord,asc

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "value": "50000",
    "amount": 50000,
    "ord": 1,
    "field": {
      "id": 5,
      "name": "amount"
    },
    "titles": [
      {
        "lang": "EN",
        "text": "50,000 UZS"
      }
    ]
  },
  {
    "id": 2,
    "value": "100000",
    "amount": 100000,
    "ord": 2,
    "field": {
      "id": 5,
      "name": "amount"
    },
    "titles": [
      {
        "lang": "EN",
        "text": "100,000 UZS"
      }
    ]
  }
]

Get All FieldValues (Alternative)

[!example] GET /api/field-values/get Alternative endpoint for retrieving field values.

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Same as main GET endpoint plus FieldValueCriteria filters.

Example:

GET /api/field-values/get?fieldId.equals=5&page=0&size=10

Response

✅ Success (200 OK): Same format as main GET endpoint.

FieldValueCriteria - Advanced Filtering

[!abstract] JHipster Criteria Filtering FieldValueCriteria provides powerful filtering capabilities for querying field values. All filter parameters support multiple operators for precise data retrieval.

Available Filter Types

String Filters:

Operator

Description

Example

equals

Exact match

value.equals=50000

notEquals

Not equal

value.notEquals=100000

in

Match any value

value.in=50000,100000,150000

notIn

Not in list

value.notIn=0,5000

contains

Partial match

value.contains=000

doesNotContain

Doesn't contain

filterBy.doesNotContain=test

specified

Field exists/null

filterBy.specified=true

Numeric Filters (Long, Integer):

Operator

Description

Example

equals

Exact match

amount.equals=50000

notEquals

Not equal

amount.notEquals=0

in

Match any value

amount.in=50000,100000

notIn

Not in list

amount.notIn=0

greaterThan

Greater than

amount.greaterThan=50000

lessThan

Less than

amount.lessThan=100000

greaterOrEqualThan

Greater or equal

amount.greaterOrEqualThan=50000

lessOrEqualThan

Less or equal

amount.lessOrEqualThan=100000

specified

Field exists/null

amount.specified=true

Get FieldValues by Criteria

[!example] GET /api/field-values/criteria Retrieves field values filtered by field name and criteria.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/field-values/criteria?fieldName=amount&amount.greaterThan=50000&sort=ord,asc

Response

✅ Success (200 OK):

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

[
  {
    "id": 2,
    "value": "100000",
    "amount": 100000,
    "ord": 2,
    "field": {
      "id": 5,
      "name": "amount"
    }
  },
  {
    "id": 3,
    "value": "150000",
    "amount": 150000,
    "ord": 3,
    "field": {
      "id": 5,
      "name": "amount"
    }
  }
]

FieldValueCriteria Parameters

public class FieldValueCriteria implements Serializable, Criteria {
    private LongFilter id;
    private StringFilter value;
    private LongFilter amount;
    private StringFilter filterBy;
    private StringFilter checkId;
    private IntegerFilter ord;
    private LongFilter fieldId;           // Filter by parent field
    private LongFilter titleId;           // Filter by title I18n
    private LongFilter descriptionId;     // Filter by description I18n
}

Common Query Examples

Filter by Field:

GET /api/field-values?fieldId.equals=5

Filter by Amount Range:

GET /api/field-values?amount.greaterThan=50000&amount.lessThan=200000

Filter with filterBy:

GET /api/field-values?filterBy.equals=mobile&fieldId.equals=5

Search by Value:

GET /api/field-values?value.contains=000&fieldId.equals=5

Values with Amount:

GET /api/field-values?amount.specified=true&fieldId.equals=5

Sorted by Display Order:

GET /api/field-values?fieldId.equals=5&sort=ord,asc

Complex Filter (AND operation):

GET /api/field-values?fieldId.equals=5&amount.greaterThan=50000&filterBy.equals=mobile&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: Field=5 AND Amount>50000
GET /api/field-values?fieldId.equals=5&amount.greaterThan=50000

# OR (same field): Value=50000 OR Value=100000
GET /api/field-values?value.in=50000,100000&fieldId.equals=5

Get FieldValues V2

[!example] GET /api/v2/field-values Retrieves field values using V2 projection (optimized response).

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Same as standard criteria endpoint.

Example:

GET /api/v2/field-values?fieldId.equals=5&page=0&size=10

Response

✅ Success (200 OK):

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

[
  {
    "id": 1,
    "value": "50000",
    "amount": 50000,
    "ord": 1,
    "fieldId": 5
  },
  {
    "id": 2,
    "value": "100000",
    "amount": 100000,
    "ord": 2,
    "fieldId": 5
  }
]

[!info] V2 Projection V2 endpoint returns a lighter projection without nested objects for better performance.

Get Single FieldValue

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

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/field-values/1

Response

✅ Success (200 OK):

{
  "id": 1,
  "value": "50000",
  "amount": 50000,
  "filterBy": "mobile",
  "ord": 1,
  "checkId": "CHK001",
  "field": {
    "id": 5,
    "name": "amount",
    "type": "AMOUNT",
    "controlType": "SELECT"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "50,000 UZS"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "50 000 сум"
    }
  ],
  "descriptions": [
    {
      "id": 3,
      "lang": "EN",
      "text": "Standard package"
    }
  ]
}

❌ Error (404 - Not found):

HTTP/1.1 404 Not Found

Count FieldValues

[!example] GET /api/field-values/count Counts field values matching criteria.

Request

Headers:

Authorization: Bearer {token}

Query Parameters: Any FieldValueCriteria filters.

Example:

GET /api/field-values/count?fieldId.equals=5&amount.greaterThan=50000

Response

✅ Success (200 OK):

Delete FieldValue

[!example] DELETE /api/field-values/{id} Deletes a field value.

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/field-values/1

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

Cascaded Delete FieldValue

[!example] DELETE /api/field-values/cascaded/{id} Deletes a field value with all related entities (I18n translations).

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/field-values/cascaded/1

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

Error Handling

Error Response Format

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "path": "/api/field-values",
  "message": "error.validation",
  "entityName": "pkbillmsFieldValue",
  "errorKey": "validation",
  "fieldErrors": [
    {
      "objectName": "fieldValueDTO",
      "field": "value",
      "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
✅ value - Value to send to server
✅ field - Parent field reference
✅ titles - At least one title (I18n)

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new fieldValue cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

value

@NotNull, @Size(max=64)

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

filterBy

@Size(max=16)

"size must be between 0 and 16"

field

@NotNull

"must not be null"

titles

@NotNull

"must not be null"

Business Rules

[!info] Business Validation
value is used as the parameter sent to backend services
amount represents pricing information for the selected value
filterBy enables dependent dropdown filtering (parent-child relationships)
ord determines display order in UI select elements
checkId is used for validation and reconciliation processes
titles must include at least one language translation
descriptions are optional additional information

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/field-values \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "value": "50000",
    "amount": 50000,
    "filterBy": "mobile",
    "ord": 1,
    "field": {"id": 5},
    "titles": [
      {"lang": "EN", "text": "50,000 UZS"},
      {"lang": "RU", "text": "50 000 сум"},
      {"lang": "UZ", "text": "50 000 som"}
    ],
    "descriptions": [
      {"lang": "EN", "text": "Standard package"}
    ]
  }'

Update

curl -X PUT http://localhost:8080/api/field-values/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "value": "50000",
    "amount": 55000,
    "ord": 1,
    "field": {"id": 5},
    "titles": [{"lang": "EN", "text": "55,000 UZS"}]
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/field-values/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "amount": 60000, "ord": 2}'

Get All

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

Get by Criteria (with Field Name)

curl -X GET "http://localhost:8080/api/field-values/criteria?fieldName=amount&amount.greaterThan=50000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Criteria (Standard)

curl -X GET "http://localhost:8080/api/field-values?fieldId.equals=5&amount.greaterThan=50000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get V2

curl -X GET "http://localhost:8080/api/v2/field-values?fieldId.equals=5&page=0&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

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

Count

curl -X GET "http://localhost:8080/api/field-values/count?fieldId.equals=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

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

Cascaded Delete

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

📝 Notes

[!tip] Best Practices
Always provide meaningful ord values for proper sorting
Use filterBy for cascading dropdown dependencies
Include translations for all supported languages
Set appropriate amount values for pricing information
Use checkId for validation and reconciliation tracking

[!warning] Important
Deleting field values may affect active payment forms
Use cascaded delete carefully as it removes all I18n data
value field is sent to backend services - ensure proper validation
V2 endpoint provides better performance for large datasets

PreviousAgent-Recipient NextRecipient

Last updated 1 month ago

hashtagGateway API - Complete Documentation

hashtag📋 Table of Contents

hashtagTable of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagGateway DTO Structure

hashtagField Specifications

hashtagAudit Fields (Auto-populated)

hashtagAPI Endpoints

hashtagCreate Gateway

hashtagUpdate Gateway

hashtagPartial Update

hashtagGet All Gateways

hashtagGet Single Gateway

hashtagCount Gateways

hashtagDelete Gateway

hashtagExamples

hashtagExample 1: Create New Gateway

hashtagExample 2: Toggle Gateway Status

hashtagExample 3: Search Active Bank Gateways

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Error Example

hashtagBusiness Logic Errors

hashtagValidation Rules

hashtagField-Level Validation

hashtagEntity-Level Validation

hashtagPagination & Filtering

hashtagPagination Parameters

hashtagFiltering with Criteria API

hashtagFilter Examples

hashtagResponse Headers

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet Single

hashtagCount

hashtagDelete

hashtagFieldValue API - Complete Documentation

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagFieldValue Specifications

hashtagAPI Endpoints

hashtagCreate FieldValue

hashtagUpdate FieldValue

hashtagPartial Update

hashtagGet All FieldValues

hashtagGet All FieldValues (Alternative)

hashtagFieldValueCriteria - Advanced Filtering

hashtagAvailable Filter Types

hashtagGet FieldValues by Criteria

hashtagFieldValueCriteria Parameters

hashtagCommon Query Examples

hashtagCombining Filters

hashtagGet FieldValues V2

hashtagGet Single FieldValue

hashtagCount FieldValues

hashtagDelete FieldValue

hashtagCascaded Delete FieldValue

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 (with Field Name)

hashtagGet by Criteria (Standard)

hashtagGet V2

Gateway API - Complete Documentation

📋 Table of Contents

Table of Contents

Quick Reference

Endpoints Summary

Data Models

Gateway DTO Structure

Field Specifications

Audit Fields (Auto-populated)

API Endpoints

Create Gateway

Update Gateway

Partial Update

Get All Gateways

Get Single Gateway

Count Gateways

Delete Gateway

Examples

Example 1: Create New Gateway

Example 2: Toggle Gateway Status

Example 3: Search Active Bank Gateways

Error Handling

Error Response Format

HTTP Status Codes

Validation Error Example

Business Logic Errors

Validation Rules

Field-Level Validation

Entity-Level Validation

Pagination & Filtering

Pagination Parameters

Filtering with Criteria API

Filter Examples

Response Headers

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get Single

Count

Delete

FieldValue API - Complete Documentation

📋 Table of Contents

Quick Reference

Endpoints Summary

Data Models

FieldValue Specifications

API Endpoints

Create FieldValue

Update FieldValue

Partial Update

Get All FieldValues

Get All FieldValues (Alternative)

FieldValueCriteria - Advanced Filtering

Available Filter Types

Get FieldValues by Criteria

FieldValueCriteria Parameters

Common Query Examples

Combining Filters

Get FieldValues V2

Get Single FieldValue

Count FieldValues

Delete FieldValue

Cascaded Delete FieldValue

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 (with Field Name)

Get by Criteria (Standard)

Get V2