# Client API Documentation for Transaction Anomaly Monitoring System ## 1**. API Specifications** ### **1.1 Endpoint URL** * **API Endpoint URL**: You will provide us with a secure HTTPS endpoint where our system can send requests to retrieve transaction data. * **Example**: `https://api.yourcompany.com/stats` ### **1.2 Request Method** * **HTTP Method**: `GET` * **Content-Type**: `application/json` ### **1.3 Request Parameters** Our system will send a JSON payload containing the following parameters: | Parameter | Type | Description | Example | | ------------ | ------ | ------------------------------------------------------------- | ------------------------------------------------------------------- | | `start_time` | String | Start of the time interval in ISO 8601 format (UTC). | `"2024-09-30T10:00:00Z"` | | `end_time` | String | End of the time interval in ISO 8601 format (UTC). | `"2024-09-30T10:05:00Z"` | | `groups` | String | Comma-separated list of groups (e.g., merchants) to retrieve. |

"merchant1,merchant2"

"all"

| | `signature` | String | HMAC SHA-256 signature for authentication. | `"a1b2c3d4e5f6g7h8i9j0..."` | #### **1.3.1 Parameter Details** * **`start_time` and `end_time`**: * Represent the time window for which transaction data is requested. * Possible intervals are **5, 10, 15, or 30 minutes**, depending on settings and agreed-upon configurations. * Must be in ISO 8601 format and in UTC timezone. * **`groups`**: * Specifies which groups or merchants the data should be retrieved for. * If set to `"all"`, data for all available groups should be returned. * **`signature`**: * Used for request authentication. * Generated using HMAC SHA-256 with a secret key. ### **1.4 Authentication** #### **1.4.1 Signature Generation** The `signature` parameter is generated by concatenating the values of `start_time`, `end_time`, and `groups`, then applying HMAC SHA-256 encryption using the secret key. **Example in Python**: ```python import hmac import hashlib data = "2024-09-30T10:00:00Z2024-09-30T11:00:00Zmerchant1,merchant2" secret_key = "your_secret_key" signature = hmac.new(secret_key.encode(), data.encode(), hashlib.sha256).hexdigest() ``` **Important Notes**: * The shared secret key will be provided to you securely. * Ensure that the signature is correctly calculated to avoid authentication errors. ### **1.5 Response Structure** Your API should return a JSON response with the following structure: | Field | Type | Description | | --------------- | ------- | ---------------------------------------------------------------- | | `status` | String | `"success"` or `"error"`. | | `error_code` | Integer | Numeric code (`0` for success, other codes for specific errors). | | `error_message` | String | Description of the error (if any). | | `start_time` | String | Echoes the `start_time` from the request. | | `end_time` | String | Echoes the `end_time` from the request. | | `groups` | Array | Contains data objects for each group and metric. | #### **1.5.1 Group Data Object** Each element in the `groups` array should have the following fields: | Field | Type | Description | | -------- | ------- | ------------------------------------------------- | | `group` | String | Name of the group (e.g., merchant identifier). | | `metric` | String | Name of the metric (e.g., `"transaction_count"`). | | `count` | Integer | Transaction count for the specified period. | ### **1.6 Requests and Responses Examples** #### **1.6.1 Request Example** ```json { "start_time": "2024-09-30T10:00:00Z", "end_time": "2024-09-30T10:05:00Z", "groups": "merchant1,merchant2", "signature": "a1b2c3d4e5f6g7h8i9j0..." } ``` #### **1.6.2 Successful Response** ```json { "status": "success", "error_code": 0, "error_message": null, "start_time": "2024-09-30T10:00:00Z", "end_time": "2024-09-30T10:05:00Z", "groups": [ { "group": "merchant1", "metric": "transactions_all", "count": 150 }, { "group": "merchant2", "metric": "deposits", "count": 200 } ] } ``` #### **1.6.3 Error Response - Invalid Signature** ```json { "status": "error", "error_code": 1, "error_message": "Invalid authentication signature", "start_time": null, "end_time": null, "groups": null } ``` ### **1.7 Error Codes** | Error Code | Description | | ---------- | --------------------------------- | | 0 | Success | | 1 | Invalid signature | | 2 | Missing or invalid parameters | | 3 | Internal server error | | 4 | Too many requests (rate limiting) | ### **1.8 HTTP Status Codes** * **200 OK**: Successful requests. * **400 Bad Request**: Invalid request format or parameters. * **401 Unauthorized**: Authentication failed. * **429 Too Many Requests**: Rate limiting applied. * **500 Internal Server Error**: Server-side errors. *** ## **2. Groups and Metrics** * **Groups**: Typically represent identifiers such as merchant IDs, store IDs, or any other logical grouping relevant to your business. * **Metrics**: Currently, the system focuses on the number of transactions in the specified interval. It can be one of transaction types like “deposits” or “withdrawals”, and also the whole transaction amount without types differentiation, for example “all transactions”. *** ## 3. Initial Training and Missing Data Recovery Procedure The anomaly detection service will automatically recover missing data in cases where the client's system was unresponsive or there were issues with the monitoring service itself. It will sequentially request data for the missing period, at a rate of **5 requests per second**. These requests are identical to those used during normal operation. Initial training happens in the same way as Missing Data Recovery Procedure but will be applied for **6 weeks time period**. *** ## **4. Limits** * In current version the maximum response size should not exceed **500 KB**. Please contact Anomalis team if you predict larger responses. * Maximum length of the requested interval between start\_time and end\_time from Anomalis Service is not supposed to be larger than **30 minute**s. * The requested stats are not supposed to be older than **2 months** ago. * In case of missing data recovery procedure, you will receive **5 requests per second** maximum. *** ## 5. Notifications ### 5.1 Anomaly Notification When an anomaly is detected, the system sends a Telegram message containing the following parameters: * **Incident ID**: Unique identifier for the incident, used to link information about this anomaly with other events. * **Type**: Type of anomaly, currently always set to "Statistical". More types will be added in future versions. * **Group**: Logical grouping of incidents, such as merchant ID or other relevant business identifiers. * **Metric**: A specific name or designation for the metric used to detect the anomaly. It can include transaction types like "deposits" or "withdrawals" or the total transaction volume, such as "all transactions". * **Detected**: The specific moment in time when the anomaly was detected. * **Layers affected**: Time intervals where anomalies were detected (e.g., 5 minutes, 15 minutes, 2 hours, 8 hours, etc.). Describes the time layers where deviations were observed, including expected and actual metric values. **Example**: ``` [Anomaly Detected] Incident ID: 12345 Type: Statistical Group: merchant1 Metric: deposits Detected: 2024-08-23 08:15:00 Layers affected: - 5 minutes (expected: 200, actual: 150) - 15 minutes (expected: 600, actual: 500) ``` ### 5.2 Normalization Notification Sent when the anomaly is resolved. **Example**: ``` [Anomaly Resolved] Incident ID: 12345 Group: merchant1 Metric: deposits Incident Start: 2024-08-23 08:00:00 Incident End: 2024-08-23 09:00:00 ```