Programa publicaciones en redes sociales con una API REST

La secuencia completa

Para programar una publicación a través de Mellow Hub, identifica la autoridad de la credencial, selecciona los canales conectados, valida una petición y luego créala con una clave de idempotencia estable. Vuelve a leer la publicación resultante para saber qué ocurrió en cada destino. Una respuesta de creación correcta no demuestra que todas las redes la hayan publicado.

Esta receta usa REST. Un cliente MCP sigue la secuencia equivalente whoami → list_channels → validate_post → create_post → get_post descrita en la guía de MCP para redes sociales.

Prueba la comprobación de entrada con un ejemplo listo para ejecutar

Descarga el comprobador de entrada en Node.js y la plantilla post.example.json en la misma carpeta. El script necesita Node.js 22 o más reciente y ningún paquete. Lee su código y luego aporta una credencial de Hub existente a través de tu entorno secreto como MELLOW_HUB_KEY.

Para esta comprobación bastan channels:read y posts:read. Elige solo los canales que piensas usar en los ajustes de acceso de Hub. Listar canales solo necesita el primer permiso. Esta comprobación de entrada no necesita permiso de publicación ni suscripción.

node mellow-hub-check.mjs --channels
# Sustituye los IDs de canal y la URL del material en post.example.json.
node mellow-hub-check.mjs post.example.json

El script comprueba los canales disponibles para la credencial, envía tu JSON editado al endpoint de validación autenticado de Mellow Hub e imprime los problemas bloqueantes y las notas. Termina con 0 cuando esas comprobaciones de entrada pasan, 1 si hay problemas de entrada, o 2 ante un fallo de archivo, permiso, conexión o una respuesta inesperada.

1. Comprueba la cuenta y la credencial

Conecta tus propios canales en Hub y crea una credencial con los canales y el modo que piensas delegar. Guárdala en el entorno secreto de tu servidor como MELLOW_HUB_KEY; nunca la pongas en JavaScript del frontend ni en un repositorio público. Los ejemplos leen esa variable de entorno sin mostrar su valor.

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

Usa los IDs de canal devueltos para esta cuenta. Los valores spc_… de abajo son marcadores de posición. Comprueba el modo y la cuota disponible antes de crear nada. Una credencial de revisión prepara una publicación para que una persona la apruebe. Una credencial de piloto automático puede actuar dentro de su alcance, tope y caducidad delegados.

2. Describe la publicación real

Guarda la siguiente estructura como post.json. Sustituye los dos IDs de canal, la dirección del material de ejemplo, el texto y la fecha de ejemplo. Usa un desfase horario ISO 8601 explícito o una Z UTC; la marca de tiempo representa un instante, no el reloj local del lector. La fecha de 2030 del ejemplo es deliberadamente ilustrativa.

{
  "caption": "A short look at how this piece was made.",
  "channels": [
    "spc_your_instagram_channel",
    "spc_your_youtube_channel"
  ],
  "media": [
    "https://cdn.example.com/your-video.mp4"
  ],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": {
      "placement": "reels"
    },
    "youtube": {
      "title": "How this piece was made",
      "privacyStatus": "public"
    }
  }
}

La red descarga el material en el momento de publicar, así que la URL HTTPS real debe seguir accesible entonces. Un archivo local privado o una URL firmada caducada no funcionarán. Este ejemplo da a YouTube su título aparte y selecciona la ubicación Reels para Instagram. La disponibilidad de formatos sigue dependiendo de tus cuentas conectadas y del proveedor.

3. Valida sin publicar

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

Inspecciona ok, issues y notes en la respuesta. Corrige cada problema bloqueante antes de continuar. La validación puede devolver HTTP 200 con ok: false, así que comprobar solo el estado HTTP no basta. El endpoint autenticado comprueba la propiedad real de tus canales además de las reglas de entrada.

Para una vista previa sin cuenta de las comprobaciones de texto, título y número de archivos, usa el comprobador de publicaciones gratuito. Ninguna de las dos vistas previas mide la duración ni la proporción de tu archivo real, y un proveedor aún puede rechazar la entrega.

