> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# الحملات الإعلانية

> أنشئ الحملات الإعلانية التي لا تستند إلى منشور، مثل حملات البحث، واقرأها وحدّثها.

الحملة إعلان لا يبدأ من أحد منشوراتك. استخدمها لتنسيقات مثل إعلانات البحث، حيث تحدد الميزانية واستراتيجية عروض الأسعار والاستهداف، وتتولى الشبكة إنشاء الإعلانات.

للترويج لمنشور نشرته بالفعل، استخدم [تعزيز المنشور](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md) بدلًا من ذلك.

> [!NOTE]
>
> تقبل Google الحملات. راجع [حملات بحث Google](https://www.ayrshare.com/docs/apis/ads/google/search-campaigns.md) و[حملات Google Performance Max](https://www.ayrshare.com/docs/apis/ads/google/performance-max-campaigns.md) لمعرفة ما يخص Google. وترفض الشبكات الأخرى طلب الحملة مع `code: 101`، ويوضح `details` السبب. على Facebook مثلًا، تكون الرسالة `campaignCreation is not supported on facebook.`

## نقاط النهاية

| الطريقة | المسار | الوظيفة |
| - | - | - |
| `POST` | `/ads/{platform}/campaigns` | إنشاء حملة |
| `GET` | `/ads/{platform}/campaigns/{id}` | الحصول على حملة واحدة |
| `PUT` | `/ads/{platform}/campaigns/{id}` | تعديل حملة واحدة |

`{platform}` هي الشبكة الإعلانية. و`{id}` هو معرّف الحملة الذي أُعيد عند إنشائها. لا يمكنك قراءة وتعديل سوى الحملات التي أُنشئت عبر Ayrshare بواسطة الملف الشخصي للمستخدم نفسه.

## معاملات الترويسة

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

**Idempotency-Key** `string` *required*

مطلوب لإنشاء حملة. أرسل قيمة فريدة جديدة، مثل UUID، لكل حملة جديدة. إذا كررت طلبًا بالمفتاح نفسه، يُعيد Ayrshare الاستجابة الأولى مع العلامة `idempotentReplayed: true`، ولا يُنشئ شيئًا جديدًا. يمكنك بدلًا من ذلك إرسال المفتاح في الجسم باسم `idempotencyKey`. وإذا أرسلتهما معًا، فيجب أن يتطابقا.

## إنشاء حملة

`POST /ads/{platform}/campaigns`

تبدأ الحملات الجديدة بالحالة `paused` ما لم ترسل `status: "active"`، لذا لا يُنفق أي مبلغ حتى تختار البدء.

**accountId** `string` *required*

حساب الإعلانات الذي ستُنشأ فيه الحملة.

**name** `string` *required*

اسم الحملة، من 1 إلى 255 حرفًا.

**type** `string` *required*

نوع الحملة: `search` أو `performanceMax`. تدعم كل شبكة بعض الأنواع فقط. يُعيد النوع الذي لا تدعمه الشبكة الرمز `code: 101` مع قائمة بالأنواع المدعومة.

**budget** `object` *required*

**السمات الفرعية**

**amount** `number` *required*

المبلغ المطلوب إنفاقه يوميًا، بحد أقصى منزلتين عشريتين.

**type** `string` *required*

`daily`.

**currency** `string`

رمز ISO 4217، مثل `USD`. القيمة الافتراضية هي عملة حساب الإعلانات. لا تقبله إلا بعض الشبكات.

**bidding** `object` *required*

**السمات الفرعية**

**strategy** `string` *required*

`maximizeConversions` أو `maximizeConversionValue` أو `targetCpa` أو `targetRoas` أو `maximizeClicks` أو `manualCpc`. تدعم كل شبكة بعض الاستراتيجيات فقط.

**targetCpa** `number`

التكلفة المستهدفة لكل إجراء. مطلوب مع `targetCpa`، ولا يُقبل مع أي استراتيجية أخرى.

**targetRoas** `number`

العائد المستهدف على الإنفاق الإعلاني، مثل `3.5` لنسبة 350%. مطلوب مع `targetRoas`، ولا يُقبل مع أي استراتيجية أخرى.

**euPoliticalAdvertising** `boolean` *required*

ما إذا كانت الحملة إعلانًا سياسيًا في الاتحاد الأوروبي. يجب عليك إرساله دائمًا. لا يملؤه Ayrshare نيابةً عنك أبدًا.

**schedule** `object`

**السمات الفرعية**

**start** `string`

وقت البدء: تاريخ ISO (`2026-11-01`) أو تاريخ ووقت ISO مع `Z` أو إزاحة زمنية (`2026-11-01T09:00:00Z`). القيمة الافتراضية هي الآن.

**end** `string`

وقت التوقف، بالتنسيق نفسه المستخدم في `start`. يجب أن يكون بعد `start`، أو بعد الوقت الحالي إذا حذفت `start`. احذفه لتعمل الحملة دون تاريخ انتهاء. وتقبل الشبكة التي تجدول أيامًا كاملة، مثل Google، أيضًا `end` في اليوم نفسه الذي يقع فيه `start`، لحملة مدتها يوم واحد.

**targeting** `object`

تدعم كل شبكة بعض خيارات الاستهداف فقط. يُعيد الحقل الذي لا تدعمه الشبكة الرمز `code: 101`.

**السمات الفرعية**

**locations** `string[]`

معرّفات المواقع الخاصة بالشبكة.

**languages** `string[]`

معرّفات اللغات الخاصة بالشبكة.

**status** `string` (default: paused)

`active` أو `paused`.

**platformOptions** `object`

خيارات لشبكة واحدة فقط، تحت اسم تلك الشبكة، مثل `{ "facebook": { ... } }`. تُعيد الخيارات الخاصة بأي شبكة أخرى الرمز `code: 101`.

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10" \
-X POST https://api.ayrshare.com/api/ads/google/campaigns \
-d '{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}'
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/ads/google/campaigns", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
  },
  body: JSON.stringify({
    "accountId": "123-456-7890",
    "name": "Spring search",
    "type": "search",
    "budget": { "amount": 20, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/spring",
        "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
      }
    }
  })
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {
    "Authorization": "Bearer API_KEY",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10",
}

