- Documentación
- API · Versión 1.0
- Publicaciones
Publicaciones
En esta página
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 demedia.
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í |
| 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.mediasustituye las imágenes comunes para esa red; una lista vacía no es una sustitución.titlees el título visible de un Pin. La publicación no tiene uno común: el título interno nunca se publica.first_commenten 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_idsse 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_atestá 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.