### Balance Accumulation Scenario Example (JSON)

Source: https://proverkacheka.kz/docs

Illustrates the balance accumulation logic when `use_balance: true` is enabled. It shows how the `balance` and `due` fields update with each received check until the `balance` meets or exceeds the `price`.

```json
// price = 10000

// Чек #1 — 6000 тенге
{ "balance": 6000, "due": 4000 }

// Чек #2 — 4000 тенге, оплата завершена
{ "balance": 10000, "due": 0 }
```

--------------------------------

### Upload Check with IIN Validation - cURL

Source: https://proverkacheka.kz/docs

This example demonstrates uploading a check for verification, prioritizing the seller's IIN for validation. This method is more reliable than using 'ip_name' as the IIN is unique to each seller.

```shell
curl -X POST https://api.proverkacheka.kz/upload \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "550e8400-e29b-41d4-a716-446655440000",
    "file": "https://example.com/receipt.pdf",
    "user_id": "123456789",
    "price": 5000,
    "iin": "123456789012"
  }'
```

--------------------------------

### Send Check for Verification (URL) - cURL

Source: https://proverkacheka.kz/docs

This example demonstrates how to send a PDF check for verification using its URL. It requires an API key, the file URL, a user ID, and optionally the price and seller's IIN/BIN. The response indicates if the check is valid and provides details.

```shell
curl -X POST https://api.proverkacheka.kz/upload \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ваш-api-ключ",
    "file": "https://example.com/receipt.pdf",
    "user_id": "123456789",
    "price": 5000,
    "iin": "123456789012"
  }'
```

--------------------------------

### Upload Check via URL - cURL

Source: https://proverkacheka.kz/docs

This cURL command demonstrates sending a check for verification by providing a URL to the PDF file. It includes the API key, file URL, user ID, price, and optionally the seller's name and IIN.

```shell
curl -X POST https://api.proverkacheka.kz/upload \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "550e8400-e29b-41d4-a716-446655440000",
    "file": "https://example.com/receipt.pdf",
    "user_id": "123456789",
    "price": 5000,
    "ip_name": "ИП АЛИБЕКОВ",
    "iin": "123456789012"
  }'
```

--------------------------------

### File Upload API (Balance Accumulation)

Source: https://proverkacheka.kz/docs

Allows for file uploads, with an option to enable balance accumulation for partial payments. The response indicates the current balance and remaining amount due.

