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

# Campañas publicitarias

> Crea, consulta y actualiza campañas publicitarias que no parten de una publicación, como las campañas de búsqueda.

Una campaña es un anuncio que no parte de una de tus publicaciones. Úsala para formatos como los anuncios de búsqueda, en los que defines un presupuesto, una estrategia de puja y la segmentación, y la red crea los anuncios.

Para promocionar una publicación que ya publicaste, usa [Impulsar publicación](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md) en su lugar.

> [!NOTE]
>
> Google acepta campañas. Consulta [Campañas de búsqueda de Google](https://www.ayrshare.com/docs/apis/ads/google/search-campaigns.md) y [Campañas Performance Max de Google](https://www.ayrshare.com/docs/apis/ads/google/performance-max-campaigns.md) para ver lo específico de Google. Las demás redes rechazan una solicitud de campaña con `code: 101`, y `details` indica el motivo. En Facebook, por ejemplo, dice `campaignCreation is not supported on facebook.`

## Endpoints

| Método | Ruta | Qué hace |
| - | - | - |
| `POST` | `/ads/{platform}/campaigns` | Crea una campaña |
| `GET` | `/ads/{platform}/campaigns/{id}` | Obtiene una campaña |
| `PUT` | `/ads/{platform}/campaigns/{id}` | Modifica una campaña |

`{platform}` es la red de anuncios. `{id}` es el ID de la campaña que se devolvió al crearla. Solo puedes consultar y modificar las campañas creadas a través de Ayrshare por el mismo perfil de usuario.

## Parámetros del encabezado

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

Obligatorio para crear una campaña. Envía un valor único nuevo, como un UUID, para cada campaña nueva. Si repites una solicitud con la misma clave, Ayrshare devuelve la primera respuesta, marcada con `idempotentReplayed: true`, y no crea nada nuevo. También puedes enviar la clave en el cuerpo como `idempotencyKey`. Si envías ambas, deben coincidir.

## Crear una campaña

`POST /ads/{platform}/campaigns`

Las campañas nuevas comienzan en `paused` a menos que envíes `status: "active"`, por lo que no se gasta nada hasta que decidas iniciarlas.

**accountId** `string` *required*

La cuenta publicitaria en la que se creará la campaña.

**name** `string` *required*

El nombre de la campaña, de 1 a 255 caracteres.

**type** `string` *required*

El tipo de campaña: `search` o `performanceMax`. Cada red admite solo algunos tipos. Un tipo que la red no admite responde `code: 101` y enumera los tipos admitidos.

**budget** `object` *required*

**propiedades**

**amount** `number` *required*

Cuánto gastar por día, con un máximo de dos decimales.

**type** `string` *required*

`daily`.

**currency** `string`

Código ISO 4217, como `USD`. De forma predeterminada, la moneda de la cuenta publicitaria. Solo algunas redes lo aceptan.

**bidding** `object` *required*

**propiedades**

**strategy** `string` *required*

`maximizeConversions`, `maximizeConversionValue`, `targetCpa`, `targetRoas`, `maximizeClicks` o `manualCpc`. Cada red admite solo algunas estrategias.

**targetCpa** `number`

Costo objetivo por acción. Obligatorio con `targetCpa` y no se acepta con ninguna otra estrategia.

**targetRoas** `number`

Retorno objetivo de la inversión publicitaria, por ejemplo `3.5` para 350%. Obligatorio con `targetRoas` y no se acepta con ninguna otra estrategia.

**euPoliticalAdvertising** `boolean` *required*

Indica si la campaña es publicidad política en la UE. Siempre debes enviarlo. Ayrshare nunca lo completa por ti.

**schedule** `object`

**propiedades**

**start** `string`

Cuándo comenzar: una fecha ISO (`2026-11-01`) o una fecha y hora ISO con `Z` o un desfase (`2026-11-01T09:00:00Z`). De forma predeterminada, ahora.

**end** `string`

Cuándo detenerse, en el mismo formato que `start`. Debe ser posterior a `start`, o posterior al momento actual si omites `start`. Omítelo para que se ejecute sin fecha de finalización. Una red que programa días completos, como Google, también acepta un `end` en el mismo día que `start`, para una campaña de un día.

**targeting** `object`

Cada red admite solo cierta segmentación. Un campo que la red no admite responde `code: 101`.

**propiedades**

**locations** `string[]`

Los IDs de ubicación propios de la red.

**languages** `string[]`

Los IDs de idioma propios de la red.

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

`active` o `paused`.

**platformOptions** `object`

Opciones para una sola red, bajo el nombre de esa red, por ejemplo `{ "facebook": { ... } }`. Las opciones para cualquier otra red responden `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
```

Una creación exitosa responde con `status: "success"`, el `campaignId` y el estado propio de la campaña como `campaignStatus` (`active` o `paused`). Las operaciones de obtener y actualizar responden de la misma forma.

## Obtener una campaña

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

Devuelve la campaña tal como la informa la red. Una campaña que no es tuya, o que no existe, responde `code: 400`.

## Actualizar una campaña

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

Envía al menos uno de estos campos. No puedes cambiar `type`, `accountId` ni `euPoliticalAdvertising` después de crear la campaña.

**name** `string`

El nuevo nombre de la campaña.

**status** `string`

`active` o `paused`. Una solicitud que solo envía `status: "paused"` no se bloquea cuando Ayrshare ha pausado los anuncios en esa red. Aun así necesita una red vinculada y puede fallar si la propia red no está disponible.

**budget** `object`

`{ "amount": number }`: el nuevo monto a gastar por día.

**schedule** `object`

`{ "end": string }`: la nueva fecha de finalización, en el mismo formato que `schedule.start`. Debe ser posterior al inicio de la campaña. Una red que programa días completos, como Google, también acepta el mismo día del inicio.

## Errores

Estos errores incluyen un `code` de Ayrshare:

| Código | Cuándo |
| - | - |
| `101` | La solicitud no es válida, la red no admite campañas o este tipo de campaña, o falta la clave de idempotencia. `details` indica cuál. Ayrshare comprueba la clave después de confirmar que la red está vinculada, por lo que un perfil sin vincular recibe primero el error "not linked" (no vinculado). |
| `400` | La campaña no es tuya o no existe. |
| `424` | Los anuncios en esta red no están disponibles temporalmente. |

Una creación también puede responder con uno de estos estados HTTP. Su cuerpo no tiene `code`, solo `{ "action": "createAdCampaign", "status": "error", "message": "..." }`:

| Estado HTTP | Cuándo |
| - | - |
| `409` | La clave de idempotencia se usó con una solicitud diferente, o la solicitud con esta clave todavía está en curso. No reintentes con una clave nueva. Revisa primero la cuenta publicitaria. |
| `503` | Ayrshare no pudo reservar de forma segura la clave de idempotencia, por lo que no se creó nada. Vuelve a intentarlo más tarde con la misma clave. |


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