payload = {
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": False,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}

r = requests.post("https://api.ayrshare.com/api/ads/google/campaigns", headers=headers, json=payload)

print(r.json())
```

```php PHP theme={"system"}
<?php
$payload = <<<'JSON'
{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}
JSON;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.ayrshare.com/api/ads/google/campaigns",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
    ],
    CURLOPT_POSTFIELDS => $payload
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error: " . $err;
} else {
    echo $response;
}
?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
        client.DefaultRequestHeaders.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10");

        var payload = """
            {
              "accountId": "123-456-7890",
              "name": "Spring search",
              "type": "search",
              "budget": { "amount": 20, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/spring",
                  "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
                }
              }
            }
            """;

        var response = await client.PostAsync(
            "https://api.ayrshare.com/api/ads/google/campaigns",
            new StringContent(payload, Encoding.UTF8, "application/json"));
        var content = await response.Content.ReadAsStringAsync();

        Console.WriteLine(content);
    }
}
```

```go Go theme={"system"}
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := `{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}`

    req, _ := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/google/campaigns", strings.NewReader(payload))
    req.Header.Add("Authorization", "Bearer API_KEY")
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateCampaign {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "accountId": "123-456-7890",
              "name": "Spring search",
              "type": "search",
              "budget": { "amount": 20, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/spring",
                  "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
                }
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.ayrshare.com/api/ads/google/campaigns"))
            .header("Authorization", "Bearer API_KEY")
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={"system"}
require 'net/http'
require 'uri'

uri = URI.parse('https://api.ayrshare.com/api/ads/google/campaigns')

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer API_KEY'
request['Content-Type'] = 'application/json'
request['Idempotency-Key'] = '6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10'
request.body = <<~JSON
  {
    "accountId": "123-456-7890",
    "name": "Spring search",
    "type": "search",
    "budget": { "amount": 20, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/spring",
        "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
      }
    }
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

يُعيد الإنشاء الناجح `status: "success"` و`campaignId` وحالة الحملة نفسها في `campaignStatus` (`active` أو `paused`). ويُعيد الحصول والتحديث الاستجابة بالطريقة نفسها.

## الحصول على حملة

`GET /ads/{platform}/campaigns/{id}`

يُعيد الحملة كما تُبلغ عنها الشبكة. تُعيد الحملة التي لا تخصك، أو غير الموجودة، الرمز `code: 400`.

## تحديث حملة

`PUT /ads/{platform}/campaigns/{id}`

أرسل حقلًا واحدًا على الأقل من هذه الحقول. لا يمكنك تغيير `type` أو `accountId` أو `euPoliticalAdvertising` بعد إنشاء الحملة.

**name** `string`

الاسم الجديد للحملة.

**status** `string`

`active` أو `paused`. لا يُحظر الطلب الذي يرسل `status: "paused"` فقط عندما يكون Ayrshare قد أوقف الإعلانات مؤقتًا على تلك الشبكة. لكنه لا يزال يتطلب شبكة مرتبطة، وقد يفشل إذا كانت الشبكة نفسها معطّلة.

**budget** `object`

`{ "amount": number }`: المبلغ الجديد المطلوب إنفاقه يوميًا.

**schedule** `object`

`{ "end": string }`: تاريخ الانتهاء الجديد، بالتنسيق نفسه المستخدم في `schedule.start`. يجب أن يكون بعد تاريخ بدء الحملة. وتقبل الشبكة التي تجدول أيامًا كاملة، مثل Google، أيضًا اليوم نفسه الذي تبدأ فيه الحملة.

## الأخطاء

تحمل هذه الأخطاء رمز `code` من Ayrshare:

| الرمز | متى |
| - | - |
| `101` | الطلب غير صالح، أو الشبكة لا تدعم الحملات أو نوع الحملة هذا، أو مفتاح عدم التكرار مفقود. يوضح `details` أيّها. يتحقق Ayrshare من المفتاح بعد أن يتأكد من أن الشبكة مرتبطة، لذا يتلقى الملف الشخصي غير المرتبط خطأ "not linked" (غير مرتبط) أولًا. |
| `400` | الحملة لا تخصك أو غير موجودة. |
| `424` | الإعلانات على هذه الشبكة غير متاحة مؤقتًا. |

قد يُعيد الإنشاء أيضًا إحدى حالات HTTP التالية. لا يحتوي جسمها على `code`، بل على `{ "action": "createAdCampaign", "status": "error", "message": "..." }` فقط:

| حالة HTTP | متى |
| - | - |
| `409` | استُخدم مفتاح عدم التكرار مع طلب مختلف، أو أن الطلب الذي يحمل هذا المفتاح لا يزال قيد المعالجة. لا تُعِد المحاولة بمفتاح جديد. تحقق من حساب الإعلانات أولًا. |
| `503` | لم يتمكن Ayrshare من حجز مفتاح عدم التكرار بأمان، لذا لم يُنشأ أي شيء. أعد المحاولة لاحقًا بالمفتاح نفسه. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.