Ir al contenido
Quiet Social

Publicaciones

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

Una publicación lleva un contenido común y un objetivo por cada destino elegido. Cada objetivo tiene su propio estado, su propio texto y su propio resultado: Facebook puede tener éxito mientras Instagram falla, y relanzar Instagram no vuelve a publicar en Facebook.

El recurso

{
  "data": {
    "id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8",
    "title": null,
    "content": "Nuestro nuevo artículo ya está publicado.",
    "link_url": "https://example.com/article",
    "status": "scheduled",
    "external_reference": "article-42",
    "tags": ["PanDeMasaMadre"],
    "media": [
      { "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Una hogaza de pan de masa madre sobre una tabla." }
    ],
    "scheduled_at": "2026-10-01T09:14:22+00:00",
    "published_at": null,
    "timezone": "Europe/Paris",
    "targets": [
      {
        "destination_id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
        "network": "facebook",
        "provider": "meta",
        "status": "pending",
        "content": "Nuestro nuevo artículo ya está publicado.",
        "link_url": "https://example.com/article",
        "tags": ["PanDeMasaMadre"],
        "title": null,
        "first_comment": null,
        "media": [
          { "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Una hogaza de pan de masa madre sobre una tabla." }
        ],
        "scheduled_at": null,
        "published_at": null,
        "external_url": null,
        "attempts": 0,
        "error": null,
        "metrics": null
      }
    ],
    "created_at": "2026-10-01T09:14:22+00:00"
  }
}
Campo Significado
title Título interno. No se envía a ninguna red.
content Texto común.
link_url Enlace común.
status Estado agregado, consulta Estados.
external_reference Tu propia referencia, tal como la enviaste.
tags Hashtags comunes, formateados y sin #. Consulta Las etiquetas.
media Imágenes comunes, en orden, con su texto alternativo.
scheduled_at Fecha de salida prevista. Vale el instante de creación para una publicación inmediata, null para un borrador o una publicación sometida a validación.
published_at Fecha de publicación.
timezone Zona horaria de la publicación, la de la marca por defecto.
targets[].destination_id El destino al que apunta. Relaciona un objetivo con su destino mediante este campo.
targets[].network El nombre corto de la red (facebook, instagram, linkedin, threads, pinterest).
targets[].provider El proveedor de la conexión: meta para Facebook e Instagram; en los demás casos, el mismo nombre que la red.
targets[].content El texto realmente enviado a este destino.
targets[].link_url, tags, title, first_comment, media Los valores realmente retenidos para este destino: la sustitución de la red si la hay, el valor común en caso contrario, ya filtrados según lo que acepta la red.
targets[].external_url La dirección pública del post, una vez publicado.
targets[].attempts Número de intentos de envío.
targets[].error { "code", "message" } del último error, o null. Nuestros propios rechazos están en inglés; los de la red conservan sus palabras (consulta Errores).
targets[].metrics Estadísticas del último hito registrado, o null. Consulta Estadísticas.

Los valores de un objetivo quedan fijados en la creación: lo que sale es lo que lleva el objetivo.

El código y el mensaje de error de un objetivo proceden de la red y se transmiten tal cual: reformularlos haría perder lo que permite corregir.

POST /publications

Crea una publicación y sus objetivos.

Permiso requerido: publications:create. Cabecera requerida: Idempotency-Key (consulta Idempotencia).

