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

# Usar la API GraphQL

> Encuentra operaciones, entiende los tipos de argumentos y los enums, crea publicaciones y sube medios mediante la API GraphQL de Ayrshare.

<h2 id="finding-an-operation">
  Encontrar una operación
</h2>

El esquema es la referencia autorizada para el subconjunto GraphQL compatible: raíces de operación, nombres, argumentos, tipos de entrada y valores de enum. Las descripciones ofrecen orientación de uso, y el [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) muestra ambos. Para las capacidades exclusivas de REST, usa la [referencia de la API REST](/docs/apis/overview).

Los nombres de las operaciones siguen los endpoints REST a los que llegan, en camelCase. `GET /history` es `postHistory`, `GET /analytics/social` es `socialAnalytics`, `POST /post` es `createPost`.

<h2 id="queries-read-mutations-write">
  Las queries leen, las mutations escriben
</h2>

Las queries son lecturas y validaciones que no cambian nada en nuestro lado. Las mutations publican o cambian el estado, inician trabajos o envían emails. Ni el verbo HTTP de REST ni el coste de una llamada deciden la raíz:

<ul class="custom-bullets">
  <li><code>validatePost</code> comprueba una publicación sin publicarla.</li>
  <li><code>validateMedia</code> comprueba que una URL de medios sea accesible.</li>
  <li><code>generatePost</code> es una query porque no cambia nada en nuestro lado. Aun así cuenta como una llamada a la API y devuelve un texto distinto cada vez, así que asegúrate de que una caché del cliente o una recarga automática no la repita sin que te des cuenta.</li>
  <li><code>mediaUploadUrl</code> es una mutation porque crea una URL de subida para tu cuenta.</li>
  <li><code>linkAnalytics</code> es una mutation porque puede solicitar un informe por email.</li>
  <li><code>userBatch</code> es una mutation porque inicia un trabajo de exportación.</li>
</ul>

Usa el Explorer o el esquema para confirmar la raíz de cada operación compatible.

<h2 id="creating-a-post">
  Crear una publicación
</h2>

`createPost` recibe un único argumento `input`, así que toda la publicación es un solo objeto:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}
```

La entrada refleja el [endpoint REST de publicación](/docs/apis/post/post) documentado, incluidos los objetos de opciones por red y las formas REST que aceptan más de una estructura JSON:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}
```

Una publicación puede tener éxito en una red y fallar en otra. Eso no es un fallo de la solicitud; consulta [Errores](/docs/apis/graphql/errors#partial-success-on-multi-network-posts).

<h2 id="argument-types">
  Tipos de argumentos
</h2>

La mayoría de los argumentos son cadenas, números y booleanos corrientes. Hay tres casos que conviene conocer.

<h3 id="enums">
  Enums
</h3>

Muchos argumentos de tipo cadena con un conjunto cerrado de valores compatibles son enums de GraphQL, que se escriben **sin comillas y en mayúsculas**:

```graphql theme={"system"}
{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }
```

No `"instagram"`. El servidor asigna cada enum aceptado al valor exacto que espera el controlador REST subyacente: a menudo, aunque no siempre, una cadena en minúsculas. Un enum no válido se rechaza durante la validación de GraphQL antes de que se ejecute la operación, así que un error tipográfico no te cuesta nada.

Algunos argumentos comparten nombre entre operaciones pero aceptan valores diferentes, porque los endpoints realmente son distintos. `reviews(platform:)` acepta solo `GMB` y `FACEBOOK`, ya que son las únicas redes con reseñas. El autocompletado de tu cliente mostrará el conjunto correcto para cada operación.

<h3 id="the-json-scalar">
  El escalar JSON
</h3>

Algunos argumentos están tipados como `JSON` en lugar de un tipo específico. Esto ocurre cuando un valor tiene legítimamente más de una forma y ningún tipo GraphQL único podría describirlo con precisión:

<ul class="custom-bullets">
  <li><code>explainError(code:)</code> acepta <code>215</code> o <code>"215"</code>, porque los clientes guardan los códigos de error de ambas formas.</li>
  <li><code>createPost(input:)</code> usa JSON para campos como <code>post</code> y <code>mediaUrls</code>, que pueden ser valores compartidos u objetos por plataforma.</li>
  <li><code>createAutomation(triggers:, actions:)</code> reciben arrays cuyos campos dependen del <code>type</code> de cada entrada.</li>
  <li><code>boostFacebookPost(interests:)</code> acepta ids de intereses de Meta como cadenas o números.</li>
</ul>

Pasa el mismo valor que enviarías en el cuerpo REST correspondiente. Un argumento `JSON` no es una laguna: el resolver lo valida antes de despacharlo, así que un valor no válido devuelve un error de validación y no consume ninguna llamada a la API.

<h3 id="optional-arguments-and-nulls">
  Argumentos opcionales y nulls
</h3>

En los argumentos opcionales y en los campos opcionales dentro de objetos de entrada, un `null` explícito se normaliza como omisión. Los miembros null dentro de listas se conservan cuando el tipo de la lista lo permite.

<h2 id="reading-responses">
  Leer las respuestas
</h2>

La mayoría de las operaciones devuelven un escalar `JSON` que contiene el envoltorio completo de la respuesta REST, así que selecciona el campo raíz sin subcampos. `createPost` devuelve actualmente un `PostResult` tipado, así que selecciona sus campos:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}
```

Los tipos de respuesta tipados como `PostResult` también incluyen `raw: JSON!`, que contiene la respuesta REST completa sin modificar:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}
```

