API de redes sociales para desarrolladores: empezá por un borrador

Integrá Postbean con endpoints reales para cuentas, publicaciones y archivos. Controlá estado, permisos, horarios y reintentos.

Publicado api, developers, automation
Ilustración: API de redes sociales para desarrolladores: empezá por un borrador

La primera prueba de una integración de redes debería guardar un borrador y volver a leerlo. Así comprobás cuenta destino, formato de datos y credenciales antes de mandar contenido a una cuenta pública.

Postbean expone una API REST además del servidor MCP. Podés consultar cuentas conectadas, crear publicaciones, subir archivos, programar y pedir un envío inmediato. Las solicitudes usan una API key asociada a un espacio y pasan por los servicios de publicación del producto.

El recorrido que sigue empieza chico: elegís una cuenta, guardás contenido y conservás su ID. Cuando eso funciona, agregás archivos y horarios. No necesitás arrancar con una campaña completa para descubrir que estabas apuntando al cliente equivocado.

Definí qué credencial pertenece a cada cliente

Abrí Configuración → Developers y revisá los requisitos de acceso de tu cuenta antes de crear la key. Elegí proyecto y permisos; guardá el token en el servidor o en un almacén de secretos, fuera del código que recibe el navegador.

La autenticación usa Authorization: Bearer <token>. Mandá también Accept: application/json; cuando enviás JSON, agregá Content-Type: application/json. Eso facilita tratar respuestas y errores dentro de tu integración.

Si trabajás para varias marcas, mantené una relación explícita entre tu identificador de cliente y la key correspondiente. Un header de espacio enviado por el navegador no debería reemplazar esa decisión del servidor.

Registrá nombre de operación e ID devuelto, sin guardar el header de autorización. Necesitás poder investigar un borrador fallido sin convertir cada log en otra copia del secreto.

Consultá cuentas antes de elegir destino

La ruta para listar cuentas conectadas es:

GET https://postbean.app/api/social-accounts
Authorization: Bearer <token>
Accept: application/json

Requiere accounts:read. Usá los IDs devueltos para construir la lista de destinos. No mezcles tipos: un usuario de red, un ID numérico de cuenta y el ID público de una publicación identifican cosas distintas.

Durante la configuración, pedile a una persona que confirme plataforma y usuario. Guardá esa selección. Elegir siempre “la primera cuenta de LinkedIn” deja de funcionar cuando alguien conecta otra cuenta o cambia el orden de la respuesta.

La conexión de redes se hace desde el panel. Tu integración trabaja sobre cuentas ya autorizadas; no necesita pedir la contraseña de Instagram ni pasarla como parte del payload para publicar.

Creá un borrador sin depender de valores implícitos

Este ejemplo usa 42 como ID ilustrativo. Reemplazalo por una cuenta real del espacio:

POST https://postbean.app/api/posts
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

{
  "caption": "Ya podés consultar las fechas de los talleres de diciembre.",
  "post_type": "text",
  "draft": true,
  "social_account_ids": [42]
}

La ruta requiere drafts:write y el usuario debe tener autorización para crear contenido. Probalo con una red que admita texto; un destino que exige imagen o video necesita otro tipo de publicación.

draft: true es una decisión funcional. Si omitís borrador y fecha, el flujo de creación puede dejar el post en cola para salir inmediatamente. El nombre de tu paso, aunque diga “revisión”, no modifica el estado que mandás.

Guardá el ID público devuelto, un ULID, y consultá GET /api/posts/{post}. La respuesta REST representa un recurso. Mirá su estructura al mapear los datos; no supongas que coincide exactamente con el formato presentado por una herramienta de chat.

Corregí sobre el mismo objeto

Para editar existe PATCH /api/posts/{post}. Si una persona cambia el cierre del caption, actualizá la publicación existente. Crear otra fila por cada corrección vuelve incierto qué versión sigue vinculada con tu sistema.

Las versiones por red usan platform_overrides:

{
  "platform_overrides": {
    "threads": {
      "caption": "Ya están las fechas de diciembre. Consultalas en la página de reservas."
    }
  }
}

El destino tiene que formar parte de las cuentas seleccionadas. Podés mantener un texto general más largo y reducir solamente Threads. La validación mide el caption efectivo que corresponde a cada cuenta.

Prestá atención a las listas que reemplazan contenido. media_ids indica todos los archivos que querés conservar, en su orden final. Mandar solamente el ID nuevo no significa agregarlo a los anteriores. Si tu interfaz permite sumar una foto, primero recuperá lo que ya estaba adjunto.

