ShamCash API

مرجع HTTP للحسابات المرتبطة.

كل المسارات أدناه نسبية إلى هذا الرابط الأساسي.

HTTP

Base URL:
https://api.shamcash-api.com/v1

Authorization:
Authorization: Bearer <api_token>

المصادقة

يجب أن يتضمن كل طلب مفتاح API صالحا صادرا من لوحة تحكم المنصة.

Header

Authorization: Bearer <api_token>

إذا كان المفتاح مفقودا أو غير صالح أو ملغى، يرجع API الحالة status: "error" مع code مناسب و message مفهوم.

القواعد العامة

الإصدارات: مقطع v1 هو الإصدار الرئيسي الحالي. التغييرات غير المتوافقة ستصدر تحت v2 و v3 وهكذا.

نوع المحتوى: تستخدم الاستجابات application/json; charset=utf-8. أجسام الطلبات، إذا أضيفت لاحقا، يجب أن تستخدم نفس النوع ما لم يوثق غير ذلك.

المناطق الزمنية: لمعاملات /transactions، يتم تفسير start_at و end_at بتوقيت Asia/Damascus ما لم ترسل قيمة ISO 8601 كاملة مع إزاحة صريحة. ترجع كائنات المعاملات occurred_at كتاريخ ISO 8601 مع إزاحة، مثل 2026-04-16T01:22:21+03:00.

دورة حياة الحساب: كل عنصر ضمن /accounts هو حساب ShamCash ربطه المستخدم على المنصة. له status، active أو inactive، و subscription_expires_at اختياري يصف متى ينتهي وصول API لهذا الربط. إذا طلب المستخدم /balances أو /transactions عندما يكون الربط inactive أو لا يوجد اشتراك أو انتهت فترة الاشتراك، يرجع API الرمز SUBSCRIPTION_UNAVAILABLE.

شكل الاستجابة

تستخدم كل استجابة الشكل العلوي التالي.

JSON

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Accounts retrieved successfully.",
  "data": {}
}

Name	النوع	الوصف
`status`	string	"success" or "error"
`code`	string	Machine-readable outcome.
`message`	string	Human-readable summary. On success, a short confirmation. On error, what went wrong and what the user can do next.
`data`	mixed	Payload on success. On error often null or [] depending on endpoint.

قواعد النجاح: status is "success"; code is "SUCCESS"; message briefly describes the outcome; data follows the schema described for each endpoint.

قواعد الخطأ: status is "error"; code is one of the documented error codes; message explains the failure; data is typically null or an empty array; clients should use code for branching and message for display or logging.

رموز الأخطاء

الرمز	HTTP المعتاد	المعنى
`SUCCESS`	200	Request completed successfully.
`VALIDATION_ERROR`	400	Malformed or conflicting query parameters, for example invalid date format or invalid coin_id.
`AUTH_MISSING`	401	No Authorization header or empty token.
`AUTH_INVALID`	401	Token unknown, expired, or revoked.
`FORBIDDEN`	403	Token valid but not allowed to perform this action.
`NOT_FOUND`	404	Resource not found, for example unknown account_id for this user.
`SUBSCRIPTION_UNAVAILABLE`	403	This operation is not allowed because the account has no active subscription, the subscription period has ended, the ShamCash link is inactive, or subscription data is missing. The exact situation is described in message.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Retry after the period indicated by Retry-After when present.
`FETCH_FAILED`	502	Upstream or internal data fetch failed. Safe to retry with backoff.
`INTERNAL_ERROR`	500	Unexpected server error.

قد يتم ضبط HTTP status الدقيق لرمز معين حسب النشر. استخدم status و code و message و data لمنطق العميل.

الواجهات

أمثلة

تستخدم الأمثلة كودا يعمل على الخادم. لا تضع مفاتيح API في كود المتصفح.

cURL

curl "https://api.shamcash-api.com/v1/accounts" \
  -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/json"

JavaScript

const API_BASE = "https://api.shamcash-api.com/v1";
const token = process.env.SHAMCASH_API_TOKEN;

async function listAccounts() {
  const response = await fetch(`${API_BASE}/accounts`, {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json"
    }
  });

  const payload = await response.json();

  if (!response.ok || payload.status !== "success") {
    throw new Error(`${payload.code}: ${payload.message}`);
  }

  return payload.data;
}

PHP

<?php

$apiBase = 'https://api.shamcash-api.com/v1';
$token = getenv('SHAMCASH_API_TOKEN');

$ch = curl_init($apiBase . '/accounts');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}

curl_close($ch);

$payload = json_decode($body, true);

if ($status >= 400 || ($payload['status'] ?? null) !== 'success') {
    throw new RuntimeException(($payload['code'] ?? 'ERROR') . ': ' . ($payload['message'] ?? 'Request failed'));
}

print_r($payload['data']);

Python

import os
import requests

API_BASE = "https://api.shamcash-api.com/v1"
TOKEN = os.environ["SHAMCASH_API_TOKEN"]

def shamcash_get(path, params=None):
    response = requests.get(
        f"{API_BASE}{path}",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Accept": "application/json",
        },
        params=params or {},
        timeout=30,
    )

    payload = response.json()

    if response.status_code >= 400 or payload.get("status") != "success":
        raise RuntimeError(f"{payload.get('code')}: {payload.get('message')}")

    return payload["data"]

accounts = shamcash_get("/accounts")
account_id = accounts[0]["id"]

balances = shamcash_get("/balances", {"account_id": account_id})
transactions = shamcash_get("/transactions", {
    "account_id": account_id,
    "start_at": "2026-05-25",
    "limit": 20,
})

print(accounts)
print(balances)
print(transactions)

Python client

عميل Python الرسمي لهذا API.

التثبيت

pip install shamcash

GitHub: Melchersman/shamcash

PyPI: shamcash

تحقق من استخدام الحزمة من توثيق GitHub أو PyPI.

مثال استجابة خطأ

JSON

{
  "status": "error",
  "code": "SUBSCRIPTION_UNAVAILABLE",
  "message": "This account has no active subscription. Purchase or renew a plan on shamcash-api.com to use balances and transactions.",
  "data": null
}

رسائل أخرى ممكنة لنفس الرمز:

"The subscription for this account ended on 2026-01-01. Renew on shamcash-api.com to continue."
"This ShamCash link is inactive. Reactivate it in your dashboard to continue."
"No subscription is associated with this account."

اختبار API

Bearer token

الواجهة

Query string

cURL الناتج

curl "https://api.shamcash-api.com/v1/accounts" \
  -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/json"

الاستجابة

No request sent yet.