# API Request Protocol

## 1. Request Protocol

All API interactions must utilize **HTTPS** with strict adherence to the following technical standards:

1. **Content Handling**
  - **Content-Type**: application/json (mandatory for all requests)
  - **Character Encoding**: UTF-8 exclusively
  - **Parameter Transmission**: All parameters must be passed through the request body in JSON format
2. **Common Request Parameters (Body Content)**


Every API request must include these four essential parameters within the JSON body:

| **Parameters** | **Type** | **Description** |
|  --- | --- | --- |
| appId | long | Unique application identifier assigned by the Keeta platform to your service provider integration. This value remains constant across all API calls from your application. |
| accessToken | string | Authorization token granted through merchant OAuth 2.0 authentication. Tokens have a 90-day validity period and must be refreshed via the POST {{URL}}/api/open/base/oauth/token endpoint upon expiration. |
| timestamp | int | Unix timestamp in seconds representing the exact moment of API invocation. |
| sig | string | Cryptographic signature generated by applying the HMAC-SHA256 algorithm to the concatenated request parameters. Detailed signature calculation methodology is documented in the [Authorization Guide](/apis/standard/docs/author) |


## 2. Response Parameter

- **HTTP Status Code**: 200 (All responses return 200 for successful receipt, with actual status in code field)
- **Content-Type**: application/json (mandatory for all requests)


| **Field Name** | **Type** | **Description** |
|  --- | --- | --- |
| code | int | A numeric status identifier indicating the result of the interface call, used to determine whether the operation executed successfully. **A code value of 0** indicates that **the request was executed successfully**. **Any non-zero code value** indicates that **request execution failed**. Specific error details can be viewed in the *message* field. |
| message | string | Text description corresponding to the status code, explaining the operation result or error cause to users. |
| data | object/array | Primary carrier of business data returned upon successful API execution. Contains specific content requested by developers. |
| errorList | array | Validation error specifics. For details, please Refer to API reference section. |


#### Response Examples


```json
// Success Response
{
  "code": 0,
  "message": "success",
  "data": {}
}

// Failure Response  
{
  "code": 115000110,
  "message": "The sig calculation error, please refer to the signature calculation instructions for checking.",
  "data": {}
}

// Partial Failure Response
{
  "code": 0,
  "message": "Partial Failure", 
  "data": [],
  "errorList": []
}
```

## 3. Error Code Classification & Resolution

| **Error Code Range** | **Error Type** | **Resolution Steps** |
|  --- | --- | --- |
| **115000100～115000199** | Request Signature Errors | 1. Verify signature algorithm compliance with [Authorization Guide](/apis/standard/docs/author)2. Check Access Token validity and expiration status3. Validate parameter sorting and concatenation logic |
| **115000200～115000399** | Business Parameter Errors | 1. Cross-check parameter names and types in request body2. Validate value ranges (timestamp formats, ID validity)3. Verify mandatory field presence4. Consult endpoint-specific field definitions |
| **315000100～315000199** | Keeta Server Exceptions | Please contact Keeta Team for trouble-shooting |


## 4. IP Whitelist Configuration

To ensure reliable receipt of Keeta Webhook notifications, whitelist these IP ranges:

- 43.135.86.188
- 43.135.94.192
- 101.32.221.146
- 43.128.27.185
- 101.32.216.180
- 119.28.140.253
- 162.62.123.227
- 162.62.219.133
- 162.62.55.69
- 162.62.61.26
- 43.131.16.79
- 43.131.30.39
- 43.131.52.67
- 43.131.55.51
- 43.157.1.126
- 43.157.104.104
- 43.157.33.44
- 43.157.64.52
- 43.158.90.31
- 43.158.90.65
- 49.51.164.88
- 49.51.172.32