Обзор API

Базовый URL https://api.sofia-post.com/api · Документ OpenAPI

Sofia API даёт вашему коду доступ к вашему аккаунту Sofia: заведениям ваших Workspaces, их подключённым сетям, медиатеке, публикациям и статистике. Это REST API по HTTPS; запросы и ответы — в JSON. Оно позволяет:

• Публиковать: сейчас, в назначенную дату или черновиком, в одну или несколько сетей сразу.
• Проверять перед публикацией: симуляция сообщает, приняла бы каждая сеть публикацию, ничего не записывая.
• Управлять медиа: загружайте файл или импортируйте его по URL в медиатеку заведения.
• Отслеживать публикации: читайте статус каждой сети, её постоянную ссылку или причину сбоя. Подписанный вебхук тоже может вас уведомить.
• Читать статистику: последние цифры, собранные Sofia по каждому подключённому аккаунту.
• Подключать сети: создайте размещённую ссылку, по которой владелец подключит недостающую сеть.

SDK и интеграции

• CLI `sofia`: CLI, опубликованный в npm под именем sofia-post, для управления Sofia из терминала.
• Сервер MCP: подключите Sofia к вашим ИИ-агентам.
• Zapier: интеграция Sofia подключается с вашим личным ключом. Она предлагает триггеры «Post Published» и «Post Failed», действие «Create Post» (опубликовать, запланировать или сохранить черновик) и поиск «Find Post». Она ещё не подана в публичный каталог Zapier.

Аутентификация

Каждый вызов несёт токен Bearer в заголовке Authorization. Sofia перечитывает связанные с ним права при каждом вызове: человек, удалённый из Workspace, или отозванное разрешение останавливает токен со следующего запроса.

Аутентифицироваться можно двумя способами:

Ключ API

Если вы автоматизируете собственный Workspace, достаточно личного ключа. В приложении Sofia откройте Настройки › API, вкладку Личный доступ, и создайте ключ. Выберите его название, срок действия и разрешения. Ключ показывается один раз: скопируйте его и храните в хранилище секретов, но не в коде.

Создайте ключ в Настройки › API › Личный доступ. Он действует от вашего имени во всех ваших Workspaces: названное вами заведение определяет Workspace, а ваша роль в нём — что ключ может делать.

Передавайте ключ в заголовке Authorization как токен Bearer:

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

`GET /v1/me` сообщает, от чьего имени действует ключ, его Workspaces и разрешения.

Вызов без нужного разрешения (scope) возвращает 403 insufficient_scope.

Токен OAuth2

Для SaaS-продукта, действующего от имени своих пользователей в их собственных Workspaces, зарегистрируйте клиента OAuth: каждый человек авторизует ваше приложение в выбранном им Workspace. Токены доступа OAuth начинаются с sofia_live_at_…, живут час и используются так же:

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

Создаёте приложение, к которому подключаются другие аккаунты Sofia? Его процесс authorization code с PKCE, client credentials и scopes описаны в OAuth2.

Базовый URL

Каждый endpoint находится под одним базовым URL:

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

Лимиты запросов

Sofia API считает запросы в трёх окнах: 15 минут, 24 часа и 30 дней.

Заголовки

Каждый ответ сообщает, сколько осталось, в формате 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 — число оставшихся запросов, t — секунды до сброса окна, q — квота, w — окно в секундах.

Когда окно заполнено

Ответ — 429 rate_limit_exceeded с заголовком Retry-After и исчерпанным окном в details. Подождите указанное время, прежде чем повторять.

Как эффективно использовать API

• Зарегистрируйте вебхук вместо того, чтобы в цикле опрашивать публикацию.
• Используйте limit до 100, чтобы читать списки за меньшее число страниц.
• Кэшируйте то, что меняется редко: платформы, заведения, подключённые аккаунты.

Ошибки

Каждая ошибка возвращается со статусом HTTP и одним и тем же JSON-конвертом. code — контракт, который читает ваш код; message написано для человека и может меняться.

{
  "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 сообщает больше: отклонённое поле, причину сети, исчерпанное окно лимита.
• docUrl ведёт к объяснению кода на этой странице.
• requestId идентифицирует запрос: сообщите его в поддержку.

Коды ошибок

Причины отклонения публикации

post_refused перечисляет каждую причину в details[].code:

Обработка ошибок

• Стройте логику на code, а не на message.
• Повторяйте 429 после Retry-After, а 5xx — с экспоненциальной задержкой.
• Никогда не повторяйте 4xx без изменений: сначала исправьте запрос.
• Записывайте requestId при каждой ошибке.

Пагинация

Списки (GET /v1/posts, GET /v1/media) возвращаются начиная с самых свежих, по одной странице. limit задаёт размер страницы от 1 до 100 (по умолчанию 20).

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

Передайте nextCursor как cursor, чтобы прочитать следующую страницу. Когда nextCursor отсутствует, вы достигли конца.

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);

Курсор непрозрачен: никогда не составляйте и не изменяйте его. Курсор, который Sofia не возвращала, получает ответ 400 invalid_cursor.

Идемпотентность

Сетевая ошибка может оставить вас в сомнении, создана ли публикация. Отправьте заголовок Idempotency-Key с POST /v1/posts и POST /v1/media и повторите с тем же ключом: Sofia вернёт то, что ответила в первый раз, и ничего не создаст дважды.

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

• Используйте новый случайный ключ (UUID) для каждой новой публикации и тот же ключ для каждой повторной попытки этой публикации.
• Тот же ключ с другим телом возвращает 422 idempotency_key_reused.
• Пока первый запрос выполняется, тот же ключ возвращает 409 idempotency_in_progress: повторите чуть позже.

Тестовый режим и симуляция

Симуляция. Добавьте ?dry_run=true к POST /v1/posts: Sofia выполняет проверки настоящей публикации (правила каждой сети, подключённый аккаунт, медиа, дату и ваш тариф), ничего не сохраняя и не отправляя. Подробности ответов — на странице Публикация.

Тестовый режим. Приложение, созданное в режиме test (токены sofia_test_at_…), читает ваш настоящий Workspace, но никогда в него не пишет: его публикации симулируются и оцениваются по тем же правилам, а любая реальная запись возвращает 403 live_mode_required. Ключи и клиенты, созданные в Настройки › API, работают в режиме live; для проверки без публикации используйте симуляцию.