Publicaciones y programación

Obtener una clave de API

Una publicación pertenece a un establecimiento y va a una o varias redes, sus destinos (targets). Cada destino tiene su propio texto, sus medios, su formato y su propio estado.

Endpoints

POST/v1/postsGET/v1/postsGET/v1/posts/{id}PATCH/v1/posts/{id}DELETE/v1/posts/{id}

El cuerpo de una publicación

Campo	Significado
`establishmentId`	El establecimiento que publica (`GET /v1/establishments`)
`targets[]`	Una entrada por red: `platform`, `text`, y opcionalmente `media`, `format` y `accountId`
`targets[].media[]`	Un medio de la biblioteca por su `id`, o una `url` https pública con su `type` (`image` o `video`)
`targets[].accountId`	La cuenta que se usará cuando el establecimiento tiene varias en esa red
`scheduledAt`	Una fecha y hora ISO 8601 futura; si falta, la publicación sale ahora
`status`	`draft` para guardar un borrador que no sale (entonces sin `scheduledAt`)

Estados

Estado	Significado
`draft`	Guardada, no sale
`scheduled`	Saldrá en `scheduledAt`
`publishing`	Enviándose a la red
`published`	En línea, con su `permalink`
`failed`	La red la rechazó; `error` dice por qué
`sent_to_inbox`	Enviada a la app de la red, donde el propietario la termina (TikTok)

El status de la publicación resume sus destinos. Es partial cuando una red publicó y otra falló.

Editar antes de la salida

PATCH /v1/posts/{id} reescribe los destinos, mueve scheduledAt o cambia status: draft quita la hora y conserva el contenido, scheduled la vuelve a programar. Una vez que una red ha enviado la publicación, responde 409 post_not_editable.

bash

curl -X PATCH https://api.sofia-post.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"scheduled","scheduledAt":"2026-11-20T09:00:00Z"}'

Eliminar

DELETE /v1/posts/{id} responde 204. Mientras una red está enviando la publicación, responde 409 post_in_flight: reintenta un momento después.

Listar publicaciones

GET /v1/posts lista todas las publicaciones a las que el token puede acceder, las más recientes primero, filtradas por establishmentId, status, from, to y createdBy (me o app). Una publicación coincide con status cuando al menos una de sus redes está en ese estado. Consulta la paginación.