Campo Tipo Requerido Nota
destination_ids lista de dst_… sí Al menos uno, 100 como máximo, sin duplicados.
content texto no Texto común.
title texto (255) no Título interno, nunca publicado.
link_url URL absoluta (2048) no Se ignora en un destino que no acepta enlaces (Instagram).
media lista de objetos {id, alt_text} no 10 como máximo, sin duplicados. alt_text: 1 000 caracteres como máximo.
media_ids lista de med_… no Forma antigua, sin texto alternativo. 10 como máximo. Excluyente con media.
tags lista de textos no 30 como máximo, 100 caracteres cada uno una vez formateado.
first_comment texto (8000) no Se acepta, pero hoy ninguna red publica un primer comentario: se ignora.
mastodon objeto no Ajustes de los destinos Mastodon: content_warning (texto, 500, la advertencia tras la que se pliega el texto, contada en el límite del servidor), visibility (public, unlisted o private; si falta, la de la cuenta), language (fr, en, es, de, it, pt, nl, ca; si falta, la de la marca). Cualquier otra clave se rechaza. Se devuelven en mastodon de la publicación.
scheduled_at fecha ISO 8601 no Debe estar en el futuro.
timezone zona horaria IANA no Europe/Paris, America/Montreal… La de la marca por defecto.
mode draft, approval, scheduled, immediate no Se deduce si falta.
overrides objeto indexado por red no Consulta Las sustituciones por red.
external_reference texto (255) no Tu referencia, para encontrar la publicación más adelante.
brand_id brd_… según el caso Obligatorio si el cliente cubre todo el espacio de trabajo.

Una publicación debe llevar un texto o una imagen, y cada destino debe recibir uno u otra una vez aplicadas las sustituciones.

Las fechas

scheduled_at sigue la norma ISO 8601: 2026-10-15T09:00:00+02:00, 2026-10-15T07:00Z o 2026-10-15T09:00. Los segundos y el desfase son opcionales; sin desfase, la hora se lee en UTC. Cualquier otra forma — 15/10/2026, por ejemplo — se rechaza con 422, en lugar de leerse al azar de una convención. El instante enviado se conserva, sea cual sea el desfase, y se devuelve en UTC.

El modo

mode Efecto Estado inicial
immediate Sale en la próxima pasada del planificador, que se ejecuta cada minuto. scheduled
scheduled Sale en scheduled_at, que pasa a ser obligatorio. scheduled
draft Guardada, no sale nada. Hay que liberarla con publish. draft
approval Sometida a la validación del equipo en el panel. pending_approval

Sin mode, una fecha significa scheduled y su ausencia significa immediate: un contenido enviado sin precisar nada sale, no se queda dormido como borrador.

En modo draft o approval, scheduled_at no se guarda: la fecha de salida se elige en el momento de liberarla, con publish. Aun así, una fecha enviada debe estar en el futuro.

Una publicación en modo approval espera a que un miembro del equipo la valide en el panel; la API no valida. Una vez validada (status: "approved"), se libera con POST /publications/{id}/publish.

Las imágenes

media nombra las imágenes de la biblioteca de la marca, en orden, cada una con un texto alternativo opcional:

"media": [
  { "id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Una hogaza de pan de masa madre sobre una tabla." }
]
  • media_ids (["med_…"]) se sigue aceptando, sin texto alternativo. Enviar los dos se rechaza.
  • El texto alternativo se transmite a las redes que lo aceptan (Facebook, Instagram, LinkedIn, Threads, Pinterest). Pinterest lo limita a 500 caracteres.
  • Un medio eliminado, aunque siga en la papelera, ya no se puede utilizar.
  • El número de imágenes depende de la red: Facebook, Instagram, Threads y LinkedIn admiten hasta diez (un carrusel en Instagram y Threads; el enlace de un carrusel de Threads no se envía; en LinkedIn, las imágenes prevalecen sobre el enlace, como una imagen sola), Mastodon y Bluesky hasta cuatro, Pinterest una por ahora. Consulta capabilities.maximum_media_count. Las imágenes salen en el orden de media.

Las etiquetas

tags lleva hashtags, escritos libremente: "pan de masa madre", "#PanDeMasaMadre" o "pan-de-masa-madre" se convierten todos en PanDeMasaMadre. Cada palabra toma una mayúscula inicial, todo lo que no es letra ni cifra separa dos palabras, y el # se retira: el recurso devuelve las etiquetas sin él. Una etiqueta de la que no queda nada ("!!!") se rechaza.

Cada red las coloca a su manera:

Red Colocación Contada en el límite de texto
Facebook, Instagram, Pinterest Al final del texto, tras una línea vacía, #Etiqueta separadas por espacios. Sí
LinkedIn Al final del texto, como hashtags clicables. Sí, en la forma enviada a LinkedIn, más larga que #Etiqueta.
Threads La primera etiqueta se convierte en el tema del post (50 caracteres como máximo). Las siguientes no salen. No

