واجهة REST

واجهة Hivesigner على https://hivesigner.com/api/. تعيد حساب المستخدم الذي سجّل الدخول، وتبثّ عمليات النشر نيابةً عنه، وتستبدل الأكواد بالرموز، وتسرد التطبيقات التي تستخدم Hivesigner. تصف هذه الصفحة كل نقطة نهاية مع طلباتها وإجاباتها وأخطائها.

الطلبات والمصادقة

• العنوان الأساسي: https://hivesigner.com/api/. وكل نقطة نهاية أدناه نسبية إلى https://hivesigner.com.
• الرمز: أرسله كترويسة Authorization كما هو: Authorization: ACCESS_TOKEN. ويُقبل أيضًا البادئة Bearer . ويمكنك إرساله كذلك باسم access_token في سلسلة الاستعلام أو في الجسم، لكن الترويسة تبقيه خارج العناوين والسجلات.
• الأجسام: JSON مع Content-Type: application/json، أو نموذج (application/x-www-form-urlencoded).
• الإجابات: JSON.
• المتصفحات: تسمح الواجهة بالطلبات عبر الأصول، فيستطيع تطبيق ويب استدعاءها مباشرةً.

للحصول على رمز، راجع تسجيل الدخول باستخدام OAuth2. ولمعرفة ما يحتويه الرمز، راجع الرموز.

الأخطاء

إجابة الخطأ لها حالة HTTP للخطأ وهذا الجسم:

{
  "error": "invalid_scope",
  "error_description": "The access_token scope does not allow the following operation(s): transfer"
}

GET /api/me

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

• الطرق: GET أو POST.
• الرمز: رمز وصول، بما في ذلك رمز login يسمّي تطبيقًا.

curl https://hivesigner.com/api/me -H 'Authorization: ACCESS_TOKEN'

الإجابة، مختصرة:

{
  "user": "alice",
  "_id": "alice",
  "name": "alice",
  "account": { "id": 1370484, "name": "alice" },
  "scope": [
    "vote",
    "comment",
    "delete_comment",
    "comment_options",
    "custom_json",
    "claim_reward_balance",
    "account_update2"
  ],
  "user_metadata": { "profile": { "name": "Alice", "version": 2 } }
}

لا يسمّي /api/me التطبيق الذي أُنشئ الرمز له. وللتحقق من ذلك، فُكّ ترميز الرمز: راجع اسأل الواجهة.

POST /api/broadcast

توقّع عمليات النشر نيابةً عن مستخدم الرمز بمفتاح النشر الخاص بـ @hivesigner وتبثّها إلى Hive.

• الطريقة: POST.
• الرمز: رمز وصول posting، من التدفق بالرمز أو التدفق بالكود.
• قبل أن تعمل: يكون المستخدم قد منح حساب تطبيقك صلاحية النشر (تفعل ذلك شاشة الموافقة) ويكون حساب تطبيقك قد منح @hivesigner صلاحية النشر.
• الجسم: { "operations": [...] }، حيث تكون كل عملية [name, fields] كما على سلسلة Hive. وكل العمليات في طلب واحد تدخل في معاملة واحدة.

POST /api/broadcast HTTP/1.1
Host: hivesigner.com
Authorization: ACCESS_TOKEN
Content-Type: application/json

{
  "operations": [
    ["vote", { "voter": "alice", "author": "bob", "permlink": "my-first-post", "weight": 10000 }]
  ]
}

الطلب نفسه باستخدام curl:

curl -X POST https://hivesigner.com/api/broadcast \
  -H 'Authorization: ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[["vote",{"voter":"alice","author":"bob","permlink":"my-first-post","weight":10000}]]}'

المتابعة عملية custom_json:

{
  "operations": [
    ["custom_json", {
      "required_auths": [],
      "required_posting_auths": ["alice"],
      "id": "follow",
      "json": "[\"follow\",{\"follower\":\"alice\",\"following\":\"bob\",\"what\":[\"blog\"]}]"
    }]
  ]
}

تجيب الواجهة بمجرد أن تقبل عقدة Hive المعاملة. وresult.id هو معرّف المعاملة:

{
  "result": { "id": "TRANSACTION_ID" }
}

