Ir al contenido
Quiet Social

Publicar

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

Un Post describe lo que hay que publicar, una sola vez para todas las redes, y publications()->create() lo publica en los destinos indicados. Esta página trata la descripción de un post, la programación, los modos, las sobrecargas por red, la idempotencia y el seguimiento de una publicación.

Describir un post

Cada método devuelve un post nuevo y deja intacto el original: un post base se comparte y se adapta sin riesgo.

use QuietSocial\Sdk\Image;
use QuietSocial\Sdk\Network;
use QuietSocial\Sdk\NetworkPost;
use QuietSocial\Sdk\Post;

$post = Post::make('Nuestra receta de tarta de calabaza ya está en línea.')
    ->title('Tarta de calabaza, octubre')               // interno: visible en el panel, nunca publicado
    ->link('https://ejemplo.es/recetas/42')
    ->tags('Receta vegetariana', 'Otoño')              // se convierten en #RecetaVegetariana #Otoño
    ->image(Image::fromPath(__DIR__.'/tarta.jpg', alt: 'Una tarta de calabaza sobre una mesa de madera'))
    ->scheduleAt(new DateTimeImmutable('2026-10-15 09:00', new DateTimeZone('Europe/Madrid')))
    ->timezone('Europe/Madrid')
    ->reference('articulo:42')
    ->for(Network::LinkedIn, fn (NetworkPost $linkedin) => $linkedin
        ->content('La receta que nuestros lectores pedían todo el año.')
        ->tags('Cocina'))
    ->for(Network::Pinterest, fn (NetworkPost $pin) => $pin
        ->title('Tarta de calabaza')
        ->destination('Recetas'))
    ->for(Network::Instagram, fn (NetworkPost $instagram) => $instagram->tags());

$publication = $client->publications()->create($post, to: ['linkedin', 'pinterest', 'instagram']);
Método Lo que fija
content() El texto.
title() Un título interno, visible en el panel y nunca publicado.
link() Un enlace. Una URL absoluta en http o https, sin credenciales ni espacios.
tags() Palabras o expresiones, sin #: la API convierte cada una en un hashtag (Receta vegetariana se convierte en #RecetaVegetariana). Una nueva llamada sustituye la lista.
image() Una imagen, con su texto alternativo (ver Imágenes).
firstComment() Un primer comentario. Ninguna red lo publica todavía: la API lo ignora por ahora.
scheduleAt() La fecha de publicación, cualquier DateTimeInterface.
timezone() La zona horaria en la que se muestra la publicación, como Europe/Madrid.
mode() Lo que la API hace con ella (ver más abajo).
reference() Tu propio identificador de aquello de lo que trata el post, como articulo:42: se guarda como external_reference de la publicación, y es el origen de la clave de idempotencia.
brand() La marca brd_…, para una clave que cubre todo el espacio.
for() Lo que cambia en una red (ver más abajo).

Un post mal formado (un enlace relativo, una etiqueta que no es una cadena, un campo que una red no admite) lanza InvalidPost en cuanto se llama al método, antes de enviar nada. Las reglas de cada red las aplica la API, que responde con ValidationFailed (ver Errores).

Programar

scheduleAt() admite cualquier DateTimeInterface y conserva su desfase: la fecha de arriba se envía como 2026-10-15T09:00:00+02:00 (ISO 8601). Sin fecha, la publicación sale en el siguiente paso del planificador, en menos de un minuto. La API rechaza una fecha pasada, incluso para un borrador.

Los modos

Mode Efecto Estado tras create()
Mode::Publish (por defecto) Se publica en la fecha programada, o enseguida si no la hay. scheduled
Mode::Draft Se guarda como borrador: nada sale hasta una llamada a publish(). draft
Mode::Approval Se somete a validación en el panel. Una vez validada, se libera con publish(). pending_approval
use QuietSocial\Sdk\Mode;

$borrador = $client->publications()->create($post->mode(Mode::Draft), to: ['linkedin']);

// Más tarde: liberarla, ahora o en una fecha.
$client->publications()->publish($borrador->id, at: new DateTimeImmutable('2026-10-16 08:00', new DateTimeZone('Europe/Madrid')));