`raw` es permanente y existe para que un campo nuevo que aparezca en la respuesta REST nunca quede inaccesible desde GraphQL mientras nos ponemos al día con su tipado. Si necesitas algo que los campos tipados no exponen, pide `raw`.

<h2 id="uploading-media">
  Subir medios
</h2>

**Los bytes de los medios no pueden viajar en una solicitud GraphQL.** Una solicitud GraphQL es un único documento JSON con un límite de 64 KB, así que no hay ningún campo que acepte un archivo, y codificar una imagen en base64 dentro de la query superaría ese límite para cualquier cosa más grande que una miniatura.

La vía compatible evita el problema por completo y, en cualquier caso, es más rápida que subir a través de una API, porque tus bytes van directamente al almacenamiento:

1. Pide una URL de subida:

   ```graphql theme={"system"}
   mutation { mediaUploadUrl(contentType: "image/jpeg") }
   ```

2. Lee `data.mediaUploadUrl.uploadUrl`, `accessUrl` y `contentType` del JSON devuelto.

3. Haz `PUT` de tu archivo **directamente a `uploadUrl`**, no a la API de Ayrshare, estableciendo el encabezado `Content-Type` de la solicitud con el `contentType` devuelto.

4. Una vez que la subida se complete correctamente, pasa `accessUrl` en `createPost.input.mediaUrls`:

   ```graphql theme={"system"}
   mutation {
     createPost(input: {
       post: "With a photo"
       platforms: [INSTAGRAM]
       mediaUrls: ["https://the-returned-access-url"]
       idempotencyKey: "instagram-photo-001"
     }) {
       status
       postIds { platform postUrl }
     }
   }
   ```

Trata `uploadUrl` como una credencial de escritura de corta duración y no la registres ni la expongas. `accessUrl` es la URL de medios que se usa al crear la publicación.

También puedes seguir usando los [endpoints REST de subida](/docs/apis/media/upload-media) y hacer referencia a las URLs resultantes desde GraphQL. Ambas interfaces comparten la misma biblioteca de medios.

<h2 id="read-next">
  Lecturas recomendadas
</h2>

<ul class="custom-bullets">
  <li>[Errores](/docs/apis/graphql/errors): códigos de estado HTTP, estructura de los errores y éxito parcial.</li>
  <li>[Límites y facturación](/docs/apis/graphql/limits): límites de tamaño de las consultas y cómo se cuentan las solicitudes.</li>
</ul>


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