Subí archivos mediante tres solicitudes

Para un archivo local, reservá una subida con POST /api/media/upload-url. El cuerpo incluye file_name, mime_type y size_bytes. La respuesta entrega media_id y upload_url.

Después mandá los bytes mediante PUT a esa URL devuelta. Ya viene firmada: no agregues el bearer token. El tipo de contenido tiene que coincidir con el MIME que declaraste al reservar. No armes la URL firmada a mano.

Por último confirmá con POST /api/media, enviando por ejemplo {"media_id":51}. El ID sirve para adjuntar el archivo en media_ids. La transferencia puede haber terminado aunque siga pendiente el procesamiento de dimensiones o miniatura; tratá esas etapas por separado.

Los topes configurados son 8 MiB por imagen y 100 MiB por video: cada MiB equivale a 1.024 × 1.024 bytes. Podés detectar excesos antes de transferir, pero la respuesta del servidor sigue siendo la autoridad. Además, cada red puede imponer requisitos propios sobre el contenido que acepta.

Programar también requiere una decisión de salida

Al crear una publicación programada, mandá un scheduled_at futuro y draft: false. Hacelo después de revisar contenido y destinos. Si actualizás un borrador existente, consultá después el estado resultante; no deduzcas que quedó programado porque guardaste una fecha en tu base.

Una fecha sin offset se interpreta en la zona del espacio de Postbean. Una fecha con offset o Z identifica un instante preciso. Tu interfaz debería mostrar qué zona está usando y qué horario va a recibir la persona que aprueba.

Para publicar inmediatamente una publicación existente, usá POST /api/posts/{post}/publish-now, que requiere posts:publish. Para cancelar programación existe POST /api/posts/{post}/cancel. No simules “publicar ahora” con una fecha pasada.

La API también permite PATCH /api/posts/{post}/targets/{target}/schedule para una red particular. Tomá el target de la representación del post y comprobá su relación con la publicación elegida.

Separá errores corregibles de reintentos técnicos

Un caption demasiado largo necesita edición. Postbean expone problemas de publicación y puede rechazar programación o envío con HTTP 422. Guardá el mensaje y mostralo donde la persona pueda corregir el contenido.

Un error de scope o autorización requiere revisar credenciales o acceso. Repetir solicitudes no lo resuelve. Para TikTok, consultá GET /api/social-accounts/{account}/tiktok/creator-info antes de elegir audiencia: sus opciones dependen de la cuenta.

Si una creación vence por timeout, buscá evidencia de que ya se guardó antes de repetirla. No asumas un header de idempotencia que el endpoint no documenta. Mantené en tu integración una relación entre evento de origen, intento e ID de Postbean para detectar duplicados.

Mostrá el error junto a la operación que lo provocó. Quien edita necesita saber qué contenido falló y si el problema apareció al transferir archivo, guardar borrador o publicar. Esa diferencia permite recuperar una etapa sin volver a ejecutar todas. Conservá mensajes útiles, pero quitá credenciales y URLs firmadas de los registros compartidos.

Antes de agregar tandas, probá enviar dos veces el mismo evento de origen. Tu integración debería reutilizar el ID guardado o frenar el segundo intento para revisarlo. Ensayá también un borrador creado correctamente seguido de una subida fallida: recuperar ese archivo no debería crear otra publicación. Son pruebas de tu cliente API, no garantías de idempotencia que debas atribuir al servidor.

Comprobá qué pasó después del envío

GET /api/posts/{post}/status permite consultar el resultado. “En cola” o “programado” todavía no demuestra aceptación por parte de una red. Mirá también el resultado individual cuando hay varias cuentas destino.

Para reintentar una sola red existe POST /api/posts/{post}/targets/{target}/retry, con permiso de publicación. Primero resolvé la causa del error. Un cliente que recrea todo el post puede duplicar las salidas que ya habían funcionado.

Tu primera versión puede limitarse a un espacio, una cuenta confirmada y borradores explícitos. Agregá lo demás cuando puedas explicar cada respuesta y cada falla. Consultá la guía de acceso y el ejemplo con herramientas de automatización para seguir desde esa base.

Fuentes

Escribilo una vez. Publicalo en todos lados.

Conectá tus redes y programá tu primer post en pocos minutos. Plan gratis, sin tarjeta.

Creá tu cuenta gratis