> ## 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, дивіться в [Пошукові кампанії 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). Інші мережі відхиляють запит на кампанію з `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}` — 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[]`

Власні ID локацій мережі.

**languages** `string[]`

Власні ID мов мережі.

**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.