# سجل التغييرات

كل إصدارات API لدى AdProMaxPay، وما يتضمنه كل إصدار، وهل يكسر الكود القائم.

تسرد هذه الصفحة كل إصدارات API، الأحدث أولًا. يوضح كل مدخل هل هو **كاسر للتوافق**:
أي هل يجب تغيير الكود المكتوب للإصدار الذي قبله.

## كيف تعمل الإصدارات

* يُسمّى الإصدار بتاريخه: `2026-11-01`.
* مؤسستك **مثبَّتة** على الإصدار الذي كان ساريًا عند إنشائها. يذكره حقلها
  `api_version` في `GET /v1/account`. وتستخدمه طلباتك ما لم تحدد غير ذلك.
* يمكن لطلب أن يحدد إصدارًا عبر ترويسة `X-AdProMaxPay-Version`. يُرفض الإصدار غير المعروف
  بـ `400`، `api_version_invalid`.
* يحمل كل حدث `api_version` الذي كُتب به.

يأتي **التغيير الكاسر للتوافق** في إصدار جديد مؤرَّخ، ويظل الإصدار الذي أنت مثبَّت عليه يعمل
كما كان. أما **الإضافات** فتأتي دون إصدار جديد: كائنات جديدة، وحقول جديدة، وأنواع أحداث جديدة،
ومعاملات اختيارية جديدة، ورموز أخطاء جديدة. اكتب كودك بحيث يتجاهل الحقول وأنواع الأحداث التي
لا يعرفها.

```bash
curl https://pay-api.adpromax.com/v1/account \
  -u "$APX_SECRET_KEY:" \
  -H "X-AdProMaxPay-Version: 2026-11-01"
```

```js title="version.mjs"
const response = await fetch('https://pay-api.adpromax.com/v1/account', {
  headers: {
    'Authorization': `Bearer ${process.env.APX_SECRET_KEY}`,
    'X-AdProMaxPay-Version': '2026-11-01',
  },
})
const account = await response.json()
console.log(account.api_version)
```

```ts title="version.ts"
interface Account {
  id: string
  object: 'account'
  api_version: string
}

const response = await fetch('https://pay-api.adpromax.com/v1/account', {
  headers: {
    'Authorization': `Bearer ${process.env.APX_SECRET_KEY}`,
    'X-AdProMaxPay-Version': '2026-11-01',
  },
})
const account = (await response.json()) as Account
console.log(account.api_version)
```

```python title="version.py"
import os

import requests

response = requests.get(
    "https://pay-api.adpromax.com/v1/account",
    auth=(os.environ["APX_SECRET_KEY"], ""),
    headers={"X-AdProMaxPay-Version": "2026-11-01"},
)
account = response.json()
print(account["api_version"])
```

```php title="version.php"
<?php
$ch = curl_init('https://pay-api.adpromax.com/v1/account');
curl_setopt_array($ch, [
    CURLOPT_USERPWD => getenv('APX_SECRET_KEY') . ':',
    CURLOPT_HTTPHEADER => ['X-AdProMaxPay-Version: 2026-11-01'],
    CURLOPT_RETURNTRANSFER => true,
]);
$account = json_decode(curl_exec($ch), true);
echo $account['api_version'], PHP_EOL;
```

```ruby title="version.rb"
require 'json'
require 'net/http'

uri = URI('https://pay-api.adpromax.com/v1/account')
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch('APX_SECRET_KEY'), '')
request['X-AdProMaxPay-Version'] = '2026-11-01'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(request)
end
account = JSON.parse(response.body)
puts account['api_version']
```

```go title="version.go"
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

type Account struct {
	ID         string `json:"id"`
	APIVersion string `json:"api_version"`
}

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://pay-api.adpromax.com/v1/account", nil)
	if err != nil {
		log.Fatal(err)
	}
	req.SetBasicAuth(os.Getenv("APX_SECRET_KEY"), "")
	req.Header.Set("X-AdProMaxPay-Version", "2026-11-01")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	var account Account
	if err := json.NewDecoder(res.Body).Decode(&account); err != nil {
		log.Fatal(err)
	}
	fmt.Println(account.APIVersion)
}
```

