REST API · الإصدار 1

صور مستندات مطابقة للشروط بطلب API واحد

أرسل صورة والمستند المطلوب لها، فتعود إليك مقصوصة وبالمقاس الصحيح ومفحوصة وفق الشروط الرسمية لذلك المستند، مع نتيجة كل فحص — المحرّك نفسه الذي يعمل عليه موقعنا، للتطبيقات ومحلات الطباعة والأكشاك.

احصل على مفتاح تجريبي اقرأ المرجع

العنوان الأساسي https://api.takiphoto.com/api/v1

حالة الـ API: جارٍ التحقق…

بدء سريع

من الصفر إلى صورة جاهزة في ثلاث خطوات.

احصل على مفتاح تجريبي
افتح حساب API وأنشئ مفتاحاً تجريبياً — يبدأ بـ pk_test_. المفاتيح التجريبية مجانية وتعيد معاينة بعلامة مائية.
احصل على مفتاح تجريبي

أرسل صورة

أرسل الصورة بطلب POST مع المستند الذي تحتاجه. يصلك الرد فور جهوز الصورة، أو 202 مع ترويسة Location لتتابعها.

curl -X POST "https://api.takiphoto.com/api/v1/photos" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000" \
  -F "[email protected]" \
  -F "spec_id=us-passport" \
  -F 'outputs=["digital"]'

اقرأ النتيجة

تحمل الصورة حالتها، وكل فحص قيست به، وبعد اكتمالها روابط موقَّعة لملفاتها. هذا شكلها:

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

أمثلة برمجية

الطلبات الثلاثة نفسها بأربع لغات. ضع مفتاحك مكان المفتاح المثال.

رفع ملف صورة

curl -X POST "https://api.takiphoto.com/api/v1/photos" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000" \
  -F "[email protected]" \
  -F "spec_id=us-passport" \
  -F 'outputs=["digital"]'

قراءة صورة

curl "https://api.takiphoto.com/api/v1/photos/PHOTO_ID" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000"

إرسال صورة برابطها

curl -X POST "https://api.takiphoto.com/api/v1/photos" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"spec_id": "us-passport", "image_url": "https://example.com/photo.jpg", "outputs": ["digital"]}'

رفع ملف صورة

import requests

with open("photo.jpg", "rb") as photo:
    response = requests.post(
        "https://api.takiphoto.com/api/v1/photos",
        headers={"Authorization": "Bearer pk_test_EXAMPLE000000000000000000000000000000000000"},
        files={"file": photo},
        data={"spec_id": "us-passport", "outputs": '["digital"]'},
        timeout=30,
    )
response.raise_for_status()
print(response.json()["status"])

قراءة صورة

import requests

response = requests.get(
    "https://api.takiphoto.com/api/v1/photos/PHOTO_ID",
    headers={"Authorization": "Bearer pk_test_EXAMPLE000000000000000000000000000000000000"},
    timeout=30,
)
photo = response.json()
print(photo["status"], photo["outputs"])

إرسال صورة برابطها

import requests

response = requests.post(
    "https://api.takiphoto.com/api/v1/photos",
    headers={"Authorization": "Bearer pk_test_EXAMPLE000000000000000000000000000000000000"},
    json={"spec_id": "us-passport", "image_url": "https://example.com/photo.jpg", "outputs": ["digital"]},
    timeout=30,
)
print(response.json()["status"])

رفع ملف صورة

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");
form.append("spec_id", "us-passport");
form.append("outputs", JSON.stringify(["digital"]));

const response = await fetch("https://api.takiphoto.com/api/v1/photos", {
  method: "POST",
  headers: { Authorization: "Bearer pk_test_EXAMPLE000000000000000000000000000000000000" },
  body: form,
});
const photo = await response.json();
console.log(photo.status);

قراءة صورة

const response = await fetch("https://api.takiphoto.com/api/v1/photos/PHOTO_ID", {
  headers: { Authorization: "Bearer pk_test_EXAMPLE000000000000000000000000000000000000" },
});
const photo = await response.json();
console.log(photo.status, photo.outputs);

إرسال صورة برابطها

