Ir al contenido
Quiet Social

Introducción

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

El SDK PHP quiet-social/php-social publica en Facebook, Instagram, LinkedIn, Threads y Pinterest desde cualquier aplicación PHP. Habla con la API de Quiet Social por ti: un post descrito una sola vez, sus imágenes enviadas, sus destinos resueltos dentro de la marca, y cada rechazo convertido en una excepción con nombre.

Un primer ejemplo

use QuietSocial\Sdk\Client;
use QuietSocial\Sdk\Post;

$client = new Client(
    clientId: 'qsc_a1b2c3d4e5f6g7h8i9j0k1l2',
    clientSecret: (string) getenv('QUIET_SOCIAL_SECRET'),
);

$publication = $client->publications()->create(
    Post::make('Nuestra carta de otoño ya está disponible.')->link('https://ejemplo.es/carta')->reference('carta:otono'),
    to: ['facebook', 'linkedin'],
);

echo $publication->id; // pub_…

La clave debe tener al menos los permisos publications:create y destinations:read. Una clave que cubre todo el espacio de trabajo también debe nombrar la marca: new Client(..., brand: 'brd_…') (ver Instalación y autenticación).

Esta llamada lee los destinos de Facebook y LinkedIn de la marca, crea la publicación con una clave de idempotencia derivada de la referencia carta:otono, y devuelve la publicación tal como la registró la API.

Lo que hace el SDK, y lo que deja a la API

El SDK comprueba la forma: un enlace absoluto, etiquetas como cadenas de texto, un título solo para Pinterest, ningún enlace en Instagram. Un error de forma lanza InvalidPost antes de enviar nada.

La API comprueba el fondo: la longitud del texto en cada red, el número de hashtags, la imagen que exigen Instagram y Pinterest, la cuota de la marca. Un rechazo de la API lanza ValidationFailed, con el motivo de cada destino.

Todo lo que hace el SDK pasa por la API REST v1: no abre ninguna puerta que ella no abra, y sus permisos son los de la clave con la que se autentica.

Las páginas de esta documentación

  • Instalación y autenticación: requisitos, clave API, construcción del cliente, permisos que marcar.
  • Publicar: describir un post, programar, los modos, las sobrecargas por red, la idempotencia, seguir una publicación.
  • Imágenes: las cuatro fuentes de una imagen, el texto alternativo, la seguridad de las imágenes remotas.
  • Destinos: nombres de red, identificadores dst_…, un destino por su nombre.
  • Errores: la tabla de excepciones, y cuándo reintentar.
  • Webhooks: declarar un endpoint, verificar una notificación.
  • Pruebas y transportes: FakeTransport, CurlTransport y transportes propios.

Limitaciones conocidas

  • Una imagen por post, y una por red. Ni galería, ni vídeo.
  • X se declara, no se publica. Network::X existe para que un post compartido pueda configurarlo ya, pero la API todavía no publica nada en X: to: ['x'] lanza ValidationFailed con el código destination_unavailable.
  • Todavía no hay primer comentario. firstComment() se acepta, pero ninguna red lo publica: la API ignora el comentario común y rechaza el que se fija para una sola red.
  • Las reglas de las redes las comprueba la API, no el SDK: llegan por ValidationFailed, destino por destino.
  • Una clave de idempotencia vive 24 horas. Protege de una llamada reintentada, no de un post reenviado días después.

Versiones

El SDK sigue el versionado semántico. Antes de la 1.0, una versión menor puede cambiar la API pública; el registro de cambios del paquete (CHANGELOG.md) dice qué ha cambiado. Esta documentación describe la versión 0.1, que funciona con la versión 1 de la API (/api/v1).

El código fuente se publica en GitHub, como espejo de solo lectura: allí las pull requests se cierran, las issues son bienvenidas.