وعندما ترفض الشبكة المعاملة، تكون الإجابة 500 مع server_error. ويحمل error_description رسالة الشبكة ويحمل response الخطأ الخام.

ما يقبله البثّ

يسمح رمز النشر للواجهة ببثّ هذه العمليات لا غير. وفي كل واحدة، يجب أن يكون مستخدم الرمز هو الحساب المذكور في الحقل المبيّن:

• أي عملية أخرى تُرفض بـ invalid_scope. ورمز login لا يسمح بأي عملية على الإطلاق.
• عملية لحساب آخر تُرفض بـ unauthorized_client. فالرمز لا يبثّ أبدًا إلا نيابةً عن مستخدمه هو.
• account_update2 لا يمكنها تغيير غير بيانات الحساب الوصفية. وأي عملية تحمل حقل owner أو active أو posting تُرفض بـ unauthorized_client.
• custom_json: اترك required_auths فارغًا. فالواجهة توقّع بصلاحية النشر، ولذلك تفشل على الشبكة أي عملية تحتاج الصلاحية النشطة.

التحويلات وغيرها من عمليات المحفظة تحتاج المفتاح النشط للمستخدم. أرسلها بدلًا من ذلك على هيئة روابط توقيع.

POST /api/oauth2/token

تستبدل كودًا برموز، أو رمز تجديد برموز جديدة. استدعِها من خادمك فقط. راجع التدفق بالكود.

• الطريقة: POST، مع القيم في الجسم.
• الجسم: code وclient_secret، أو refresh_token وclient_secret.
• الترويسات: لا ترسل أي ترويسة Authorization.

curl -X POST https://hivesigner.com/api/oauth2/token \
  -H 'Content-Type: application/json' \
  -d '{"code": "CODE", "client_secret": "CLIENT_SECRET"}'

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 604800,
  "username": "alice"
}

كل استدعاء يعيد رمز وصول جديدًا ورمز تجديد جديدًا. ويوقّعهما @hivesigner. وexpires_in هو عمر رمز الوصول بالثواني (7 أيام).

الأخطاء: 401 invalid_grant. ويكون الوصف "The token has invalid role" عندما لا تكون القيمة المرسلة كودًا ولا رمز تجديد صالحًا. ويكون "The code or secret is not valid" عندما لا يتطابق الكود أو المفتاح السري.

POST /api/oauth2/token/revoke

تخبر Hivesigner بأن المستخدم سجّل الخروج من تطبيقك. ويتخلّص تطبيقك من الرمز بنفسه.

• الطريقة: POST.
• الرمز: رمز الوصول، في ترويسة Authorization.

curl -X POST https://hivesigner.com/api/oauth2/token/revoke -H 'Authorization: ACCESS_TOKEN'

{ "success": true }

تجري revokeToken() في حزمة JavaScript SDK هذا الاستدعاء ثم تنسى الرمز. ولإزالة وصول تطبيقك نهائيًا، يزيله المستخدم على https://hivesigner.com/authorized-apps. راجع تسجيل الخروج وإزالة الوصول.

GET /api/apps

دليل التطبيقات العام: التطبيقات التي تبثّ عبر Hivesigner، مرتّبة بحسب عدد مستخدميها. ولا يحتاج أي رمز. ويعرض https://hivesigner.com/apps القائمة نفسها.

curl https://hivesigner.com/api/apps

{
  "updated_at": "2026-09-19T06:00:00.000Z",
  "building": false,
  "window_days": 7,
  "featured": ["myapp"],
  "apps": [
    {
      "username": "myapp",
      "name": "My App",
      "about": "A short description from the app's profile.",
      "website": "https://myapp.example",
      "site": "ok",
      "users": 412,
      "requests": 9310,
      "first_seen": "2026-08-01",
      "last_seen": "2026-09-19",
      "new": false
    }
  ]
}

قد تبقى الإجابة في ذاكرة مؤقتة حتى 5 دقائق. وقبل بناء الدليل أول مرة، تجيب الواجهة بـ 503 مع unavailable. أعد المحاولة لاحقًا.

الأسماء والأوصاف ينشرها كل حساب تطبيق بنفسه. ولا يتحقق Hivesigner من أي منها.