const response = await fetch("https://api.takiphoto.com/api/v1/photos", {
  method: "POST",
  headers: { Authorization: "Bearer pk_test_EXAMPLE000000000000000000000000000000000000", "Content-Type": "application/json" },
  body: JSON.stringify({ spec_id: "us-passport", image_url: "https://example.com/photo.jpg", outputs: ["digital"] }),
});
const photo = await response.json();
console.log(photo.status);

رفع ملف صورة

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final request = http.MultipartRequest('POST', Uri.parse('https://api.takiphoto.com/api/v1/photos'))
    ..headers['Authorization'] = 'Bearer pk_test_EXAMPLE000000000000000000000000000000000000'
    ..fields['spec_id'] = 'us-passport'
    ..fields['outputs'] = jsonEncode(['digital'])
    ..files.add(await http.MultipartFile.fromPath('file', 'photo.jpg'));
  final response = await http.Response.fromStream(await request.send());
  final photo = jsonDecode(response.body) as Map<String, dynamic>;
  print(photo['status']);
}

قراءة صورة

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final response = await http.get(
    Uri.parse('https://api.takiphoto.com/api/v1/photos/PHOTO_ID'),
    headers: {'Authorization': 'Bearer pk_test_EXAMPLE000000000000000000000000000000000000'},
  );
  final photo = jsonDecode(response.body) as Map<String, dynamic>;
  print(photo['status']);
}

إرسال صورة برابطها

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final response = await http.post(
    Uri.parse('https://api.takiphoto.com/api/v1/photos'),
    headers: {'Authorization': 'Bearer pk_test_EXAMPLE000000000000000000000000000000000000', 'Content-Type': 'application/json'},
    body: jsonEncode({'spec_id': 'us-passport', 'image_url': 'https://example.com/photo.jpg', 'outputs': ['digital']}),
  );
  print(jsonDecode(response.body)['status']);
}

مرجع الـ API

مولَّد من عقد OpenAPI المنشور، فيسرد بالضبط ما يستجيب له الـ API — لا أكثر ولا أقل.

يحمل كل طلب مفتاح الـ API في الترويسة Authorization: Bearer pk_test_…. المفاتيح الحية (pk_live_) تُخصم من خطتك، والتجريبية (pk_test_) مجانية وتضع علامة مائية على النتيجة.

`/photos`

post/photosمفتاح API

Create Photo

A photo from file (multipart) or image_url (JSON). Answers 200 with the result when the photo settles within the wait — completed (one credit on a live key), needs_retake or failed (free) — else 202 with Location to poll. An expert review answers 202 in_review until the expert decides.

جسم الطلب `application/json`

backgroundstring | null

#RRGGBB; the document's own colour when absent.

الحدود:pattern: ^#[0-9A-Fa-f]{6}$

callback_urlstring | null

A public https URL told when this photo settles.

الحدود:maxLength: 512

expert_reviewboolean

Live keys: have an expert check the photo (one review credit).

الافتراضي: false

image_urlstring | nullمطلوب

JSON body only: a public http(s) URL of the photo, fetched by us (≤ 25 MB).

الحدود:maxLength: 2048

outputsarray<string>

The files wanted: the digital photo and any print sheets.

إحدى القيم:digital4x6in10x15cma4

الحدود:minItems: 1maxItems: 4

retouchboolean

The automatic light retouch, when it is offered.

الافتراضي: false

spec_idstringمطلوب

A document from GET /specs.

الحدود:minLength: 4maxLength: 64

مثال

{
  "background": "string",
  "callback_url": "string",
  "expert_review": false,
  "image_url": "string",
  "outputs": [
    "digital"
  ],
  "retouch": false,
  "spec_id": "string"
}

جسم الطلب `multipart/form-data`

backgroundstring | null: #RRGGBB; the document's own colour when absent.
الحدود:pattern: ^#[0-9A-Fa-f]{6}$
callback_urlstring | null: A public https URL told when this photo settles.
الحدود:maxLength: 512
expert_reviewboolean: Live keys: have an expert check the photo (one review credit).
الافتراضي: false
filestring<binary>مطلوب: The photo: JPEG, PNG, HEIC or WebP, at most 25 MB.
outputsstring: The files wanted, as the JSON text of an array: ["digital","4x6in"].
الافتراضي: ["digital"]
retouchboolean: The automatic light retouch, when it is offered.
الافتراضي: false
spec_idstringمطلوب: A document from GET /specs.
الحدود:minLength: 4maxLength: 64

