# الحساب والاستهلاك

تحقّق من مفتاحك وما يستطيع فعله.

## تحقّق من مفتاح API

```
GET https://api.saei.automize.sa/v1/me
```

يُرجع مساحة العمل ووضع المفتاح وصلاحياته وحد الطلبات. أسرع طريقة للتأكد من أن المفتاح يعمل.

- الصلاحية: أي مفتاح صالح
- يعمل في وضع الاختبار

### الاستجابة 200

المفتاح يعمل.

```json
{
  "object": "api_key_context",
  "livemode": false,
  "workspace": {
    "id": "ws_12",
    "name": "Riyadh Coffee"
  },
  "api_key": {
    "id": "key_7",
    "name": "Order system",
    "prefix": "sk_test_Ab12Cd",
    "scopes": [
      "messages:send",
      "messages:read",
      "webhooks:read",
      "webhooks:write"
    ],
    "expires_at": null
  },
  "rate_limit": {
    "limit": 60,
    "window_seconds": 60
  }
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 429

طلبات كثيرة جدًا. انتظر عدد الثواني الموجود في `Retry-After`.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الأخطاء المحتملة

`api_key_missing`, `api_key_invalid`, `api_key_revoked`, `api_key_expired`, `rate_limited`

## جلب الاستهلاك

```
GET https://api.saei.automize.sa/v1/usage
```

ما استهلكته مساحة العمل في فترة الفوترة الحالية مقارنة بباقتها (الرسائل التسويقية والخدمية، الحملات، جهات الاتصال، القوالب، التدفقات، الأرقام)، وكيف استُدعيت الواجهة في وضع هذا المفتاح خلال آخر 30 يومًا.

تحقق من `remaining` قبل إرسال كبير لتتجنب `quota_exceeded`. تكون `limit` و`remaining` بقيمة `null` للرصيد غير المحدود.


- الصلاحية: usage:read
- يعمل في وضع الاختبار

### الاستجابة 200

تقرير الاستهلاك.

```json
{
  "object": "usage",
  "period": {
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-11-01T00:00:00Z"
  },
  "allowances": [
    {
      "key": "marketing_messages_month",
      "type": "monthly",
      "used": 4120,
      "limit": 10000,
      "remaining": 5880
    },
    {
      "key": "service_messages_month",
      "type": "monthly",
      "used": 18230,
      "limit": null,
      "remaining": null
    },
    {
      "key": "contacts",
      "type": "total",
      "used": 9214,
      "limit": 25000,
      "remaining": 15786
    }
  ],
  "api": {
    "livemode": true,
    "window_days": 30,
    "requests": 48213,
    "errors": 212,
    "error_rate": 0.0044,
    "by_day": [
      {
        "date": "2026-09-30",
        "requests": 1804,
        "errors": 6
      }
    ]
  }
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`rate_limited`