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

# Campanhas de anúncios

> Crie, leia e atualize campanhas de anúncios que não partem de uma publicação, como campanhas de pesquisa.

Uma campanha é um anúncio que não parte de uma das suas publicações. Use-a para formatos como anúncios de pesquisa, em que você define um orçamento, uma estratégia de lances e a segmentação, e a rede cria os anúncios.

Para promover uma publicação que você já publicou, use [Impulsionar publicação](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md).

> [!NOTE]
>
> O Google aceita campanhas. Veja [Campanhas de pesquisa do Google](https://www.ayrshare.com/docs/apis/ads/google/search-campaigns.md) e [Campanhas Performance Max do Google](https://www.ayrshare.com/docs/apis/ads/google/performance-max-campaigns.md) para o que é específico do Google. As outras redes recusam uma solicitação de campanha com `code: 101`, e `details` informa o motivo. No Facebook, por exemplo, a mensagem é `campaignCreation is not supported on facebook.`

## Endpoints

| Método | Caminho | O que faz |
| - | - | - |
| `POST` | `/ads/{platform}/campaigns` | Cria uma campanha |
| `GET` | `/ads/{platform}/campaigns/{id}` | Obtém uma campanha |
| `PUT` | `/ads/{platform}/campaigns/{id}` | Altera uma campanha |

`{platform}` é a rede de anúncios. `{id}` é o ID da campanha retornado quando você a criou. Você só pode ler e alterar campanhas criadas pela Ayrshare pelo mesmo perfil de usuário.

## Parâmetros de cabeçalho

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

Obrigatório para criar uma campanha. Envie um novo valor único, como um UUID, para cada nova campanha. Se você repetir uma solicitação com a mesma chave, a Ayrshare retorna a primeira resposta, marcada com `idempotentReplayed: true`, e não cria nada novo. Você também pode enviar a chave no corpo como `idempotencyKey`. Se enviar as duas, elas devem ser iguais.

## Criar uma campanha

`POST /ads/{platform}/campaigns`

Novas campanhas começam como `paused`, a menos que você envie `status: "active"`, então nada é gasto até que você decida iniciar.

**accountId** `string` *required*

A conta de anúncios na qual criar a campanha.

**name** `string` *required*

O nome da campanha, de 1 a 255 caracteres.

**type** `string` *required*

O tipo de campanha: `search` ou `performanceMax`. Cada rede suporta apenas alguns tipos. Um tipo que a rede não suporta responde `code: 101` e lista os tipos suportados.

**budget** `object` *required*

**propriedades**

**amount** `number` *required*

Quanto gastar por dia, com no máximo duas casas decimais.

**type** `string` *required*

`daily`.

**currency** `string`

Código ISO 4217, como `USD`. O padrão é a moeda da conta de anúncios. Apenas algumas redes o aceitam.

**bidding** `object` *required*

**propriedades**

**strategy** `string` *required*

`maximizeConversions`, `maximizeConversionValue`, `targetCpa`, `targetRoas`, `maximizeClicks` ou `manualCpc`. Cada rede aceita apenas algumas estratégias.

**targetCpa** `number`

Custo por ação desejado. Obrigatório com `targetCpa` e não aceito com nenhuma outra estratégia.

**targetRoas** `number`

Retorno sobre o investimento em anúncios desejado, por exemplo `3.5` para 350%. Obrigatório com `targetRoas` e não aceito com nenhuma outra estratégia.

**euPoliticalAdvertising** `boolean` *required*

Se a campanha é publicidade política na UE. Você deve sempre enviá-lo. A Ayrshare nunca o preenche por você.

**schedule** `object`

**propriedades**

**start** `string`

Quando iniciar: uma data ISO (`2026-11-01`) ou uma data e hora ISO com `Z` ou um deslocamento (`2026-11-01T09:00:00Z`). O padrão é agora.

**end** `string`

Quando parar, no mesmo formato de `start`. Deve ser posterior a `start`, ou posterior a agora se você omitir `start`. Omita-o para veicular sem data de término. Uma rede que programa dias inteiros, como o Google, também aceita um `end` no mesmo dia de `start`, para uma campanha de um dia.

**targeting** `object`

Cada rede suporta apenas algumas opções de segmentação. Um campo que a rede não suporta responde `code: 101`.

**propriedades**

**locations** `string[]`

Os IDs de localização da própria rede.

**languages** `string[]`

Os IDs de idioma da própria rede.

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

`active` ou `paused`.

**platformOptions** `object`

Opções para uma única rede, sob o nome dessa rede, por exemplo `{ "facebook": { ... } }`. Opções para qualquer outra rede respondem `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
```

Uma criação bem-sucedida responde `status: "success"`, o `campaignId` e o estado da própria campanha como `campaignStatus` (`active` ou `paused`). A obtenção e a atualização respondem da mesma forma.

## Obter uma campanha

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

Retorna a campanha conforme informada pela rede. Uma campanha que não é sua, ou que não existe, responde `code: 400`.

## Atualizar uma campanha

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

Envie pelo menos um destes campos. Você não pode alterar `type`, `accountId` ou `euPoliticalAdvertising` depois de criar a campanha.

**name** `string`

O novo nome da campanha.

**status** `string`

`active` ou `paused`. Uma solicitação que envia apenas `status: "paused"` não é bloqueada quando a Ayrshare pausou os anúncios nessa rede. Ela ainda precisa de uma rede vinculada e ainda pode falhar se a própria rede estiver fora do ar.

**budget** `object`

`{ "amount": number }`: o novo valor a gastar por dia.

**schedule** `object`

`{ "end": string }`: a nova data de término, no mesmo formato de `schedule.start`. Deve ser posterior ao início da campanha. Uma rede que programa dias inteiros, como o Google, também aceita o mesmo dia do início.

## Erros

Estes erros trazem um `code` da Ayrshare:

| Código | Quando |
| - | - |
| `101` | A solicitação é inválida, a rede não suporta campanhas ou este tipo de campanha, ou a chave de idempotência está ausente. `details` informa qual. A Ayrshare verifica a chave depois de confirmar que a rede está vinculada, então um perfil não vinculado recebe primeiro o erro "not linked" (não vinculado). |
| `400` | A campanha não é sua ou não existe. |
| `424` | Os anúncios nesta rede estão temporariamente indisponíveis. |

Uma criação também pode responder com um destes status HTTP. O corpo não tem `code`, apenas `{ "action": "createAdCampaign", "status": "error", "message": "..." }`:

| Status HTTP | Quando |
| - | - |
| `409` | A chave de idempotência foi usada com uma solicitação diferente, ou a solicitação com essa chave ainda está em andamento. Não tente novamente com uma nova chave. Verifique primeiro a conta de anúncios. |
| `503` | A Ayrshare não conseguiu reservar a chave de idempotência com segurança, então nada foi criado. Tente novamente mais tarde com a mesma chave. |


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