# الأرقام

أرقام واتساب المرسِلة وحالتها.

## عرض أرقام واتساب

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

الأرقام التي ترسل منها مساحة العمل، مع تقييم الجودة والحد اليومي وهل يستطيع الرقم الإرسال الآن. استخدم `id` في حقل `from` عند الإرسال.

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

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.

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

صفحة من الأرقام.

```json
{
  "object": "list",
  "data": [
    {
      "id": "num_3",
      "object": "phone_number",
      "phone_number": "+966112345678",
      "display_name": "string",
      "name_status": "string",
      "is_default": false,
      "quality_rating": "string",
      "messaging_limit_tier": "TIER_1K",
      "daily_conversation_limit": 0,
      "can_send": false,
      "cannot_send_reason": "string",
      "created_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}
```

### الاستجابة 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"
  }
}
```

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

`parameter_invalid`, `rate_limited`

## جلب رقم

```
GET https://api.saei.automize.sa/v1/numbers/{id}
```

رقم واحد وحالته. عندما تكون `can_send` هي `false` يوضّح `cannot_send_reason` السبب (غير متصل، الرمز يحتاج إعادة ربط…)؛ أصلحه من الإعدادات ← واتساب.

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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

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

الرقم.

```json
{
  "id": "num_3",
  "object": "phone_number",
  "phone_number": "+966112345678",
  "display_name": "متجر النخبة",
  "name_status": "APPROVED",
  "is_default": true,
  "quality_rating": "green",
  "messaging_limit_tier": "TIER_1K",
  "daily_conversation_limit": 1000,
  "can_send": true,
  "cannot_send_reason": null,
  "created_at": "2026-06-01T10:00:00Z"
}
```

### الاستجابة 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"
  }
}
```

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

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `rate_limited`