```APIDOC
## POST /upload (with use_balance: true)

### Description
Uploads a file for validation and enables balance accumulation for partial payments. The response includes the current balance and the amount still due.

### Method
POST

### Endpoint
/upload

### Parameters
#### Query Parameters
- **use_balance** (boolean) - Optional - If true, enables balance accumulation mode.

#### Request Body
- **file** (file) - Required - The file to upload (e.g., PDF).
- **price** (number) - Required - The total price for the transaction.

### Request Example
```json
{
  "use_balance": true,
  "price": 10000
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message (e.g., "Баланс пополнен").
- **check_number** (string) - The unique identifier for the check.
- **amount** (number) - The amount of the current payment.
- **company_name** (string) - The name of the company issuing the check.
- **balance** (number) - The current accumulated balance.
- **due** (number) - The remaining amount due.
- **payment_method** (string) - The method of payment.

#### Response Example
```json
{
  "message": "Баланс пополнен",
  "check_number": "QR13973837513",
  "amount": 500.00,
  "company_name": "ИП АЛИБЕКОВ",
  "balance": 500.00,
  "due": 500.00,
  "payment_method": "с Kaspi Gold"
}
```

### Error Handling
- **400 Bad Request**: Invalid file type, file too large, missing API key.
- **401 Unauthorized**: Invalid API key.
- **402 Payment Required**: Insufficient credits.
- **408 Request Timeout**: Timeout during file download.
- **413 Payload Too Large**: Request exceeds the maximum allowed size.
- **429 Too Many Requests**: Rate limit exceeded.
```

--------------------------------

### POST /upload

Source: https://proverkacheka.kz/docs

Upload a Kaspi PDF check for validation. Supports sending the file via URL, base64, or multipart form.

```APIDOC
## POST /upload

### Description
Upload a Kaspi PDF check for validation. Supports sending the file via URL, base64, or multipart form.

### Method
POST

### Endpoint
https://api.proverkacheka.kz/upload

### Parameters
#### Request Body
- **api_key** (string) - Required - UUID API key of the client.
- **file** (string / file) - Required - URL to PDF, base64 string, or binary file (multipart).
- **user_id** (string) - Required - User identifier (e.g., Telegram ID).
- **price** (number) - Optional - Minimum payment amount in tenge (default: 1000).
- **ip_name** (string) - Required* - Seller's name (Sole Proprietor/LLC). *Not required if `iin` is provided.
- **iin** (string) - Recommended - Seller's IIN/BIN (12 digits). Unique for each seller, prevents substitution.
- **use_balance** (boolean) - Optional - Partial payment accumulation mode (default: false).
- **max_age** (integer) - Optional - Maximum check age in days (default: 14).
- **max_overpay** (number) - Optional - Maximum allowable overpayment beyond `price`.

### Request Example
```json
{
  "api_key": "550e8400-e29b-41d4-a716-446655440000",
  "file": "https://example.com/receipt.pdf",
  "user_id": "123456789",
  "price": 5000,
  "ip_name": "ИП АЛИБЕКОВ",
  "iin": "123456789012"
}
```

### Response
#### Success Response (200)
- **message** (string) - Status message.
- **check_number** (string) - Unique check identifier.
- **amount** (number) - The validated amount of the check.
- **company_name** (string) - The name of the company that issued the check.
- **payment_method** (string) - The method of payment used.
- **balance** (any) - Null in this context.
- **due** (any) - Null in this context.

#### Response Example
```json
{
  "message": "Чек валиден и добавлен в базу данных.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "payment_method": "с Kaspi Gold",
  "balance": null,
  "due": null
}
```

#### Response Example (Duplicate Check)
```json
{
  "message": "Чек уже обработан ранее.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "previous_user_id": "123456789",
  "payment_method": "с Kaspi Gold"
}
```
```

--------------------------------

### Error Codes

Source: https://proverkacheka.kz/docs

Provides a comprehensive list of API error codes, their descriptions, and common causes.

```APIDOC
## API Error Codes

### Description
This section details the various error codes returned by the API, along with their corresponding messages and potential causes.

### Error List

| Code | Description                                       | Cause                                       |
|------|---------------------------------------------------|---------------------------------------------|
| 200  | Successful request (check `message` for validation result) | Valid request, but validation may have specific outcomes. |
| 400  | Bad Request - Missing parameters or invalid format | Missing API key, invalid file type, file too large (> 5 MB), etc. |
| 401  | Unauthorized - Invalid API key                    | The provided API key is incorrect or expired. |
| 402  | Payment Required - Insufficient credits           | Your account has run out of credits.        |
| 408  | Request Timeout - File download timeout           | The URL provided for file download is unresponsive for more than 10 seconds. |
| 413  | Payload Too Large                                 | The request payload exceeds the 10 MB limit. |
| 429  | Too Many Requests - Rate limit exceeded           | Exceeded 100 requests per minute.           |
| 500  | Internal Server Error                             | An unexpected error occurred on the server. |

### Validation Error Messages
When a validation error occurs (e.g., incorrect amount, wrong seller, outdated check), the API returns a `200 OK` status with a descriptive message in the `message` field. Always check the `message` field for the specific outcome of the validation.
```

--------------------------------

### Upload Check via File Upload - cURL

Source: https://proverkacheka.kz/docs

This cURL command shows how to upload a PDF check directly as a file. It uses multipart form data to send the API key, the PDF file, user ID, price, and seller's name and IIN.

```shell
curl -X POST https://api.proverkacheka.kz/upload \
  -F "api_key=550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@/path/to/receipt.pdf" \
  -F "user_id=123456789" \
  -F "price=5000" \
  -F "ip_name=ИП АЛИБЕКОВ" \
  -F "iin=123456789012"
```

--------------------------------

### Generate HMAC-Signed Token for Widget (PHP)

Source: https://proverkacheka.kz/docs

Generate a secure HMAC-signed token on your server for the Proverkacheka widget. This PHP function utilizes hash_hmac to create a token from verification parameters and your API key, safeguarding against tampering.

```php
function generateToken(array $params, string $apiKey): string {
    $payload = rtrim(strtr(base64_encode(
        json_encode($params)
    ), '+/', '-_'), '=');
    $signature = hash_hmac('sha256', $payload, $apiKey);
    return "{$payload}.{$signature}";
}

$token = generateToken([
    'price' => 5000,
    'iin' => '123456789012',
    'max_age' => 7,
    'exp' => time() + 3600,
], 'ВАШ_API_KEY');
```

--------------------------------

### Generate HMAC-Signed Token for Widget (Node.js)

Source: https://proverkacheka.kz/docs

Generate a secure HMAC-signed token on your server for the Proverkacheka widget. This Node.js function uses the crypto module to create a token from verification parameters and your API key, ensuring data integrity.

```javascript
const crypto = require('crypto');

function generateToken(params, apiKey) {
  const payload = Buffer.from(JSON.stringify(params))
    .toString('base64url');
  const signature = crypto
    .createHmac('sha256', apiKey)
    .update(payload)
    .digest('hex');
  return `${payload}.${signature}`;
}

const token = generateToken({
  price: 5000,
  iin: '123456789012',
  max_age: 7,
  exp: Math.floor(Date.now() / 1000) + 3600
}, 'ВАШ_API_KEY');
```

--------------------------------

### Generate HMAC-Signed Token for Widget (Python)

Source: https://proverkacheka.kz/docs

Generate a secure HMAC-signed token on your server for the Proverkacheka widget. This Python function takes verification parameters and your API key to create a token that prevents user manipulation of check details.

```python
import hmac, hashlib, base64, json, time

def generate_token(params, api_key):
    payload = base64.urlsafe_b64encode(
        json.dumps(params).encode()
    ).rstrip(b'=').decode()
    signature = hmac.new(
        api_key.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return f"{payload}.{signature}"

token = generate_token({
    "price": 5000,
    "iin": "123456789012",
    "max_age": 7,
    "exp": int(time.time()) + 3600  # 1 час
}, "ВАШ_API_KEY")
```

--------------------------------

### Embed Proverkacheka Widget on Website (HTML)

Source: https://proverkacheka.kz/docs

Integrate a check verification widget into your website using a simple HTML snippet. This widget requires an API key and a generated token for security. The token embeds verification parameters like price, seller, and validity period.

```html
<div data-proverkacheka-widget
     data-api-key="ВАШ_API_KEY"
     data-token="СГЕНЕРИРОВАННЫЙ_ТОКЕН"
     data-user-id="order-123"></div>
<script src="https://api.proverkacheka.kz/widget.js"></script>
```

--------------------------------

### Successful Check Verification Response (Detailed)

Source: https://proverkacheka.kz/docs

This is a detailed successful response from the API after a check has been validated. It includes a message, check number, amount, company name, payment method, and potentially balance and due information.

```json
// 200 OK
{
  "message": "Чек валиден и добавлен в базу данных.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "payment_method": "с Kaspi Gold",
  "balance": null,
  "due": null
}
```

--------------------------------

### Successful Balance Accumulation Response (JSON)

Source: https://proverkacheka.kz/docs

This JSON response indicates a successful operation where the balance has been updated. It's used when the accumulated balance is less than the required price, showing the current balance and the remaining amount due. The `use_balance: true` parameter must be set in the request.

```json
{
  "message": "Баланс пополнен",
  "check_number": "QR13973837513",
  "amount": 500.00,
  "company_name": "ИП АЛИБЕКОВ",
  "balance": 500.00,
  "due": 500.00,
  "payment_method": "с Kaspi Gold"
}
```

--------------------------------

### Successful Check Verification Response

Source: https://proverkacheka.kz/docs

This is a successful response from the API after a check has been validated and added to the database. It includes a success message, check number, amount, company name, and payment method.

```json
{
  "message": "Чек валиден и добавлен в базу данных.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "payment_method": "с Kaspi Gold"
}
```

--------------------------------

### Check API Health Status (curl)

Source: https://proverkacheka.kz/docs

This command-line request checks the health status of the Proverkacheka.kz API service and its database connection. It does not require authentication and returns a JSON object indicating the service status.

```curl
curl https://api.proverkacheka.kz/health
```

--------------------------------

### Health Check API

Source: https://proverkacheka.kz/docs

Checks the health status of the service and database availability. This endpoint does not require authentication.

```APIDOC
## GET /health

### Description
Checks the health status of the service and database availability.

### Method
GET

### Endpoint
/health

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://api.proverkacheka.kz/health
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the service.
- **service** (string) - The name of the service.

#### Response Example
```json
{
  "status": "healthy",
  "service": "proverkacheka-api"
}
```
```

--------------------------------

### API Health Check Success Response (JSON)

Source: https://proverkacheka.kz/docs

A successful response from the `/health` endpoint, indicating that the Proverkacheka.kz API service is operational and the database is accessible. The response includes the status and the name of the service.

```json
{
  "status": "healthy",
  "service": "proverkacheka-api"
}
```

--------------------------------

### Duplicate Check Verification Response

Source: https://proverkacheka.kz/docs

This response is returned when a check has already been processed. It indicates that the check is a duplicate and provides the same details as a successful verification, along with the previous user ID.

```json
{
  "message": "Чек уже обработан ранее.",
  "check_number": "QR13973837513",
  "amount": 1000.50,
  "company_name": "ИП АЛИБЕКОВ",
  "previous_user_id": "123456789",
  "payment_method": "с Kaspi Gold"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.