**API Documentation for Telegram Bot Integration with HiParkV**
Overview
This document describes the RESTful API for integrating a Telegram bot with the HiParkV parking management system, enabling car license plate validation and discount application.
Base URL
[https://[server]:[port]/api/validator/](https://[server]:[port]/api/validator/)
Authentication
All API requests require an API key passed in the request body:
{ "API_KEY": "your_api_key_here" }
Endpoints
**1. Validate License Plate**
Checks if a vehicle with the specified license plate is currently in the parking.
**Endpoint:** **/validate**
**Method:** **POST**
| Request
{
"API_KEY": "your_api_key_here",
"PlateNumber": "ABC123",
"UID": "validator_device_identifier"
}
| Response
**Success (200 OK)**
{
"Present": true,
"VehicleInfo": {
"PlateNumber": "ABC123",
"CheckInTimeStamp": "2025-03-07T14:30:00Z",
"ClientGroup": "1",
"NextTimeSlice": "2025-03-07T15:30:00Z",
"CurrentFee": "500"
},
"ErrorDescription": null
}
**Not Found (404 Not Found)**
{
"Present": false,
"VehicleInfo": null,
"ErrorDescription": "Plate not found"
}
**Bad Request (400 Bad Request)**
"Invalid request: Plate number required"
|
| --- | --- |
**2. Apply Time-Based Discount**
A time discount (in minutes) applies to a vehicle's parking fee.
**Endpoint:** **/discount/time**
**Method:** **POST**
| Request
{
"API_KEY": "your_api_key_here",
"PlateNumber": "ABC123",
"DiscountMinutes": 60,
"UID": "validator_device_identifier"
}
| Response
**Success (200 OK)**
{
"Successful": true,
"NewFee": 300,
"ErrorDescription": null
}
**Not Found (404 Not Found)**
{
"Successful": false,
"NewFee": 0,
"ErrorDescription": "Failed to apply discount"
}
**Bad Request (400 Bad Request)**
"Invalid request: Plate number and discount minutes required"
|
| --- | --- |
**3. Apply Monetary Discount**
Applies a monetary discount amount to a vehicle's parking fee.
**Endpoint:** **/discount/sum**
**Method:** **POST**
| Request
{
"API_KEY": "your_api_key_here",
"PlateNumber": "ABC123",
"DiscountAmount": 200,
"UID": "validator_device_identifier"
}
| Response
**Success (200 OK)**
{
"Successful": true,
"NewFee": 300,
"ErrorDescription": null
}
**Not Found (404 Not Found)**
{
"Successful": false,
"NewFee": 0,
"ErrorDescription": "Failed to apply discount"
}
**Bad Request (400 Bad Request)**
"Invalid request: Plate number and discount amount required"
|
| --- | --- |
**Error Codes**
| Status Code | Description | |-------------|-------------| | 200 | Success - The request was successful | | 400 | Bad Request - Missing or invalid parameters | | 401 | Unauthorized - Invalid API key | | 404 | Not Found - Vehicle not found or discount application failed | | 405 | Method Not Allowed - Only POST method is supported | | 500 | Internal Server Error - Server encountered an error |
**Example Usage Workflow**
1. User inputs license plate in Telegram bot
2. Bot calls **/validate** endpoint to verify vehicle presence
3. If the vehicle is found, bot displays current fee and options for discount
4. User selects discount type (time or monetary) and amount
5. Bot calls an appropriate endpoint (**/discount/time** or **/discount/sum**)
6. Bot displays confirmation and updated fee to user
This API enables Telegram bots to seamlessly integrate with the HiParkV parking system, providing a convenient way for authorized personnel to validate vehicles and apply discounts remotely.