```java title="Version.java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Version {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://pay-api.adpromax.com/v1/account"))
            .header("Authorization", "Bearer " + System.getenv("APX_SECRET_KEY"))
            .header("X-AdProMaxPay-Version", "2026-11-01")
            .GET()
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        // The JDK has no JSON parser: a small regex reads api_version.
        Matcher version = Pattern
            .compile("\"api_version\"\\s*:\\s*\"([^\"]*)\"")
            .matcher(response.body());
        System.out.println(version.find() ? version.group(1) : response.body());
    }
}
```

```csharp title="Version.cs"
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var json = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower };
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("APX_SECRET_KEY"));
http.DefaultRequestHeaders.Add("X-AdProMaxPay-Version", "2026-11-01");

var account = await http.GetFromJsonAsync<Account>("https://pay-api.adpromax.com/v1/account", json);
Console.WriteLine(account!.ApiVersion);

record Account(string Id, string ApiVersion);
```

```rust title="main.rs"
// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }
//             serde = { version = "1", features = ["derive"] }
use serde::Deserialize;

#[derive(Deserialize)]
struct Account {
    api_version: String,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let account: Account = reqwest::blocking::Client::new()
        .get("https://pay-api.adpromax.com/v1/account")
        .bearer_auth(std::env::var("APX_SECRET_KEY")?)
        .header("X-AdProMaxPay-Version", "2026-11-01")
        .send()?
        .json()?;
    println!("{}", account.api_version);
    Ok(())
}
```

## 2026-11-01

**غير كاسر للتوافق**: الإصدار الأول من API. يتضمن:

* **الحساب**: `GET /v1/account`، مؤسستك وحالة تفعيلها. انظر
  [مفاتيح API الخاصة بك](https://pay-docs.adpromax.com/ar/get-started/api-keys).
* **نيات الدفع (payment intents) والمحاولات (charges)**، بالبطاقة ونقدًا، مع حالاتها ومحاولاتها. انظر
  [كيف تعمل المدفوعات](https://pay-docs.adpromax.com/ar/payments/how-payments-work).
* **جلسات الدفع** (checkout sessions)، لصفحة الدفع المستضافة. انظر [صفحة الدفع المستضافة](https://pay-docs.adpromax.com/ar/payments/hosted-checkout).
* **العملاء**. انظر [العملاء](https://pay-docs.adpromax.com/ar/payments/customers).
* **استرداد** المدفوعات بالبطاقة. انظر [المبالغ المستردة](https://pay-docs.adpromax.com/ar/payments/refunds).
* **الأحداث ونقاط استقبال الـ webhook**: عمليات تسليم موقّعة، تُعاد محاولتها نحو ثلاثة
  أيام. انظر [Webhooks](https://pay-docs.adpromax.com/ar/webhooks).
* **أدوات الاختبار المساعدة**، في وضع الاختبار فقط. انظر [واجهة API لأدوات الاختبار المساعدة](https://pay-docs.adpromax.com/ar/sandbox/test-helpers).
* **عدم التكرار** (idempotency): إلزامي في الطلبات التي تحرّك أموالًا، وتُحفظ الاستجابات 24 ساعة. انظر
  [عدم التكرار](https://pay-docs.adpromax.com/ar/api-reference/idempotency).
* **الأخطاء** في سبعة أنواع، برسائل بالفرنسية أو الإنجليزية أو العربية، حسب ترويسة `Accept-Language`.
  انظر [معالجة الأخطاء](https://pay-docs.adpromax.com/ar/errors).
* **ترقيم الصفحات بالمؤشر** في القوائم: `limit` و`starting_after` و`ending_before`.
* **حدود المعدل** لكل مؤسسة ووضع، مع ترويسات `RateLimit-*`. انظر
  [حدود المعدل](https://pay-docs.adpromax.com/ar/api-reference/rate-limits).
* **البيانات الوصفية** على نيات الدفع وجلسات الدفع والعملاء وعمليات الاسترداد ونقاط استقبال الـ webhook. انظر
  [البيانات الوصفية](https://pay-docs.adpromax.com/ar/payments/metadata).