4. Crea una vez, reintenta de forma coherente

La credencial inicial de solo lectura no puede crear publicaciones. Antes de este paso, usa una conexión con posts:write y posts:publish para los canales previstos. Estos permisos también son necesarios en modo de revisión; el modo de revisión sigue dejando la decisión de publicar a una persona. Sin ellos, la petición devuelve un error de permisos.

La siguiente petición crea la publicación. Ejecútala solo cuando el contenido y la autoridad sobre el destino sean correctos. En modo de revisión espera la aprobación; en piloto automático, la acción delegada puede continuar a la hora programada.

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

Guarda la clave de idempotencia junto con el trabajo en tu aplicación. Si se pierde la respuesta, reintenta la misma petición con la misma clave. No crees una clave nueva solo porque se agotó el tiempo de espera. Una publicación distinta necesita una clave distinta; reutilizar una con contenido cambiado se rechaza.

5. Lee el resultado por destino

Guarda el post.id devuelto y recupéralo con GET /api/hub/v1/posts/{id}, con la misma cabecera de autorización. Inspecciona cada entrada de targets y su URL pública. Una publicación multired puede ser parcial: un destino puede tener éxito mientras otro falla.

Guarda juntos la hora prevista, el ID de publicación de Hub, la clave de idempotencia y los resultados por destino en tu propio registro del trabajo. Evita registrar credenciales o cabeceras de autorización completas. Cuando un destino falla, usa el error que informa para decidir el siguiente paso en lugar de recrear a ciegas toda la publicación.

Recupera una publicación con tiempo de espera agotado o publicada a medias

Un tiempo de espera agotado significa que quien llama no conoce el resultado. Un resultado partial significa que Hub ha registrado resultados distintos para los destinos seleccionados. Mantén esos casos separados al decidir qué enviar a continuación.

Se perdió la respuesta de creación

Guarda la carga original y la clave de idempotencia en tu registro del trabajo antes de la primera petición. Reintenta esa petición sin cambios con la misma clave y una autoridad válida. Cuando Hub ya tiene la publicación, devuelve su ID y su estado actual. La respuesta REST sigue siendo HTTP 201, así que un 201 por sí solo no te dice si este intento creó un registro nuevo. Con el ID en la mano, usa GET para seguir su estado.

Si recibes 409 idempotency_key_reused, compara la petición con el trabajo guardado. No generes otra clave automáticamente para saltarte el error: describiría una operación nueva y podría duplicar la publicación original.

Un destino falló después de que otro publicara

Lee targets antes de preparar una recuperación. Por ejemplo, si Instagram está published y YouTube failed, corrige el problema de YouTube indicado y valida una carga nueva que contenga solo ese canal de YouTube. Una recuperación deliberada usa una clave nueva, como studio-process-video-slot-001-youtube-recovery-1. Guarda su nuevo ID de publicación junto al trabajo original. Siguen aplicándose los permisos de canal habituales, el modo de revisión y la cuota de publicaciones.

Repetir la clave original devuelve la publicación existente; no reinicia sus destinos fallidos. Un destino que sigue en espera o publicándose no es un fallo confirmado. No lo reenvíes solo porque quien llamaba dejó de esperar, y no incluyas en la petición de recuperación los destinos que ya publicaron.

Preguntas que surgen en integraciones reales

¿Puedo usar un texto distinto en una red?

Sí. Una entrada de perChannel con el ID real del canal como clave sustituye el texto o el material de ese canal. Los campos de toda la plataforma van en options. Consulta los ejemplos resueltos en la referencia de Hub.

¿Puede un agente conectar mis cuentas sociales por sí mismo?

No. El titular de la cuenta completa el flujo de conexión correspondiente. Una clave de API es una delegación para acciones ya autorizadas, no un permiso para suplantar al titular en la pantalla de inicio de sesión de una red.

¿Una petición consume una publicación de mi plan?

La cuota se cuenta por destino de red. Consulta los planes actuales y la cuota restante de la credencial antes de elegir destinos.