الردود

200Successful Response
202Still processing after `api.sync_wait_s` (15 s): follow `Location`.

مثال

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/photos/{photo_id}`

get/photos/{photo_id}مفتاح API

Get Photo

The photo as it is now. Under the key's delete_after_download, the first read of a finished photo leaves it one more hour.

المعاملات

photo_idstringفي المسارمطلوب

الردود

200Successful Response

مثال

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

delete/photos/{photo_id}مفتاح API

Delete Photo

The photo and every file made from it, at once.

المعاملات

photo_idstringفي المسارمطلوب

الردود

- 204Successful Response
- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/photos/{photo_id}/adjust`

post/photos/{photo_id}/adjustمفتاح API

Adjust Photo

Scale and shift the crop (the same rules as the web editor); the photo's files are made again at once. Free: credits_charged does not change.

المعاملات

photo_idstringفي المسارمطلوب

جسم الطلب `application/json`

dxnumberمطلوب: الحدود:minimum: -300maximum: 300
dynumberمطلوب: الحدود:minimum: -300maximum: 300
scalenumberمطلوب: الحدود:minimum: 0.7maximum: 1.4

مثال

{
  "dx": 0,
  "dy": 0,
  "scale": 0.7
}

الردود

200Successful Response

مثال

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/specs`

get/specsمفتاح API

List Specs

The document specs a photo can be made for, verified ones first; country is the ISO 3166-1 alpha-2 code, q matches the id or a name in any language.

المعاملات

countrystring | nullفي الاستعلام

الحدود:minLength: 2maxLength: 2

qstring | nullفي الاستعلام

الحدود:maxLength: 64

limitintegerفي الاستعلام

الافتراضي: 50

الحدود:minimum: 1maximum: 200

الردود

200Successful Response

مثال

[
  {
    "background": "string",
    "category": "string",
    "country": "string",
    "id": "string",
    "names": {
      "key": "string"
    },
    "output_px": [
      0
    ],
    "tier": "string",
    "version": 0
  }
]

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/specs/{spec_id}`

get/specs/{spec_id}مفتاح API

Get Spec

المعاملات

spec_idstringفي المسارمطلوب

الردود

200Successful Response

مثال