Una etiqueta que el texto ya lleva como hashtag (… nuestro #PanDeMasaMadre) no se repite. En Instagram, los hashtags del texto y las etiquetas cuentan juntos para el límite de 30.

Las sustituciones por red

overrides sustituye, para una red, los valores comunes. Está indexado por nombre de red, no por destino: una sustitución se aplica a todos los destinos de esa red presentes en la petición.

"overrides": {
  "linkedin": { "content": "Una versión más larga para LinkedIn.", "tags": ["Panadería"] },
  "instagram": { "content": "Un pie de foto para Instagram.", "tags": [] },
  "pinterest": { "title": "Pan de masa madre casero" }
}

Campos admitidos, por red:

Red content tags link_url media title first_comment
facebook, linkedin, threads sí sí sí sí no sí
instagram sí sí no sí no sí
pinterest sí sí sí sí sí (100) no
  • Una clave que una red no admite se rechaza con 422, en el campo de la sustitución (« « instagram » does not accept: « link_url » », es decir, «instagram» no acepta «link_url»): nunca se ignora en silencio.
  • Un nombre de red desconocido se rechaza (« Unknown network: « linkedln ». », es decir, red desconocida).
  • tags: [] retira los hashtags de esa red; una clave ausente deja el valor común.
  • media sustituye las imágenes comunes para esa red; una lista vacía no es una sustitución.
  • title es el título visible de un Pin. La publicación no tiene uno común: el título interno nunca se publica.
  • first_comment en sustitución se rechaza en la validación, ya que hoy ninguna red lo publica (consulta Los rechazos).
  • Una sustitución que apunta a una red ausente de destination_ids se ignora, medios incluidos.
  • Los límites se aplican a los valores realmente enviados a cada destino, sustituciones incluidas.

Ejemplo

curl -X POST https://quietsocial.dev/api/v1/publications \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: article-42-publie-v1' \
  -d '{
        "content": "Nuestro nuevo artículo ya está publicado.",
        "link_url": "https://example.com/article",
        "destination_ids": ["dst_01k4b8x2q9r7f3m5t6v8w0y2z4", "dst_01k4b8x3r0s8g4n6u7w9x1z3a5"],
        "media": [{"id": "med_01k4b8z6u3w0j7q9x1z3a5c7e9", "alt_text": "Una hogaza de pan de masa madre."}],
        "tags": ["pan de masa madre"],
        "overrides": {"linkedin": {"content": "Una versión para LinkedIn."}},
        "external_reference": "article-42"
      }'

201 Created, con el recurso completo, objetivos incluidos.

Los rechazos

Un cuerpo mal formado — campo que falta, tipo erróneo, valor fuera de la lista, fecha que no está en ISO 8601, clave de sustitución no admitida — responde 422 con el sobre de validación (consulta Errores).

Un cuerpo bien formado pero que no puede convertirse en una publicación responde 422 publication_not_publishable, y no se crea nada. Se examinan todos los destinos: recibes todos los errores de una vez, no red por red.

{
  "error": {
    "code": "publication_not_publishable",
    "message": "“Instagram Fabrique” requires an image.",
    "errors": [],
    "destination_errors": {
      "dst_01k4b8x4s1t9j5q7v8y0z2b4d6": ["“Instagram Fabrique” requires an image."]
    }
  }
}

errors contiene lo que se aplica a toda la publicación, destination_errors lo que se aplica a un destino, indexado por su identificador. message repite el primer error; lee las dos listas. El detalle de los mensajes está en Errores.

Un identificador de destino o de medio desconocido, o que pertenece a otra marca, se rechaza en errors, con el mismo mensaje en ambos casos, y hace que se rechace la publicación entera: no sale nada hacia los destinos válidos de la misma petición.

Códigos: 201, 400, 401, 403, 409, 422, 429.

GET /publications

Las publicaciones visibles para el cliente, las más recientes primero, con sus objetivos.

