Search and Filter Terminals — API
Searches and filters terminals using the required pageProperties and searchCriteria query objects. Returns terminal search results in a paginated format with page metadata and sorting information. Accessible to SUPER_ADMIN, PARTNER, and MERCHANT roles using API Key authentication through the X-API-KEY header. Confirm query-object serialization through Swagger's Try it out feature before integration.
1. Overview
The Search and Filter Terminals API retrieves terminal records based on the supplied search criteria and returns the results in a paginated format. It supports text-based searches and terminal identifier (trsm) searches, along with configurable pagination.
Access Levels: SUPER_ADMIN, PARTNER, MERCHANT
2. Endpoint Details
| Property | Value |
|---|---|
| API Name | Search and Filter Terminals |
| HTTP Method | GET |
| Endpoint | /api/v1/tms/terminals/search |
| Access Levels | SUPER_ADMIN, PARTNER, MERCHANT |
| Request Parameters | pageProperties, searchCriteria |
| Request Body | None |
| Success Response | 200 OK |
| Error Response | 400 Bad Request |
3. Base URL
Production
https://app-api.edfapay.comFull Endpoint
GET https://app-api.edfapay.com/api/v1/tms/terminals/search4. Authorization
This endpoint is available to the following access levels:
SUPER_ADMINPARTNERMERCHANT
Authentication uses an API key supplied through the X-API-KEY request header.
5. Query Parameters
The provided Swagger definition marks both query objects as required.
5.1 pageProperties
pagePropertiesDefines pagination settings for the terminal search results.
Example object:
{
"pageNumber": 0,
"pageSize": 10
}| Field | Type | Description |
|---|---|---|
pageNumber | Integer | Page number to retrieve. The example uses 0 for the first page. |
pageSize | Integer | Number of records requested per page. |
5.2 searchCriteria
searchCriteriaDefines the criteria used to search for terminals.
Example object:
{
"text": "Samsung",
"trsm": "4E0001"
}| Field | Type | Description |
|---|---|---|
text | String | General text search. The Swagger example uses Samsung. |
trsm | String | Terminal identifier or TRSM value to search for. |
The provided schema shows these example fields but does not establish the complete set of supported search criteria.
5.3 Query Serialization
Although Swagger represents pageProperties and searchCriteria as query objects, the exact serialization format required by the server is not established by the provided definition.
Use Swagger's Try it out feature to inspect the generated request URL and confirm how both objects must be encoded.
6. Request Headers
| Header | Value | Description |
|---|---|---|
X-API-KEY | YOUR_API_KEY | Authenticates the API request. |
Accept | */* | Specifies the response media types accepted by the client. |
No JSON request body is defined for this endpoint.
7. cURL Example
The following is a base request example. Add the required query parameters using the serialization format confirmed through Swagger.
curl --request GET \
--url 'https://app-api.edfapay.com/api/v1/tms/terminals/search' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'Accept: */*'Before execution:
- Replace
YOUR_API_KEYwith a valid API key. - Include both required query objects in the format accepted by the API.
- Verify the generated URL using Swagger's Try it out feature before integrating the request.
This example intentionally omits the query objects because their exact URL encoding cannot be confirmed from the supplied definition.
8. Successful Response — 200 OK
200 OKExample Response
{
"code": 0,
"message": "string",
"errorCode": "string",
"data": {
"totalPages": 0,
"totalElements": 0,
"size": 0,
"content": [
{}
],
"number": 0,
"pageable": {
"offset": 0,
"paged": true,
"pageNumber": 0,
"pageSize": 0,
"sort": [
{
"direction": "string",
"nullHandling": "string",
"ascending": true,
"property": "string",
"ignoreCase": true
}
],
"unpaged": false
},
"sort": [
{
"direction": "string",
"nullHandling": "string",
"ascending": true,
"property": "string",
"ignoreCase": true
}
],
"numberOfElements": 0,
"first": true,
"last": true,
"empty": true
}
}Note: The content item is represented as an empty object ({}) in the supplied schema. The actual terminal fields returned for each item are not visible in the provided definition.
9. Response Fields
9.1 Standard Response Envelope
| Field | Type | Description |
|---|---|---|
code | Number | API response code. |
message | String | Response message. |
errorCode | String | Error identifier, if applicable. |
data | Object | Paginated search result. |
9.2 Pagination Fields — data
data| Field | Type | Description |
|---|---|---|
totalPages | Integer | Total number of pages available. |
totalElements | Integer | Total number of matching records. |
size | Integer | Page size reported by the response. |
content | Array | Terminal records returned for the requested page. |
number | Integer | Current page number. |
pageable | Object | Pagination configuration and metadata. |
sort | Array | Sorting information for the result. |
numberOfElements | Integer | Number of records returned on the current page. |
first | Boolean | Indicates whether the current page is the first page. |
last | Boolean | Indicates whether the current page is the last page. |
empty | Boolean | Indicates whether the current page contains no records. |
9.3 data.pageable
data.pageable| Field | Type | Description |
|---|---|---|
offset | Integer | Offset of the first record for the current page. |
paged | Boolean | Indicates whether pagination is enabled. |
pageNumber | Integer | Current page number. |
pageSize | Integer | Configured page size. |
sort | Array | Sorting metadata associated with pagination. |
unpaged | Boolean | Indicates whether the results are unpaged. |
9.4 Sorting Object
Each entry in sort contains the following fields:
| Field | Type | Description |
|---|---|---|
direction | String | Sort direction. |
nullHandling | String | Null-value handling strategy. |
ascending | Boolean | Indicates whether sorting is ascending. |
property | String | Property used for sorting. |
ignoreCase | Boolean | Indicates whether case is ignored during sorting. |
The accepted values for direction and nullHandling are not specified in the supplied schema.
10. Error Response — 400 Bad Request
400 Bad RequestThe endpoint documents 400 Bad Request as a possible response.
Example Response
{
"code": 0,
"message": "string",
"errorCode": "string",
"data": {}
}| Field | Type | Description |
|---|---|---|
code | Number | API response code. |
message | String | Error or response message. |
errorCode | String | Error identifier. |
data | Object | Additional error details; empty in the documented example. |
The values shown are Swagger example placeholders, not confirmed runtime response values.
11. Integration Workflow
- Authenticate using a valid API key and an authorized
SUPER_ADMIN,PARTNER, orMERCHANTaccount. - Prepare the required
pagePropertiesobject with the desired page number and page size. - Prepare the
searchCriteriaobject with the supported search fields. - Confirm the query-object serialization using Swagger's Try it out feature.
- Submit a
GETrequest to the terminal search endpoint with both required query objects. - Inspect the response and review
totalElements,totalPages, andnumberOfElements. - Process the terminal records returned in
content. - Request additional pages as needed.
12. Error Handling and Troubleshooting
If the API returns 400 Bad Request, consider checking the following:
- Confirm that both
pagePropertiesandsearchCriteriaare included. - Verify that the query objects are serialized in the format expected by the API.
- Check the data types of
pageNumber,pageSize,text, andtrsm. - Confirm that the
X-API-KEYheader contains a valid API key. - Inspect
messageanderrorCodefor additional diagnostic information.
These are general troubleshooting recommendations. The exact query serialization rules, validation constraints, and error mappings are not specified in the supplied definition.
13. Important Considerations
- The endpoint uses the
GETmethod. - Both
pagePropertiesandsearchCriteriaare marked as required. - The endpoint uses query parameters rather than a JSON request body.
- Authentication uses the
X-API-KEYheader. - The response follows a paginated structure.
- The individual terminal record schema within
contentis not shown in the supplied definition. - The exact query-object serialization must be confirmed before production integration.
- Sorting fields are present in the response schema, but supported sorting inputs are not established by the provided definition.
Updated 25 days ago