Descripción general de la API

URL base https://api.sofia-post.com/api · Documento OpenAPI

Sofia API da a tu código acceso a tu cuenta de Sofia: los establecimientos de tus Workspaces, sus redes conectadas, su biblioteca multimedia, sus publicaciones y sus estadísticas. Es una API REST sobre HTTPS; las solicitudes y las respuestas son JSON. Permite:

• Publicar: ahora, en una fecha o como borrador, en una o varias redes a la vez.
• Comprobar antes de publicar: una simulación te dice si cada red aceptaría la publicación, sin escribir nada.
• Gestionar los archivos: sube un archivo o impórtalo desde una URL a la biblioteca multimedia de un establecimiento.
• Seguir las publicaciones: lee el estado de cada red, su enlace permanente o el motivo del error. Un webhook firmado también puede avisarte.
• Leer las estadísticas: las últimas cifras recopiladas por Sofia para cada cuenta conectada.
• Conectar redes: crea un enlace alojado que permite al propietario conectar una red que falta.

SDK e integraciones

• CLI `sofia`: la CLI, publicada en npm con el nombre sofia-post, para manejar Sofia desde un terminal.
• Servidor MCP: conecta Sofia a tus agentes de IA.
• Zapier: la integración de Sofia se conecta con tu clave personal. Ofrece los disparadores «Post Published» y «Post Failed», la acción «Create Post» (publicar, programar o guardar un borrador) y la búsqueda «Find Post». Todavía no se ha enviado al directorio público de Zapier.

Autenticación

Cada llamada lleva un token Bearer en la cabecera Authorization. Sofia vuelve a leer los derechos asociados en cada llamada: una persona retirada de un Workspace, o una autorización revocada, detiene el token desde la solicitud siguiente.

Hay dos formas de autenticarse:

Clave de API

Si automatizas tu propio Workspace, basta una clave personal. En la app de Sofia, abre Ajustes › API, pestaña Acceso personal, y crea una clave. Elige su nombre, su caducidad y sus permisos. La clave solo se muestra una vez: cópiala y guárdala en una caja fuerte de secretos, nunca en tu código.

Crea una clave en Ajustes › API › Acceso personal. Actúa por ti en todos tus Workspaces: el establecimiento que nombras determina el Workspace, y tu rol en él decide lo que la clave puede hacer.

Envía la clave en la cabecera Authorization, como token Bearer:

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

`GET /v1/me` te indica por quién actúa la clave, sus Workspaces y sus permisos.

Una llamada sin el permiso (el scope) necesario responde 403 insufficient_scope.

Token OAuth2

Para un producto SaaS que actúa por sus usuarios en sus propios Workspaces, registra un cliente OAuth: cada persona autoriza tu aplicación en el Workspace que elija. Los tokens de acceso OAuth empiezan por sofia_live_at_…, duran una hora y se usan del mismo modo:

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_live_at_…"

¿Creas una app a la que se conectan otras cuentas de Sofia? Su flujo authorization code con PKCE, sus client credentials y sus scopes se describen en OAuth2.

URL base

Cada endpoint se encuentra bajo una única URL base:

https://api.sofia-post.com/api/v1

Límites de frecuencia

Sofia API cuenta las solicitudes en tres ventanas: 15 minutos, 24 horas y 30 días.

Cabeceras

Cada respuesta te dice lo que queda, en formato IETF:

RateLimit: "15m";r=144;t=43, "24h";r=994;t=13543, "30d";r=9994;t=13543
RateLimit-Policy: "15m";q=150;w=900, "24h";q=1000;w=86400, "30d";q=10000;w=2592000

r es el número de solicitudes restantes, t los segundos antes de que se reinicie la ventana, q la cuota y w la ventana en segundos.

Cuando una ventana está llena

La respuesta es 429 rate_limit_exceeded, con una cabecera Retry-After y la ventana agotada en details. Espera ese plazo antes de reintentar.

Usar la API con eficacia

• Registra un webhook en lugar de consultar una publicación en bucle.
• Usa limit hasta 100 para leer las listas en menos páginas.
• Guarda en caché lo que cambia poco: plataformas, establecimientos, cuentas conectadas.

Errores

Cada error responde con un estado HTTP y el mismo sobre JSON. code es el contrato que lee tu código; message está escrito para una persona y puede cambiar.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

• details dice más: el campo rechazado, el motivo de una red, la ventana de límite agotada.
• docUrl lleva a la explicación del código en esta página.
• requestId identifica la solicitud: comunícaselo al soporte.

Códigos de error

Motivos de una publicación rechazada

Un post_refused lista cada motivo en details[].code:

Gestionar los errores

• Basa tu lógica en code, nunca en message.
• Reintenta un 429 después de Retry-After, y un 5xx con un backoff exponencial.
• No reintentes nunca un 4xx idéntico: corrige primero la solicitud.
• Registra requestId en cada fallo.

Paginación

Las listas (GET /v1/posts, GET /v1/media) se devuelven con las más recientes primero, una página cada vez. limit fija el tamaño de página, de 1 a 100 (20 por defecto).

{
  "data": [ … ],
  "nextCursor": "WyIyMDI2LTEwLTI3VDE1OjExOjU5LjAxN1oiLCIx…"
}

Pasa nextCursor como cursor para leer la página siguiente. Cuando nextCursor no aparece, has llegado al final.

let cursor;
do {
  const url = new URL('https://api.sofia-post.com/api/v1/posts');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await globalThis.fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
  handle(page.data);
  cursor = page.nextCursor;
} while (cursor);

Un cursor es opaco: nunca lo construyas ni lo modifiques. Un cursor que Sofia no ha devuelto responde 400 invalid_cursor.

Idempotencia

Un error de red puede dejarte con la duda sobre la creación de una publicación. Envía una cabecera Idempotency-Key con POST /v1/posts y POST /v1/media, y reintenta con la misma clave: Sofia responde lo que respondió la primera vez, y no crea nada por duplicado.

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d @post.json

• Usa una clave aleatoria nueva (un UUID) para cada publicación nueva, y la misma clave para cada nuevo intento de esa publicación.
• La misma clave con un cuerpo distinto responde 422 idempotency_key_reused.
• Mientras la primera solicitud está en curso, la misma clave responde 409 idempotency_in_progress: reintenta un momento después.

Modo de prueba y simulación

Simulación. Añade ?dry_run=true a POST /v1/posts: Sofia ejecuta las comprobaciones de una publicación real (las reglas de cada red, la cuenta conectada, los archivos, la fecha y tu plan) sin guardar ni enviar nada. El detalle de las respuestas está en la página Publicar.

Modo de prueba. Una aplicación creada en modo test (tokens sofia_test_at_…) lee tu Workspace real pero nunca escribe en él: sus publicaciones se simulan y se juzgan con las mismas reglas, y toda escritura real responde 403 live_mode_required. Las claves y los clientes creados en Ajustes › API están en modo live; usa la simulación para comprobar sin publicar.