{
  "allowed_backgrounds": [
    "string"
  ],
  "background": "string",
  "category": "string",
  "country": "string",
  "digital": {
    "format": "string",
    "height_px": 0,
    "max_kb": 0,
    "max_px": 0,
    "min_px": 0,
    "width_px": 0
  },
  "dpi": 0,
  "eye_line_from_bottom_mm": {
    "max": 0,
    "min": 0
  },
  "head_height_mm": {
    "max": 0,
    "min": 0
  },
  "id": "string",
  "names": {
    "key": "string"
  },
  "output_px": [
    0
  ],
  "print_sheets": [
    "string"
  ],
  "rules": {
    "color": "string",
    "expression": "string",
    "glasses": "string",
    "head_covering": "string"
  },
  "size_mm": {
    "height": 0,
    "width": 0
  },
  "source_url": "string",
  "tier": "string",
  "verified_at": "2026-01-01",
  "version": 0
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/usage`

get/usageمفتاح API

Usage

Credits left this period, the key's rate limit and mode, and its calls today.

الردود

200Successful Response

مثال

{
  "mode": "live",
  "period_end": "2026-01-01T12:00:00Z",
  "photos": {
    "balance": 0,
    "quota": 0,
    "used_this_period": 0
  },
  "rate_limit_per_min": 0,
  "requests_today": 0,
  "reviews": {
    "balance": 0,
    "quota": 0,
    "used_this_period": 0
  }
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
مثال
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

رموز الفحوصات والأخطاء

كل رمز قد يعيده الـ API، من القائمة نفسها التي تترجمها تطبيقاتنا.

رموز الفحوصات

كل عنصر في فحوصات الصورة يسمّي أحد هذه الرموز مع نتيجته.

الرمز	المعنى
`file_invalid`	تعذّرت قراءة هذا الملف ارفع صورة بصيغة JPEG أو PNG أو HEIC.
`file_too_large`	حجم الملف كبير جداً صدّر نسخة أصغر وحاول مرة أخرى.
`image_too_large`	عدد بكسلات الصورة كبير جداً أي صورة حتى 50 ميغابكسل تعمل.
`no_face`	لم نعثر على وجه واجه الكاميرا في إضاءة متساوية دون أي غطاء على وجهك.
`multiple_faces`	أكثر من شخص في الصورة يجب أن تكون وحدك في الإطار.
`head_turned`	رأسك مائل إلى الجانب انظر مباشرة إلى الكاميرا.
`head_tilted`	رأسك مائل حافظ على استقامة رأسك وانظر إلى الأمام مباشرة.
`eyes_closed`	عيناك تبدوان مغلقتين افتح عينيك وانظر إلى الكاميرا.
`mouth_open`	فمك مفتوح أغلق فمك بتعبير محايد.
`not_neutral`	التعبير غير محايد أرخِ ملامح وجهك دون ابتسامة.
`blurry`	الصورة غير واضحة ثبّت الكاميرا وتأكد من أن وجهك في بؤرة التركيز.
`too_dark`	الصورة داكنة جداً واجه نافذة أو أضف إضاءة أمامك.
`too_bright`	الصورة شديدة الإضاءة ابتعد عن الإضاءة المباشرة.
`uneven_lighting`	ظل على جانب من الوجه يجب أن يأتي الضوء من أمامك لا من الجانب.
`not_color`	هذا المستند يتطلب صورة ملونة التقط الصورة بوضع الألوان.
`busy_background`	الخلفية مزدحمة جدار بسيط خلفك يمنح حواف أنظف — أو أضف مراجعة من خبير.
`head_not_measurable`	تعذّر قياس رأسك واجه الكاميرا في إضاءة جيدة وحاول مرة أخرى.
`low_resolution`	وجهك صغير جداً في الصورة اقترب أكثر أو استخدم صورة أكبر.
`crown_cut`	أعلى الرأس مقصوص اترك مسافة فوق الشعر.
`shoulders_cut`	الإطار ينتهي قريباً جداً من الذقن أضف كتفيك إلى الصورة.
`subject_cut_side`	الشخص مقصوص من الحافة توسّط الإطار مع مسافة متساوية على الجانبين.
`eye_line_out_of_range`	خط العينين خارج النطاق المسموح أُطِّرت الصورة حسب ارتفاع الرأس بدلاً من ذلك.
`head_size_out_of_range`	حجم الرأس خارج النطاق المسموح لهذا المستند قرّب أو بعّد حتى يلائم الرأس الدليل.
`file_size_over_limit`	حجم الملف أكبر مما يسمح به هذا المستند خفّضنا الجودة إلى أقصى حد مقبول.
`retouch_skipped`	لا يوجد ما يمكن تحسينه بأمان تم الاحتفاظ بالصورة الأصلية.

رموز الأخطاء

الطلب الذي يفشل يرد بحالة HTTP وغلاف خطأ رمزه أحد هذه الرموز.

الرمز	حالة HTTP	المعنى
`background_not_allowed`	400	لون الخلفية هذا غير مسموح لهذا المستند.
`credit_packs_disabled`	400	حزم الرصيد غير معروضة للبيع حالياً.
`crop_out_of_bounds`	400	منطقة القص المطلوبة تتجاوز حدود الصورة.
`email_required`	400	يلزم إدخال بريد إلكتروني للتسليم.
`invite_invalid`	400	هذه الدعوة غير صالحة.
`magic_link_invalid`	400	رابط تسجيل الدخول هذا غير صالح أو منتهي الصلاحية — اطلب رابطاً جديداً.
`plan_not_available`	400	هذه الخطة غير متاحة.
`product_not_available`	400	هذا المنتج غير متاح.
`setting_out_of_range`	400	قيمة الإعداد خارج النطاق المسموح.
`setting_unknown`	400	مفتاح الإعداد هذا غير معروف.
`totp_invalid`	400	رمز التحقق غير صحيح.
`turnstile_failed`	400	فشل فحص مكافحة الروبوتات — أعد تحميل الصفحة وحاول مرة أخرى.
`webhook_invalid`	400	توقيع أو محتوى الـ webhook غير صالح.
`api_key_invalid`	401	مفتاح الـ API هذا غير صالح.
`api_key_revoked`	401	أُلغي مفتاح الـ API هذا.
`session_expired`	401	انتهت صلاحية جلستك — سجّل الدخول مرة أخرى.
`unauthorized`	401	يلزم تسجيل الدخول للمتابعة.
`payment_required`	402	لم يتم دفع ثمن هذا الطلب بعد.
`quota_exceeded`	402	نفدت حصة الصور لدى المؤسسة — رقِّ الخطة أو اشترِ حزمة رصيد.
`review_quota_exceeded`	402	لم تبقَ مراجعات خبير في فترة الفوترة هذه.
`seat_limit`	402	لا مقاعد شاغرة في خطتك — رقِّها أو أزل عضواً.
`subscription_required`	402	يلزم اشتراك فعّال — اختر خطة من صفحة الفوترة.
`api_disabled`	403	الـ API غير مفعّل لهذه المؤسسة.
`forbidden`	403	ليست لديك صلاحية الوصول إلى هذا.
`org_forbidden`	403	دورك في هذه المؤسسة لا يسمح بذلك.
`org_suspended`	403	هذه المؤسسة موقوفة — تواصل مع الدعم.
`totp_required`	403	هذا الإجراء يتطلب عامل تحقق ثانٍ.
`client_not_found`	404	لم نعثر على هذا الزبون.
`handoff_not_found`	404	انتهت صلاحية هذا الرابط — اعرض رمز QR جديداً وامسحه من جديد.
`intake_disabled`	404	رابط الاستقبال هذا غير مفعّل.
`not_found`	404	لم نعثر على هذا العنصر.
`org_not_found`	404	لم نعثر على هذه المؤسسة.
`photo_not_found`	404	لم نعثر على هذه الصورة.
`spec_not_found`	404	هذا المستند غير معروف.
`upload_not_found`	404	لم يتم العثور على هذا الملف المرفوع أو انتهت صلاحيته.
`already_paid`	409	تم دفع ثمن هذا الطلب بالفعل.
`attempts_exhausted`	409	بلغت الحد الأقصى لعدد المحاولات — سيراجع أحد المختصين هذا الطلب.
`invalid_state`	409	هذا الإجراء غير ممكن في الحالة الحالية للطلب.
`last_owner`	409	يجب أن يبقى للمؤسسة مالك واحد على الأقل.
`org_slug_taken`	409	اسم الرابط هذا مستخدم بالفعل.
`owner_of_organisation`	409	أنت المالك الوحيد لمؤسسة. اجعل عضواً آخر مالكاً لها أو احذف المؤسسة قبل حذف حسابك.
`product_has_sales`	409	لا يمكن حذف منتج له مبيعات — عطّله بدلاً من ذلك.
`spec_switch_not_allowed`	409	يمكن تغيير المستند مرة واحدة فقط، إلى مستند بسعر مساوٍ أو أقل.
`upload_already_used`	409	تم استخدام هذا الملف المرفوع في طلب آخر بالفعل.
`invite_expired`	410	انتهت صلاحية هذه الدعوة — اطلب من المالك إرسال دعوة جديدة.
`export_too_large`	413	حجم التصدير يتجاوز 2 GB — اختر نطاق تواريخ أقصر.
`image_url_invalid`	422	يجب أن يكون عنوان الصورة رابط http(s) عاماً.
`image_url_unreachable`	422	تعذّر جلب الصورة من هذا العنوان.
`logo_invalid`	422	يجب أن يكون الشعار بصيغة PNG أو JPEG وبحجم لا يتجاوز 1 MB.
`org_slug_reserved`	422	لا يمكن استخدام اسم الرابط هذا.
`validation_error`	422	الطلب غير صالح.
`webhook_url_invalid`	422	يجب أن يكون عنوان الـ webhook رابط https عاماً.
`rate_limited`	429	طلبات كثيرة جداً — يرجى الانتظار قليلاً.
`test_key_daily_limit`	429	بلغ مفتاح الاختبار حدّه اليومي — استخدم مفتاحاً حقيقياً للمزيد.
`internal_error`	500	حدث خطأ ما من جانبنا.
`maintenance`	503	تاك فوتو تحت الصيانة لفترة قصيرة — يرجى المحاولة بعد دقائق.

الـ Webhooks

اضبط رابط webhook على مفتاحك، أو callback_url على صورة واحدة، فنرسل إليك الصورة لحظة استقرار حالتها — بلا استطلاع متكرر.

الأحداث

photo.completed: اكتملت الصورة وملفاتها جاهزة.
photo.failed: تعذّر إنتاج الصورة. لم يُخصم شيء.
review.approved: وافق خبير المراجعة على الصورة.
review.rejected: رفض خبير المراجعة الصورة؛ السبب في review.reason.

الترويسات

X-Event: اسم الحدث.
X-Delivery-Id: معرّف هذا الإرسال.
X-Signature: التوقيع، متى صار لمفتاحك سرّ webhook.

إعادة المحاولة

ردّ بأي حالة 2xx خلال 10 ثوانٍ. أي شيء آخر — حالة أخرى أو تحويل أو عدم الرد في الوقت — محاولة فاشلة، ويُعاد الإرسال:

المحاولة 1: فوراً
المحاولة 2: بعد دقيقة من سابقتها
المحاولة 3: بعد 5 دقائق من سابقتها
المحاولة 4: بعد 30 دقيقة من سابقتها
المحاولة 5: بعد ساعتان من سابقتها

إن فشلت المحاولة 5 أيضاً، يُتخلّى عن الإرسال.

الحمولة

طلب POST بجسم JSON: الحدث، ووقته، والصورة كما تعيدها قراءتها عبر الـ API تماماً. قد يصل الحدث نفسه أكثر من مرة، فأزل التكرار بمعرّفه id.

{
  "id": "evt_00000000000000000000000000000000",
  "event": "photo.completed",
  "created_at": "2026-01-01T12:00:00Z",
  "data": {
    "checks": [
      {
        "code": "string",
        "hint": "string",
        "result": "string",
        "value": 0
      }
    ],
    "created_at": "2026-01-01T12:00:00Z",
    "credits_charged": 0,
    "crop": {
      "rotation_deg": 0,
      "scale": 0,
      "x0": 0,
      "x1": 0,
      "y0": 0,
      "y1": 0
    },
    "expires_at": "2026-01-01T12:00:00Z",
    "id": "string",
    "outputs": {
      "digital": {
        "bytes": 0,
        "height": 0,
        "url": "string",
        "width": 0
      },
      "sheets": {
        "key": {
          "jpeg": "string",
          "pdf": "string"
        }
      }
    },
    "review": {
      "reason": "string",
      "status": "string"
    },
    "spec": {
      "id": "string",
      "version": 0
    },
    "status": "processing"
  }
}

تحقّق من التوقيع

شكل X-Signature هو t=<timestamp>,v1=<hex>. احسب HMAC-SHA256 بسرّ الـ webhook على الطابع الزمني ثم نقطة ثم جسم الطلب الخام، وقارنه بـ v1 بمقارنة ثابتة الزمن، وارفض الإرسال إن اختلفا أو إن ابتعد الطابع الزمني عن ساعتك أكثر من 300 ثانية.

import hashlib
import hmac
import time

TOLERANCE_S = 300


def verify(secret: str, header: str, raw_body: bytes) -> bool:
    """header is X-Signature; raw_body is the request body before any JSON parsing."""
    parts = dict(item.split("=", 1) for item in header.split(",") if "=" in item)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1 or abs(time.time() - int(t)) > TOLERANCE_S:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_S = 300;

/** header is X-Signature; rawBody is the request body as a Buffer, before any JSON parsing. */
export function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((item) => item.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1 || Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex"));
  const given = Buffer.from(parts.v1);
  return expected.length === given.length && timingSafeEqual(expected, given);
}

<?php
const TOLERANCE_S = 300;

// $header is X-Signature; $rawBody is file_get_contents('php://input'), before json_decode.
function verify(string $secret, string $header, string $rawBody): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (!ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > TOLERANCE_S) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $v1);
}

الأسعار

خطط شهرية للمفاتيح الحية. المفاتيح التجريبية مجانية دائماً.

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

كل تغيير في /api/v1. أي تغيير كاسر يأتي بإصدار جديد فقط، ويبقى الإصدار القديم عاملاً 12 شهراً.

v1 — 2026-09

الإصدار الأول من /api/v1.

نقاط النهاية (Endpoints)

GET /specs وGET /specs/{spec_id} — كتالوج مواصفات المستندات.
POST /photos — رفع صورة (multipart أو image_url موجَّه)؛ إجابة متزامنة خلال 15 ثانية أو 202 مع Location لمتابعة النتيجة.
GET /photos/{photo_id} — حالة الصورة ومخرجاتها.
POST /photos/{photo_id}/adjust — تعديل القص/التكبير مجاناً على النتيجة الجاهزة.
DELETE /photos/{photo_id} — حذف فوري للصورة وملفاتها.
GET /usage — الحصة المتبقية والاستهلاك الحالي.
GET /content/legal/{name} وGET /content/changelog/{name} — الوثائق القانونية وسجل التغييرات بصيغة Markdown.

المصادقة

كل نداء موثَّق يحتاج Authorization: Bearer <مفتاحك>. مفاتيح pk_live_... تُخصم من حصتك وتُنتج ملفات حقيقية؛ مفاتيح pk_test_... مجانية بالكامل وتُنتج معاينة موسومة بعلامة اختبار، لتجربة التكامل قبل التشغيل الفعلي.

الـ Webhooks

إن ضبطت webhook_url لمفتاحك (أو callback_url لصورة واحدة)، تصلك أحداث photo.completed، photo.failed، review.approved وreview.rejected موقَّعة بـ HMAC-SHA256 في ترويسة X-Signature، مع إعادة محاولة تلقائية حتى 5 مرات عند فشل التسليم.

الحدود

كل استجابة موثَّقة تحمل X-RateLimit-Limit، X-RateLimit-Remaining، X-RateLimit-Reset وX-Quota-Remaining. تجاوز حصة الخطة الشهرية يوقف الخدمة أو يُفوتَر كتجاوز، حسب إعداد خطتك.

ابنِ الربط كاملاً مجاناً

المفاتيح التجريبية مجانية وتعيد معاينة بعلامة مائية، فيعمل كل شيء قبل أول صورة مدفوعة.

احصل على مفتاح تجريبي

صور مستندات مطابقة للشروط بطلب API واحد

بدء سريع

احصل على مفتاح تجريبي

أرسل صورة

اقرأ النتيجة

أمثلة برمجية

مرجع الـ API

/photos

جسم الطلب application/json

جسم الطلب multipart/form-data

الردود

/photos/{photo_id}

المعاملات

الردود

المعاملات

الردود

/photos/{photo_id}/adjust

المعاملات

جسم الطلب application/json

الردود

/specs

المعاملات

الردود

/specs/{spec_id}

المعاملات

الردود

/usage

الردود

رموز الفحوصات والأخطاء

رموز الفحوصات

رموز الأخطاء

الـ Webhooks

الأحداث

الترويسات

إعادة المحاولة

الحمولة

تحقّق من التوقيع

الأسعار

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

v1 — 2026-09

نقاط النهاية (Endpoints)

المصادقة

الـ Webhooks

الحدود

ابنِ الربط كاملاً مجاناً

`/photos`

جسم الطلب `application/json`

جسم الطلب `multipart/form-data`

`/photos/{photo_id}`

`/photos/{photo_id}/adjust`

جسم الطلب `application/json`

`/specs`

`/specs/{spec_id}`

`/usage`