API de SOSPosting para desarrolladores

Autenticación

Cada petición lleva una clave de API en la cabecera Authorization:

Authorization: Bearer sosp_<your key>

Crea tus claves en la consola, en Settings → API access (app.sosposting.com). Cada clave pertenece al negocio en el que se creó: publica en sus plataformas conectadas y gasta su monedero de tokens. La clave se muestra una sola vez al crearla — guárdala como una contraseña y revócala cuando quieras desde la misma pantalla.

URL base: https://app.sosposting.com. Las peticiones y respuestas son JSON. Una publicación por API cuesta exactamente los mismos tokens que la misma publicación hecha desde el panel — consulta los precios.

POST /api/v1/posts — crear una publicación

Una llamada llega a todas las plataformas seleccionadas. Campos del payload:

• type (obligatorio) — "reel", "social", "product" o "blog".
• mediaUrl — URL pública https:// de la imagen o el vídeo (usa el endpoint de presign si no alojas los medios tú mismo).
• title, caption — tu texto; con useAi activado, la IA lo convierte en captions, títulos y hashtags nativos por plataforma.
• providers — array como ["INSTAGRAM","FACEBOOK","TIKTOK"]; por defecto, todas las plataformas conectadas elegibles para ese tipo de publicación.
• useAi — por defecto true; ponlo en false para publicar tu texto literal.
• scheduledAt — fecha ISO 8601 para programar en lugar de publicar al momento.

curl -X POST https://app.sosposting.com/api/v1/posts \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reel",
    "mediaUrl": "https://example.com/clip.mp4",
    "title": "Summer drop",
    "caption": "Our new summer collection is live",
    "providers": ["INSTAGRAM", "FACEBOOK", "YOUTUBE"],
    "useAi": true,
    "scheduledAt": "2026-08-01T09:00:00Z"
  }'

Devuelve 201 con el id de la publicación y un target por plataforma:

{
  "id": "cmcz...",
  "scheduledAt": "2026-08-01T09:00:00.000Z",
  "targets": [
    { "id": "t1...", "status": "QUEUED" },
    { "id": "t2...", "status": "QUEUED" }
  ]
}

GET /api/v1/posts/:id — estado y métricas

Consulta la publicación para ver cómo fue la entrega y cómo rinde. El estado de entrega se devuelve para todos los targets; las métricas de interacción solo se consultan en Facebook, Instagram y YouTube — las plataformas cuyas APIs nos exponen estadísticas por publicación. Las métricas se actualizan como máximo una vez por hora, bajo demanda:

curl https://app.sosposting.com/api/v1/posts/cmcz... \
  -H "Authorization: Bearer sosp_..."

{
  "id": "cmcz...",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "scheduledAt": null,
  "status": "POSTED",
  "targets": [
    {
      "provider": "INSTAGRAM",
      "status": "POSTED",
      "externalId": "1789...",
      "externalUrl": "https://www.instagram.com/p/...",
      "error": null,
      "metrics": { "views": 1200, "likes": 88, "comments": 7 }
    }
  ]
}

• El status global resume los targets: QUEUED, SCHEDULED (esperando su hora programada), PROCESSING, POSTED, PARTIAL, FAILED o SKIPPED.
• Los targets de TikTok muestran PENDING_USER mientras el vídeo espera en los borradores de TikTok una publicación manual — aún no está en línea, así que no tiene externalUrl.
• metrics solo se rellena en los targets de FACEBOOK, INSTAGRAM y YOUTUBE; el resto de plataformas (TikTok, Pinterest, LinkedIn, Threads, Bluesky, WordPress, Shopify) devuelven siempre metrics: null. Incluso en una plataforma compatible es null hasta la primera actualización tras la entrega, y cada clave se omite si la plataforma no la reporta — shares solo llega de Facebook y views, de las publicaciones de vídeo. metricsAt indica cuándo se actualizaron por última vez.
• Los ids desconocidos o de otro cliente devuelven 404.

POST /api/v1/media/presign — sube medios sin tu propio bucket

Pide una subida prefirmada, haz PUT con los bytes y usa el publicUrl devuelto como mediaUrl al crear la publicación:

curl -X POST https://app.sosposting.com/api/v1/media/presign \
  -H "Authorization: Bearer sosp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "contentType": "video/mp4",
    "sizeBytes": 10485760
  }'

{
  "uploadUrl": "https://...r2.cloudflarestorage.com/...",
  "publicUrl": "https://media.../uploads/....mp4",
  "key": "uploads/....mp4"
}

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --data-binary @clip.mp4

Límites: imágenes hasta 25 MB, vídeos hasta 50 MB. sizeBytes es obligatorio (si falta, 400). Los tipos no soportados se rechazan con 415; los archivos demasiado grandes, con 413; las peticiones tienen límite de frecuencia por negocio (429).

Tokens y errores

• El mismo precio que el panel: una publicación por API se cobra con los mismos tokens que la publicación idéntica hecha en la consola. Las entregas que fallan por nuestra parte se reembolsan automáticamente.
• Los errores devuelven un cuerpo JSON { "error": "...", "code": "..." } — el code es un valor estable legible por máquina (p. ej. insufficient_tokens, rate_limited) — con el código habitual: 400 petición incorrecta, 401 clave inválida, 402 tokens insuficientes, 404 no encontrado, 413/415 límites de medios, 429 demasiadas peticiones.

Conviene saber

• Conecta tus plataformas una vez en la consola — la API publica a través de las mismas integraciones (en inglés).
• ¿Gestionas varias marcas? Cada negocio tiene su propia clave y sus cuentas conectadas, y los negocios de una misma cuenta comparten un único monedero de tokens — sin cuotas por puesto ni por espacio de trabajo.
• La API está versionada bajo /api/v1/; los cambios son aditivos.