Permiso requerido: publications:read.

Parámetro Tipo Nota
brand_id brd_… Solo devuelve las publicaciones de esta marca. Una marca fuera de alcance devuelve una lista vacía.
external_reference texto (255) Solo devuelve las publicaciones que llevan exactamente esta referencia.
status estado de publicación Solo devuelve las publicaciones en este estado. Un valor desconocido responde 422.
per_page entero Entre 1 y 100, 25 por defecto.
page entero
curl "https://quietsocial.dev/api/v1/publications?external_reference=article-42" \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"

El filtro por external_reference ofrece un camino de vuelta desde tu identificador hasta el nuestro: una automatización que repite su evento de negocio puede comprobar si ya ha publicado, incluso después de haber perdido el identificador pub_….

Códigos: 200, 401, 403, 422, 429.

GET /publications/{id}

Permiso requerido: publications:read.

Devuelve el recurso completo. Es la llamada que hay que hacer tras un webhook publication.published para conocer las direcciones públicas en targets[].external_url.

Códigos: 200, 401, 403, 404, 429.

POST /publications/{id}/publish

Libera una publicación retenida: un borrador, o una publicación validada.

Permiso requerido: publications:update. Sin clave de idempotencia.

Campo Tipo Requerido Nota
scheduled_at fecha ISO 8601 no Sin fecha, la publicación sale en la próxima pasada del planificador.
curl -X POST https://quietsocial.dev/api/v1/publications/pub_01k4b8y5t2v9h6p8w0y2z4b6c8/publish \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"scheduled_at": "2026-10-02T08:00:00+02:00"}'

200 OK, con la publicación releída. Su estado pasa a scheduled; los objetivos en borrador pasan a pending sin fecha, a scheduled con una fecha.

Rechazos, todos en 409 transition_not_allowed:

  • la publicación espera una validación (pending_approval);
  • ya está programada (scheduled): para cambiar su hora, muévela desde el calendario del panel; para detenerla, cancélala;
  • ya ha salido o ha terminado;
  • no tiene ningún destino;
  • scheduled_at está en el pasado;
  • la cuota mensual de entregas de la marca no basta para sus objetivos.

Un valor de scheduled_at que no es una fecha ISO 8601 responde 422.

Códigos: 200, 401, 403, 404, 409, 422, 429.

POST /publications/{id}/cancel

Detiene lo que todavía puede detenerse.

Permiso requerido: publications:cancel. Sin clave de idempotencia.

Solo se cancelan los objetivos en draft, pending_approval, pending, scheduled o queued. Un objetivo ya en curso (processing, uploading_media, waiting_for_media, publishing) quizá ya se haya comunicado con la red: no se cancela.

El estado de la publicación se deriva de sus objetivos. Si uno de ellos ya había llegado a buen término, la publicación queda en partially_published, no en cancelled. Lee el estado devuelto en lugar de esperar cancelled.

Una publicación ya terminada (published, partially_published, failed, cancelled) responde 409 transition_not_allowed.

Códigos: 200, 401, 403, 404, 409, 429.

POST /publications/{id}/retry

Relanza los objetivos fallidos.

Permiso requerido: publications:retry. Sin clave de idempotencia.

Los objetivos en failed o requires_reconnect vuelven a pending, con el contador de intentos puesto a cero y el error borrado. Un objetivo publicado nunca vuelve a salir.

Una publicación terminada (failed, partially_published) de la que vuelven a salir objetivos pasa de nuevo a scheduled, con el instante del relanzamiento como fecha de salida: puede volver a cancelarse, y el calendario la muestra el día en que vuelve a salir.

Rechazos, en 409 transition_not_allowed:

  • no hay ningún objetivo que relanzar;
  • un objetivo que relanzar depende de un destino que no puede publicar (conexión que restablecer, destino desactivado). No se modifica nada: restablece primero la conexión en el panel.

El relanzamiento no consulta la cuota de entregas: negarse a terminar una publicación que ya ha salido a medias sería peor que superar el tope en unas pocas unidades.

