Transaction API
Version 1.0.0
A REST API that processes transactions with transaction ID and COMMAREA data
Base URL: /api/v1
Transaction Operations
POST
/transaction
Process a transaction
Endpoint that accepts only POST requests with transaction ID and base64-encoded COMMAREA
Request Body
application/json
required
Schema: TransactionRequest
transid
required
Transaction identifier (exactly 4 characters)
Type: string (minLength: 4, maxLength: 4)
Example: "TX01"
commarea
required
Base64-encoded COMMAREA data
Type: string (format: byte)
Example: "SGVsbG8gV29ybGQ="
progId
optional
Optional program name if need to explicitly override which program needs to run under the transid. Otherwise system will lookup which program is mapped to the transid requested before execution.
Type: string (minLength: 4, maxLength: 8)
Example: "CLBTEST1"
caCodePg
optional
Optional codepage name if the commarea value is not in the ascii codepage, like ebcdic.
Type: string
Example: "IBM037"
Example Request Body
{
"transid": "TX01",
"commarea": "SGVsbG8gV29ybGQ=",
"progId": "CLBTEST1",
"caCodePg": "IBM037"
}
Responses
200
Successful transaction processing
application/json
Schema: TransactionResponse
commarea
Transaction processing results - as returned from the requested transaction. Base64-encoded COMMAREA data.
Type: object
Example Response
{
"commarea": {
...
}
}
400
Bad request - invalid input parameters
application/json
Schema: ErrorResponse
resp
Response code
Type: string
Example: "012"
resp2
Secondary response code
Type: string
Example: "324"
abcode
Abend code
Type: string
Example: "ABCD"
msg
Error message
Type: string
Example: "Invalid request parameters"
Example Error Response
{
"resp": "012",
"resp2": "324",
"abcode": "ABCD",
"msg": "Invalid request parameters"
}
500
Internal server error
application/json
Schema: ErrorResponse
Usage Notes
- The transid field must be exactly 4 characters in length
- The commarea must be base64-encoded
- Use progId to explicitly specify the program to execute, otherwise the system will look up the program mapped to the transaction ID
- Set caCodePg when COMMAREA uses a non-ASCII codepage (e.g., EBCDIC)
Schemas
TransactionRequest
object
Required: transid, commarea
transid *
Transaction identifier (exactly 4 characters)
Type: string
Constraints: minLength: 4, maxLength: 4
Example: "TX01"
commarea *
Base64-encoded COMMAREA data
Type: string
Format: byte (base64 encoded)
Example: "SGVsbG8gV29ybGQ="
progId
Optional program name if need to explicitly override which program needs to run under the transid. Otherwise system will lookup which program is mapped to the transid requested before execution.
Type: string
Constraints: minLength: 4, maxLength: 8
Example: "CLBTEST1"
caCodePg
Optional codepage name if the commarea value is not in the ascii codepage, like ebcdic.
Type: string
Example: "IBM037"
TransactionResponse
object
commarea
Transaction processing results - as returned from the requested transaction. Base64-encoded COMMAREA data.
Type: object
ErrorResponse
object
resp
Response code indicating the error type
Type: string
Example: "012"
resp2
Secondary response code providing additional error details
Type: string
Example: "324"
abcode
Abend code if transaction terminated abnormally
Type: string
Example: "ABCD"
msg
Human-readable error message describing the issue
Type: string
Example: "Invalid request parameters"
Integration Guide
Authentication
This API may require authentication. Contact your system administrator for authentication details and credentials.
Content Type
All requests must include the Content-Type: application/json header.
Base64 Encoding
The COMMAREA field must be base64-encoded. Most programming languages have built-in support for base64 encoding:
- JavaScript: btoa() and atob()
- Python: base64.b64encode() and base64.b64decode()
- Java: Base64.getEncoder() and Base64.getDecoder()
Error Handling
Always check the HTTP status code and handle error responses appropriately. Error responses include detailed information in the ErrorResponse schema to help diagnose issues.
Example Implementation
cURL
curl -X POST /api/v1/transaction \
-H "Content-Type: application/json" \
-d '{
"transid": "TX01",
"commarea": "SGVsbG8gV29ybGQ=",
"progId": "CLBTEST1",
"caCodePg": "IBM037"
}'
JavaScript (Fetch API)
fetch('/api/v1/transaction', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
transid: 'TX01',
commarea: btoa('Hello World'),
progId: 'CLBTEST1',
caCodePg: 'IBM037'
})
})
.then(response = response.json())
.then(data = console.log(data))
.catch(error = console.error('Error:', error));
Python (Requests)
import requests
import base64
url = '/api/v1/transaction'
data = {
'transid': 'TX01',
'commarea': base64.b64encode(b'Hello World').decode('utf-8'),
'progId': 'CLBTEST1',
'caCodePg': 'IBM037'
}
response = requests.post(url, json=data)
print(response.json())
Transaction API Documentation v1.0.0
For support and additional information, please contact your system administrator.
0 Comments