واجهة ChatGetz البرمجية للمطورين

البدء السريع

1. سجّل الدخول وافتح لوحة التحكم ← مفاتيح API.
2. أنشئ مفتاحًا بالصلاحيات التي تحتاجها وانسخه (يُعرض مرة واحدة فقط).
3. أرسله في ترويسة Authorization: Bearer cgk_…

curl https://www.chatgetz.uz/api/v1/account/balance \
  -H "Authorization: Bearer $CHATGETZ_API_KEY"

curl https://www.chatgetz.uz/api/v1/ai/generate \
  -H "Authorization: Bearer $CHATGETZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6f5e-order-42" \
  -d '{
    "model": "deepseek/deepseek-v4-flash",
    "prompt": "Write a 60-word description for a cotton kids hoodie",
    "instructions": "Answer in Uzbek (Latin script)."
  }'

المصادقة والصلاحيات

يجب أن يحمل كل طلب مفتاح API شخصيًا في ترويسة Authorization: Bearer cgk_… (أو X-API-Key). لكل مفتاح صلاحياته (scopes) وحد طلباته، ويمكن إلغاؤه في أي وقت.

احفظ المفاتيح على خادمك أو في إعدادات الإضافة، وليس أبدًا في شيفرة الواجهة الأمامية العامة. تحتفظ ChatGetz ببصمة SHA-256 لكل مفتاح فقط.

الحدود والأسعار

• Global Pro: طلبات API غير محدودة.
• Basic: ١٬٠٠٠ طلب شهريًا (يُعاد التعيين في اليوم الأول بتوقيت طشقند).
• لا تتوفر واجهة API للحسابات التي لم تختر خطة.
• لكل مفتاح حد خاص (10–120 طلبًا في الدقيقة). عند تجاوزه تردّ الواجهة بالرمز 429 مع ترويسة Retry-After.
• يُحتسب إنشاء النصوص بالذكاء الاصطناعي وفق قائمة الأسعار العامة: أولًا من حدك الشهري للذكاء الاصطناعي، ثم من رصيد ChatGetz.
• أرسل ترويسة Idempotency-Key مع طلبات الذكاء الاصطناعي: الطلب المُعاد بالمفتاح نفسه لا يُخصم مرتين أبدًا.

نقاط النهاية

• get/api/v1/account/balanceالخطة والرصيد ورصيد الذكاء الاصطناعي المضمَّن وحصة APIaccount:read
• get/api/v1/modelsالنماذج النصية ومدى توفرها لمفتاحكai:generate
• post/api/v1/ai/generateتوليد نص؛ يُخصم من الرصيد (من الرصيد المضمَّن أولًا)ai:generate
• get/api/v1/market/listingsإعلاناتك في ChatGetz Marketmarket:read
• post/api/v1/market/listingsإنشاء إعلان في Market (مسودة افتراضيًا)market:write
• post/api/v1/ingest/eventsاستقبال طلب أو عميل محتمل من إضافة (webhook)ingest:write
• get/api/v1/openapi.jsonمواصفة OpenAPI 3.1 لهذه الواجهة

ترسل الإضافات الطلبات والعملاء المحتملين الجدد إلى POST /api/v1/ingest/events. إعادة إرسال حدث بالقيم نفسها لـ source وtype وexternalId آمنة: يُحفظ مرة واحدة فقط.

curl https://www.chatgetz.uz/api/v1/ingest/events \
  -H "Authorization: Bearer $CHATGETZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order", "source": "woocommerce", "externalId": "1042",
    "customer": { "name": "Aziza", "phone": "+998901234567" },
    "total": { "amount": "249000", "currency": "UZS" },
    "items": [{ "name": "Hoodie", "quantity": 1, "price": "249000" }]
  }'

الأخطاء

تُعاد الأخطاء بصيغة JSON مع رمز ثابت قابل للقراءة آليًا ورسالة بالإنجليزية. اعتمد على الرمز في تكاملك.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly Basic API quota exhausted. ..."
  }
}

الإضافات

جميع الإضافات مفتوحة المصدر (متوافقة مع GPL) وتستخدم مفتاح API الخاص بك. يُحفظ المفتاح في إعدادات الإضافة، وليس في الشيفرة.