Códigos: 200, 401, 403, 404, 409, 429.

Estados

Estados de una publicación

Valor Significado
draft Guardada, no sale nada.
pending_approval A la espera de validación por parte del equipo.
approved Validada, todavía no liberada.
scheduled Programada, incluso para «ahora».
queued Reservado; hoy ninguna publicación toma este estado.
processing Al menos un objetivo está en curso o todavía en espera.
published Todos los objetivos están publicados.
partially_published Al menos un objetivo está publicado, otro no.
failed Ningún objetivo está publicado.
cancelled Todos los objetivos están cancelados.

Los cuatro últimos son terminales.

Estados de un objetivo

Valor Significado
draft Retenido con su borrador.
pending_approval A la espera de validación.
pending Espera la próxima pasada del planificador.
scheduled Programado para una fecha.
queued En cola de envío.
processing En curso.
uploading_media Envío de la imagen a la red.
waiting_for_media La red está procesando el medio (casi siempre un vídeo): el objetivo se volverá a leer solo. Mientras un objetivo esté en este estado, la publicación no se puede cancelar, mover ni eliminar (409).
publishing Llamada de publicación en curso.
published Publicado. external_url está informada.
failed Abandonado tras sus intentos, o rechazado.
cancelled Cancelado.
requires_reconnect La conexión debe restablecerse en el panel.

Las reglas propias de cada red que no figuran en capabilities — formato y proporciones de la imagen en Instagram, anchura de la imagen en Threads, imagen eliminada desde la creación — se comprueban en el momento del envío. Un objetivo que no las respeta pasa a failed con error.code en validation_failed y un mensaje que nombra la regla; no se reintenta.

Un objetivo hace hasta cinco intentos. Solo los errores pasajeros — red no disponible, límite de frecuencia de la red — se reintentan automáticamente: entre dos intentos, el objetivo vuelve a scheduled y conserva su último error en error. Un error de autorización lo pone directamente en requires_reconnect. failed y requires_reconnect son los dos estados que retry hace volver a salir.

Estadísticas

targets[].metrics lleva los contadores del último hito registrado con contadores: hacia el día 1, el día 7 y el día 30 después de la publicación (como mucho tres días después; un hito perdido más allá no se recupera). Vale null antes del primer registro, en una red cuyas estadísticas no se leen, y cuando ningún registro tiene contadores (publicación eliminada, acceso no concedido…). Hoy solo se lee Mastodon, sin token, para las publicaciones públicas o no listadas.

{
  "checkpoint": 7,
  "measured_at": "2026-10-08T05:40:12+00:00",
  "favourites": 34,
  "reblogs": 3,
  "replies": 5,
  "quotes": 1,
  "impressions": null,
  "reach": null,
  "likes": 34,
  "comments": 5,
  "shares": 3,
  "saves": null,
  "clicks": null,
  "video_views": null,
  "limited_by": null
}
Campo Significado
checkpoint El hito: 1, 7 o 30 días después de la publicación.
measured_at El momento del registro.
impressions Veces que la publicación se mostró o se vio.
reach Personas distintas alcanzadas.
likes Me gusta, reacciones o favoritos.
comments Comentarios o respuestas.
shares Compartidos, republicaciones o envíos.
quotes Citas.
saves Guardados.
clicks Clics salientes o en el contenido.
video_views Reproducciones de vídeo.
limited_by Por qué faltan las impresiones, el alcance y los clics cuando el resto se ha leído: permission_missing (la cuenta no ha concedido acceso a las estadísticas; volver a conectarla lo reabre para los hitos siguientes), not_eligible (la red no los ofrece para esta cuenta), not_measurable (este tipo de publicación no los tiene). null en caso contrario.
favourites, reblogs, replies Obsoletos. Antiguos nombres de Mastodon de likes, shares y comments, con el mismo valor, devueltos para todas las redes. Se mantienen en la versión 1 de la API; usa los nuevos nombres.

Un contador que la red no da vale null, que no es 0: Mastodon no da ni impresiones ni alcance. Este objeto puede recibir más contadores: ignora las claves que no conozcas.