Un borrador o una publicación sometida a validación no conserva ninguna fecha: se elige al llamar a publish().

Sobrecargas por red

for() cambia lo que recibe una red. La función recibe un NetworkPost y lo devuelve, modificado. Un campo que no se toca toma el valor común.

Método de NetworkPost Nota
content() Sustituye el texto.
title() El título del pin. Solo Pinterest: en cualquier otra red, InvalidPost.
link() Sustituye el enlace. Instagram no admite enlaces: fijar uno lanza InvalidPost, y la API retira allí el enlace común.
tags() Sustituye las etiquetas comunes. tags() sin argumentos las quita en esta red.
image() Sustituye la imagen común.
firstComment() Rechazado en Pinterest. Ninguna red publica todavía un primer comentario, y la API rechaza el que se fija para una sola red.
destination() Publica en esta red solo en el destino con ese nombre (ver Destinos).

Una red configurada con for() pero ausente de to: se ignora: declarar todas las redes una vez en un post base compartido no tiene efectos secundarios.

Idempotencia

Publicar dos veces es el peor fallo de una API de publicación, y una petición que se queda sin respuesta se reenvía. Por eso cada create() lleva una clave de idempotencia (ver Idempotencia en la referencia de la API).

  • Con una referencia, la clave es la referencia seguida del SHA-256 del cuerpo de la petición. Reenviar el mismo post (tras un tiempo de espera agotado, desde un job reintentado) devuelve la primera publicación en lugar de crear una segunda.
  • Un post modificado recibe una clave nueva, y es una publicación nueva, incluso con la misma referencia: la referencia dice de qué trata el post, no es una restricción de unicidad.
  • La API recuerda una clave durante 24 horas. El mismo post reenviado más tarde se crea de nuevo.
  • Sin referencia, cada llamada recibe una clave aleatoria: una llamada reintentada vuelve a publicar. Pon una referencia siempre que el mismo post pueda salir dos veces.
  • create($post, to: [...], idempotencyKey: 'mi-propia-clave') sustituye la clave derivada. La API rechaza una clave conocida enviada con otro cuerpo (ValidationFailed, código idempotency_key_reused).
$post = Post::make('Nuestra nueva receta ya está en línea.')->reference('articulo:42');

$primera = $client->publications()->create($post, to: ['linkedin']);
$otraVez = $client->publications()->create($post, to: ['linkedin']); // en menos de 24 horas: la misma publicación

$primera->id === $otraVez->id; // true

$post->fingerprint($to) devuelve un SHA-256 de todo lo que publicaría el post, y dónde, para saber si un post ha cambiado desde su último envío. No es la clave de idempotencia, que se calcula sobre el cuerpo una vez resueltos los destinos y enviadas las imágenes.

Seguir una publicación

$publications = $client->publications();

$publication = $publications->find('pub_01k4b8y5t2v9h6p8w0y2z4b6c8');
$publication->status;                 // draft, scheduled, processing, published, partially_published, failed, cancelled…

foreach ($publication->targets as $destino) {
    $destino->network;                // linkedin
    $destino->status;                 // published, failed…
    $destino->externalUrl;            // la dirección del post en la red, una vez publicado
    $destino->errorMessage;           // el motivo de un fallo
}

$page = $publications->list(['status' => 'failed', 'reference' => 'articulo:42'], page: 1, perPage: 25);

foreach ($page->items as $fallida) {
    $publications->retry($fallida->id);  // reenvía los destinos que fallaron
}

$page->hasMore();                     // true si sigue otra página

$publications->cancel('pub_01k4b8y5t2v9h6p8w0y2z4b6c8');

list() admite los filtros brand, status y reference; cualquier otra clave lanza InvalidArgumentException. Los valores de un destino (content, tags, linkUrl, media…) son los efectivos: lo que recibe el destino una vez aplicadas las sobrecargas. Cada objeto de respuesta conserva en raw() el contenido del que procede. Los estados se describen en Publicaciones.

Una transición que el estado prohíbe (publicar una publicación que ya salió, cancelar una ya publicada) lanza ValidationFailed con el código transition_not_allowed. Las transiciones no llevan clave de idempotencia: cada una rechaza el estado que produce, y una segunda llamada no puede actuar dos veces.