API управления компанией

API для серверов компании, которая подключена к xWires: кадровой системы, учёта, согласований, своих сервисов. Почти всё, что система делает через API, админ компании может и в кабинете («Компания»); подписку по session сотрудника там оформляет оператор xWires:

Об изменениях API сообщает лентой событий, а вебхуки присылают их на адреса ваших систем (раздел 13). Только в кабинете остаются ключи API и адреса вебхуков, назначение и снятие админов, отметка «Уволился» у админа, ссылка для сотрудников и номера для подтверждения ChatGPT.

Это не API к моделям. OpenAI-совместимый API к DeepSeek, GLM и Kimi — другой продукт со своими ключами, он описан на странице «API к моделям». Ключ API управления к нему не подходит, и наоборот.

1. Админ компании открывает «Компания → Интеграции» и в «Ключах API» создаёт ключ: название, например «1С: кадры», и доступ — «Только чтение» или «Чтение и действия». Ключ показывается один раз, скопируйте его сразу. Всем админам компании придёт письмо о новом ключе.
2. Положите ключ в секреты сервера, который ходит в API, под именем XWIRES_COMPANY_API_KEY. В код, репозиторий, браузер и мобильное приложение ключ не попадает.
3. Проверьте ключ:

curl -sS https://api.xwires.ai/company/v1/me \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

{
  "key": {
    "id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60",
    "name": "1С: кадры",
    "access": "manage",
    "last4": "a91f",
    "created_at": "2026-10-15T09:12:40.118204+00:00"
  },
  "company": {
    "id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
    "name": "Ромашка"
  }
}

Postman, Insomnia и генераторы клиентов берут описание API по ссылке: Import → Link → https://api.xwires.ai/company/v1/openapi.json. Ключ укажите в Authorization как Bearer Token. Статусы, типы событий и другие значения в ответах в v1 только добавляются, поэтому в описании они перечислены в x-extensible-enum, а не в закрытом enum: генератор делает из них строки, и новое значение не ломает разбор ответа. Событие нового типа подходит под схему UnknownEvent, последнюю в Event и WebhookEvent.

Тот же запрос и список заказов, которые ждут подтверждения, из кода:

const BASE = "https://api.xwires.ai/company/v1";

// Один запрос к API: ответ как объект, ошибка как исключение с status, code и request_id.
// error.retryAfter — через сколько секунд повторить, когда повтор поможет: 429 rate_limited, 503,
// сбой сети и ответ не от API (прокси, пока xWires перезапускается).
async function xwires(method, path, body) {
  let response;
  try {
    response = await fetch(BASE + path, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.XWIRES_COMPANY_API_KEY}`,
        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
      },
      body: body === undefined ? undefined : JSON.stringify(body),
    });
  } catch (cause) {
    throw Object.assign(new Error(`xWires не ответил: ${cause.message}`), { retryAfter: 5 });
  }
  if (response.status === 204) return null;
  const data = await response.json().catch(() => null);
  if (response.ok) return data;
  const retryAfter = Number(response.headers.get("Retry-After")) || null;
  if (!data?.error) {
    // Не ответ API: 405 у адреса без такого метода или 502 и 504 прокси, пока xWires перезапускается.
    throw Object.assign(new Error(`${response.status} без ответа API`), {
      status: response.status,
      retryAfter: retryAfter ?? (response.status >= 500 ? 5 : null),
    });
  }
  const { code, message, request_id } = data.error;
  throw Object.assign(new Error(`${response.status} ${code}: ${message} (request_id ${request_id})`), {
    status: response.status,
    code,
    retryAfter,
  });
}

const me = await xwires("GET", "/me");
console.log(me.company.name, me.key.access);

const waiting = await xwires("GET", "/orders?status=awaiting_approval");
for (const order of waiting.data) console.log(order.id, order.plan, order.employee?.email);

# pip install requests
import os

import requests

BASE = "https://api.xwires.ai/company/v1"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["XWIRES_COMPANY_API_KEY"]


class XWiresError(Exception):
    # status и code — из ответа API. retry_after — через сколько секунд повторить, когда повтор поможет:
    # 429 rate_limited, 503, сбой сети и ответ не от API (прокси, пока xWires перезапускается).
    def __init__(self, message, status=None, code=None, retry_after=None):
        super().__init__(message)
        self.status = status
        self.code = code
        self.retry_after = retry_after


# Один запрос к API: ответ как словарь, ошибка как XWiresError с кодом и request_id.
def xwires(method, path, body=None, params=None):
    try:
        response = session.request(method, BASE + path, json=body, params=params, timeout=30)
    except requests.RequestException as error:
        raise XWiresError(f"xWires не ответил: {error}", retry_after=5) from error
    if response.status_code == 204:
        return None
    try:
        data = response.json()
    except ValueError:
        data = None
    if response.ok:
        return data
    header = response.headers.get("Retry-After", "")
    retry_after = int(header) if header.isdigit() else None
    if not isinstance(data, dict) or "error" not in data:
        # Не ответ API: 405 у адреса без такого метода или 502 и 504 прокси, пока xWires перезапускается.
        if retry_after is None and response.status_code >= 500:
            retry_after = 5
        raise XWiresError(f"{response.status_code} без ответа API", response.status_code, None, retry_after)
    error = data["error"]
    raise XWiresError(
        f'{response.status_code} {error["code"]}: {error["message"]} (request_id {error["request_id"]})',
        response.status_code,
        error["code"],
        retry_after,
    )


me = xwires("GET", "/me")
print(me["company"]["name"], me["key"]["access"])

waiting = xwires("GET", "/orders", params={"status": "awaiting_approval"})
for order in waiting["data"]:
    print(order["id"], order["plan"], (order["employee"] or {}).get("email"))

Ключ — xwc_ и 64 шестнадцатеричных символа, ключ песочницы — xwc_test_ и 64 (раздел 11). Передавайте его только в заголовке Authorization: Bearer xwc_…. Без ключа, с испорченным или незнакомым ключом ответ — 401 invalid_api_key.

Доступ задают при выпуске, изменить его нельзя: выпустите новый ключ.

Ключ принадлежит компании

Ключ действует от имени компании, а не админа, который его выпустил, и работает, пока его не отзовут: и когда этого админа сняли с роли, отметили уволившимся или удалили, и когда у компании не осталось ни одного админа. В заказе, почте и приглашении, которые сделал ключ, записан ключ, а не человек.

Отзыв и смена

• Отозвать ключ может любой админ компании в «Интеграциях» и оператор xWires, навсегда. Запросы, которые идут в момент отзыва, успеют завершиться, следующие получат 401 api_key_revoked.
• Отзывая ключ, можно удалить и неиспользованные почты и приглашения, которые он добавил. Снимая человека с роли админа или отмечая уволившимся, админ может сразу отозвать выпущенные им ключи.
• Сменить ключ: выпустите новый, переключите на него систему, отзовите старый. У компании может быть до 10 действующих ключей, так что старый и новый поработают вместе.
• Уходит человек, у которого могла остаться копия ключа, — админ, разработчик интеграции, подрядчик: смените ключ.

Только с сервера

Запросы к API — только с ваших серверов: из браузера API не вызвать, заголовков CORS нет и cookies не читаются. В адресе запроса ключ не передавайте: адреса попадают в логи, такой запрос получит 400 api_key_in_url, а ключ стоит отозвать.

Свои действия

У заказа, который подтвердил ключ, approved_via: "api_key" и approved_by_api_key_id; у события, которое вызвал запрос ключа, — actor.api_key_id. Сравнивайте их с key.id из GET /me: так система отличит эхо своих действий от чужих.

В кабинете ключ виден как xwc_…a91f (последние символы — key.last4), с временем последнего успешного запроса, а «Что сделали ключи» показывает последние изменения через API. Чтение не записывается, IP-адреса мы не храним.

• Тело запроса — JSON в UTF-8 с Content-Type: application/json, до 256 КБ, и приходит целиком за 10 секунд, иначе 415 unsupported_media_type, 413 payload_too_large или 408 request_timeout. Подтверждение, отказ и увольнение шлите без тела или с {}.
• Ответ — JSON в UTF-8, кроме 204 без тела у удаления и отзыва. Ответы не кэшируются (Cache-Control: no-store).
• Идентификаторы — uuid. Время — RFC 3339 (ISO 8601) со смещением +00:00, как его отдаёт база: 2026-10-15T09:30:12.345678+00:00. В доле секунды от 0 до 6 цифр: нули в конце база отбрасывает. Разбирайте время полным разбором RFC 3339 — Date.parse в Node.js, datetime.fromisoformat в Python 3.11+, dateutil.parser.isoparse в более ранних, — а не шаблоном фиксированной длины. Цен в API нет: стоимость подписок xWires согласует с компанией отдельно.
• Поля, значения и типы событий в v1 только добавляются. Незнакомые поля и типы событий пропускайте, незнакомый статус заказа считайте «в работе».
• Каждый ответ, и ошибка тоже, несёт заголовок X-Request-Id: назовите его поддержке, если что-то пошло не так. Ответы на запросы с ключом несут и RateLimit-* (раздел 8).
• Почты в адресах не передаются: поиск сотрудника по почте — POST /employees/search с почтой в теле.

Ошибка — JSON с кодом. Решения принимайте по code: message написан для человека и может меняться.

{
  "error": {
    "code": "order_not_awaiting_approval",
    "message": "Заказ не ждёт подтверждения: его уже подтвердили, отклонили или отменили. Прочитайте заказ.",
    "request_id": "d2f6b8a4-9e1c-4a37-85d0-6c3b7e9f1a42"
  }
}

details есть только у invalid_request: пути полей и коды проверки, без присланных значений.

{
  "error": {
    "code": "invalid_request",
    "message": "Запрос не прошёл проверку: details.issues называет поля и что с ними не так.",
    "request_id": "d2f6b8a4-9e1c-4a37-85d0-6c3b7e9f1a42",
    "details": {
      "issues": [
        {
          "path": "state",
          "issue": "unrecognized_keys"
        }
      ]
    }
  }
}

• 405 без нашего JSON — у адреса нет такого метода.
• 429: на rate_limited подождите столько секунд, сколько в Retry-After. У api_email_quota_exceeded заголовка нет: суточный лимит освобождается постепенно.
• 500 — ошибка у нас: сначала прочитайте данные, потом повторяйте. Не проходит — напишите в поддержку с request_id. 503 приходит с Retry-After: 1: повторите через секунду.

Страницы

Списки отдают до limit строк (от 1 до 200, по умолчанию 100) и next_cursor. Следующая страница — тот же запрос с cursor=<next_cursor>; null — страниц больше нет. Курсор непрозрачный, до 512 символов, и действует только с теми же фильтрами, иначе 400 invalid_cursor. Незнакомый или повторённый параметр — 400 invalid_request.

Сотрудники идут по id, заказы — по времени последнего изменения (updated_at, затем id), почты и приглашения — по времени добавления.

Как держать данные в актуальном виде

Главный способ узнавать об изменениях — лента событий GET /events (раздел 13): в ней те же события, что приходят на вебхуки.

1. Запросите GET /events?after=latest и сохраните next_after, затем один раз прочитайте нужные списки целиком. Именно в таком порядке: изменения, сделанные, пока вы читаете списки, придут и в ленте, а обработчик, которому повтор не вредит, примет их ещё раз без последствий.
2. Раз в 10–60 секунд или на каждый вебхук запрашивайте GET /events?after=<next_after>, обработайте события и сохраните новый next_after. Пока has_more: true, спрашивайте сразу; на 429 rate_limited и 503 service_unavailable подождите Retry-After и повторите.
3. На 410 events_cursor_expired начните заново, как в первом шаге: сначала after=latest и next_after, потом списки, и продолжайте с сохранённой позиции.
4. Раз в сутки, например ночью, читайте весь GET /employees для сверки.

// xwires() — из примера выше. loadAfter, saveAfter, handle и resyncFromLists — ваши:
// храните позицию в своей базе, обрабатывайте событие так, чтобы повтор с тем же id ничего не менял.
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

let after = await loadAfter(); // null — ленту ещё не читали

for (;;) {
  try {
    if (after === null) {
      // Сначала позиция, потом списки: изменения, сделанные во время чтения, придут и в ленте.
      const { next_after } = await xwires("GET", "/events?after=latest");
      await resyncFromLists();
      after = String(next_after);
      await saveAfter(after);
    }
    const page = await xwires("GET", `/events?after=${after}&limit=200`);
    for (const event of page.data) await handle(event);
    after = String(page.next_after);
    await saveAfter(after);
    if (!page.has_more) await sleep(30);
  } catch (error) {
    if (error.code === "events_cursor_expired") {
      // Событий после позиции уже нет: они старше 30 дней, или базу xWires восстановили из копии.
      after = null;
    } else if (error.retryAfter) {
      // 429 и 503, сбой сети или прокси, пока xWires перезапускается: подождите и повторите.
      await sleep(error.retryAfter);
    } else {
      throw error;
    }
  }
}

Дозагрузить заказы помогает updated_since: берите его на минуту раньше последнего updated_at, который видели, и убирайте повторы по паре id и updated_at. + в смещении времени кодируйте как %2B.

curl -sS "https://api.xwires.ai/company/v1/orders?status=succeeded&updated_since=2026-10-01T00:00:00%2B03:00" \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

Заголовка Idempotency-Key нет: каждое действие и так безопасно повторить.

После таймаута или ответа 5xx не повторяйте вслепую: сначала прочитайте заказ, список или сотрудника, потом решайте. Повтор не навредит, но ответ на него скажет больше, если знать, что уже сделано.

RateLimit-Limit — сколько запросов с ключа можно за минуту, RateLimit-Remaining — сколько осталось, RateLimit-Reset — через сколько секунд минута начнётся заново. 429 rate_limited бывает и когда xWires занят запросами других компаний: просто подождите Retry-After.

Новый сотрудник

Кадровая система добавляет почту нового сотрудника в список с планом, который оплачивает компания. Подходит почта, с которой он входит в xWires, или почта его аккаунта ChatGPT.

curl -sS -X POST https://api.xwires.ai/company/v1/approved-emails \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["ivan.sidorov@example.ru","maria.kuznetsova@example.ru"],"plan":"plus"}'

{
  "approved": 1,
  "remembered": 1,
  "skipped": 0,
  "invalid": 0,
  "approved_order_ids": [
    "1d6f8a3c-7e2b-4c95-a0d4-6b9e1f3a7c52"
  ],
  "renews_monthly": false
}

• approved: почта сразу подтвердила заказ, который уже ждал (approved_order_ids); remembered: почта ждёт заказа и подтвердит первый заказ этого плана; skipped: почта уже в списке, уже подтвердила незавершённый заказ этого плана или повторяется в запросе; invalid: не похоже на почту.
• Почта подтверждает один заказ. Пока он не завершён, та же почта или другая почта того же сотрудника с этим планом пропускается, поэтому повтор запроса лишнего заказа не оплатит. Чтобы оплатить и следующий заказ, добавьте почту, когда этот завершится, или подтвердите следующий заказ, когда он придёт.
• Если почта не принадлежит сотруднику компании, на неё уходит письмо: компания оплатит подписку, можно входить в кабинет, — и приглашение в компанию.
• Почта и приглашение удаляются отдельно: DELETE /approved-emails/{id} не отзывает приглашение, для этого есть DELETE /invites/{id}. Принять в компанию, ничего не оплачивая, — POST /invites.
• Заказ с renewal_mode: monthly почта подтверждает, только если её добавили с renews_monthly: true: это согласие компании, что подписка будет продлеваться каждый месяц за её счёт, пока её не отключат. renews_monthly ответа говорит, записано ли согласие: false при true в запросе значит, что подписки компании сейчас не продлеваются каждый месяц. Какие почты списка его несут, показывает GET /approved-emails.

Согласование в вашей системе

Заказ сотрудника ждёт подтверждения компании. Узнайте о нём из события order.awaiting_approval (вебхук или лента) или спрашивайте список раз в несколько минут:

curl -sS "https://api.xwires.ai/company/v1/orders?status=awaiting_approval" \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

renewal_mode заказа — что выбрал сотрудник, он есть и в событии: once — разовая активация на месяц, monthly — с автопродлением. Решает компания: без тела заказ подтверждается разовым, что бы ни выбрал сотрудник. {"renewal": "monthly"} — согласие компании, что подписка будет продлеваться каждый месяц за её счёт, пока её не отключат; его можно дать и заказу, где сотрудник выбрал разовую активацию. Автопродление открывает компании xWires; пока оно закрыто, ответ на monthly — 409 auto_renewal_closed. Окончательным режим станет, когда сотрудник пришлёт session: без его согласия на продление заказ будет разовым.

Когда в вашей системе решили, подтвердите или отклоните заказ:

curl -sS -X POST https://api.xwires.ai/company/v1/orders/9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14/approve \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

curl -sS -X POST https://api.xwires.ai/company/v1/orders/9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14/approve \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"renewal": "monthly"}'

curl -sS -X POST https://api.xwires.ai/company/v1/orders/9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14/reject \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

{
  "id": "9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14",
  "status": "approved",
  "is_open": true,
  "kind": "renewal",
  "plan": "plus",
  "renewal_mode": "once",
  "origin": "manual",
  "created_at": "2026-10-15T09:28:04.551902+00:00",
  "updated_at": "2026-10-15T09:30:12.345678+00:00",
  "approved_at": "2026-10-15T09:30:12.345678+00:00",
  "approved_by_operator": false,
  "approved_via": "api_key",
  "approved_by_api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60",
  "scheduled_for": null,
  "completed_at": null,
  "employee": {
    "id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
    "email": "anna.petrova@example.ru",
    "name": "Анна Петрова",
    "chatgpt_email": "a.petrova@example.ru"
  }
}

renewal_mode ответа — режим, с которым компания подтвердила заказ. Окончательный режим виден с awaiting_check.

После подтверждения сотрудника просят прислать session ChatGPT, оператор xWires проверяет заказ и отправляет его партнёру. Если заказ тем временем решил админ в кабинете, ответ — 409 order_not_awaiting_approval: прочитайте заказ, чтобы узнать итог.

Подписка по session сотрудника

Сотрудник присылает в вашу систему session своего ChatGPT: войдя в свой аккаунт, открывает chatgpt.com/api/auth/session и копирует ответ целиком. Одним запросом система оформляет ему подписку, как оператор xWires в своём кабинете:

{
  "email": "oleg.smirnov@example.ru",
  "plan": "plus",
  "name": "Олег Смирнов",
  "session": {
    "user": {
      "id": "user-Xq3vT8LmN2",
      "name": "Олег Смирнов",
      "email": "o.smirnov@example.ru"
    },
    "expires": "2027-01-16T10:04:12.000Z",
    "accessToken": "eyJhbGciOiJSUzI1NiIs…",
    "sessionToken": "eyJhbGciOiJkaXIiLCJlbmMiOi…"
  }
}

curl -sS -X POST https://api.xwires.ai/company/v1/subscriptions \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @subscription.json

{
  "outcome": "ordered",
  "account_created": true,
  "order": {
    "id": "a4c7e1b9-5d2f-4a83-b6e0-2f9c7d1a3e58",
    "status": "awaiting_check",
    "is_open": true,
    "kind": "activation",
    "plan": "plus",
    "renewal_mode": "once",
    "origin": "manual",
    "created_at": "2026-10-18T10:15:31.402811+00:00",
    "updated_at": "2026-10-18T10:15:31.402811+00:00",
    "approved_at": "2026-10-18T10:15:31.402811+00:00",
    "approved_by_operator": false,
    "approved_via": "api_key",
    "approved_by_api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60",
    "scheduled_for": null,
    "completed_at": null,
    "employee": {
      "id": "5e8b2d94-3c7a-4f1e-9b06-8a2d4c6e1f37",
      "email": "oleg.smirnov@example.ru",
      "name": "Олег Смирнов",
      "chatgpt_email": "o.smirnov@example.ru"
    }
  }
}

• Почты нет в xWires — создаётся учётная запись в компании (account_created: true): сотрудник входит кодом на эту почту и видит подписку. У сотрудника компании активная или истёкшая подписка продлевается на тот же аккаунт ChatGPT и план.
• Заказ подтверждён ключом и ждёт проверки оператора xWires (awaiting_check), потом уходит партнёру; сотруднику приходит письмо. Почту ChatGPT мы берём из session.
• Отправляя session, система заверяет, что сотрудник согласился передать его партнёру. Без поля renewal подписка разовая. С "renewal": "monthly" она будет продлеваться каждый месяц за счёт компании: система заверяет и согласие сотрудника на это. Так можно, только пока автопродление для компании открыто — иначе 409 auto_renewal_closed, — и в session нужен sessionToken — 400 session_token_required. Пока автопродление сотрудника включено, заказывать продление не нужно: 409 auto_renewal_on.
• Если человек с этой почтой не в компании — личный клиент xWires или сотрудник другой компании, — или почта на домене другой компании, ответ 202 с outcome: invited. Ему уходит приглашение, почта ждёт в списке с планом, а session не сохраняется: приняв приглашение, человек сам оформит заказ, и почта его подтвердит.
• Session не подошёл — 400 invalid_session, причина в details.issues; на expired попросите прислать свежий.

Автопродление

Подписку с автопродлением (заказ с renewal_mode: monthly) каждый месяц продлевает сам OpenAI за счёт компании, пока его не отключат. Состояние — в subscription.auto_renewal сотрудника (GET /employees/{id}): state, дата следующего продления next_renewal_at, почему выключено (stop_reason) и может ли компания его отключить (can_stop). Включается оно, когда заказ с автопродлением выполнен, — событие subscription.auto_renewal_started; отключается — subscription.auto_renewal_stopped с stop_reason.

curl -sS -X POST https://api.xwires.ai/company/v1/employees/3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90/auto-renewal/stop \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

{
  "id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
  "email": "anna.petrova@example.ru",
  "name": "Анна Петрова",
  "role": "employee",
  "subscription": {
    "chatgpt_email": "a.petrova@example.ru",
    "plan": "plus",
    "status": "active",
    "expires_at": "2026-11-14T08:03:51.207114+00:00",
    "auto_renewal": {
      "state": "off",
      "next_renewal_at": null,
      "stop_reason": "api_key",
      "can_stop": false
    }
  }
}

• Оплаченный месяц остаётся у сотрудника до expires_at, потом подписка не продлится. Продление у OpenAI xWires отменит сам, сотруднику и админам компании придёт письмо. Включить снова до expires_at нельзя; новый заказ с renewal: monthly уйдёт партнёру, когда оплаченный месяц кончится.
• Отключить можно, только пока автопродление включено и платит за него ваша компания (can_stop: true), иначе 409 auto_renewal_not_on; повтор отвечает так же.
• Отключить его может и сам сотрудник, админ компании в кабинете и оператор xWires: stop_reason скажет, кто. Увольнение отключает его само (stop_reason: offboarded).

Увольнение

Найдите сотрудника по почте и отметьте уволившимся:

curl -sS -X POST https://api.xwires.ai/company/v1/employees/search \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"anna.petrova@example.ru"}'

{
  "data": [
    {
      "id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
      "email": "anna.petrova@example.ru",
      "name": "Анна Петрова",
      "role": "employee",
      "subscription": {
        "chatgpt_email": "a.petrova@example.ru",
        "plan": "plus",
        "status": "active",
        "expires_at": "2026-11-14T08:03:51.207114+00:00",
        "auto_renewal": {
          "state": "on",
          "next_renewal_at": "2026-11-14T08:03:51.207114+00:00",
          "stop_reason": null,
          "can_stop": true
        }
      }
    }
  ],
  "next_cursor": null
}

curl -sS -X POST https://api.xwires.ai/company/v1/employees/3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90/offboard \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

{
  "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
  "cancelled_order_ids": [
    "9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14"
  ]
}

Человек перестаёт быть сотрудником компании, а его заказы за счёт компании, которые ещё не ушли партнёру, отменяются (cancelled_order_ids). Заказ, который партнёру как раз передают (submitting), остаётся и доходит до итога: если партнёр его так и не получил, он отменится позже, и придёт order.cancelled. Админа так не отметить — 409 cannot_offboard_admin: это делают в кабинете. Автопродление его подписки за счёт компании отключается (subscription.auto_renewal_stopped с stop_reason: offboarded). Вернуть человека можно новым приглашением. Если у ушедшего мог остаться ключ API или секрет вебхука, смените их.

Отчёт для бухгалтерии

Выполненные заказы приходят событиями order.succeeded: подписка на них у адреса вебхука или фильтр ленты. Сумму и план берите из заказа: GET /orders/{id}.

curl -sS "https://api.xwires.ai/company/v1/events?after=1041&types=order.succeeded" \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

Или списком за период, по времени последнего изменения:

curl -sS "https://api.xwires.ai/company/v1/orders?status=succeeded&updated_since=2026-10-01T00:00:00%2B03:00" \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

Заказ

Статус может вернуться назад:

• failed → sent: партнёр всё-таки повторил заказ;
• awaiting_check → approved: оператор попросил у сотрудника новый session;
• review_required → approved: оператор повторяет заказ, а session уже нет.

Из review_required заказ может уйти и в scheduled или sent, когда снова в работе. Незнакомый статус считайте заказом в работе.

Подписка

Автопродление

Незнакомое состояние считайте включённым.

Планы

Интеграцию проверяйте в песочнице: это тот же API на тестовых данных, по адресу https://api.sandbox.xwires.ai/company/v1. В ней ничего не оплачивается и никому не пишется: заказы не уходят партнёру, письма не получают ни сотрудники, ни приглашённые. Данные песочницы отдельные и в рабочий xWires не попадают.

1. Откройте sandbox.xwires.ai и войдите с любой почтой: код придёт на неё. У вас будет своя компания «Песочница», вы — её админ.
2. В «Интеграциях» песочницы выпустите ключ, он начинается с xwc_test_, и, если нужны вебхуки, добавьте адрес. События приходят на него так же, как в рабочем xWires, подписаны так же и с того же IP.
3. Направьте систему на адрес песочницы. Все запросы этого руководства работают и там, примеры — тоже: замените адрес и ключ.

Что уже есть в компании

Это придуманные люди: их почты — под .invalid, войти за них нельзя. Подтвердите или отклоните заказы Анны и Бориса, как в рабочем API, и посмотрите, что придёт вашей системе.

Что в песочнице иначе

• Ключ песочницы в рабочем API и рабочий ключ в песочнице получают 401 invalid_api_key, а в message сказано, куда этот ключ отправлять.
• Шаги, которые в рабочем xWires делают сотрудник, оператор и партнёр, делает песочница: сама (автопилот) или по вашему запросу. В событиях этих шагов actor — null, как у действий людей, поэтому система, которая отбрасывает эхо своих запросов по actor.api_key_id, их увидит.
• Лимиты, ошибки и форма ответов — те же, что в рабочем API.

Запросы песочницы

В рабочем API их нет: там они отвечают 404 not_found. Нужен ключ с правом действий. Те же действия есть кнопками в «Интеграциях» песочницы.

Автопилот

Подтверждённый заказ, который вы не переводили вручную, песочница ведёт дальше сама: awaiting_check → scheduled → sent → succeeded, шаг примерно раз в 10 секунд, весь путь — меньше минуты. На каждый шаг — событие order.*, на успех — subscription.activated. Заказ, который вы перевели запросом POST /sandbox/orders/{id}/advance, автопилот больше не трогает. Чтобы он не тронул заказ и после подтверждения, переведите его в нынешний статус, {"to": "awaiting_approval"}, до подтверждения.

Пример: партнёр отказал

Новый сотрудник:

curl -sS -X POST https://api.sandbox.xwires.ai/company/v1/sandbox/employees \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"plus"}'

{
  "id": "5f3a9c21-7d4e-4b86-a1c2-9e8d7f6b5a43",
  "email": "employee-5f3a9c21@employees.sandbox.invalid",
  "name": "Мария Соколова",
  "role": "employee",
  "subscription": {
    "chatgpt_email": "employee-5f3a9c21@chatgpt.sandbox.invalid",
    "plan": "plus",
    "status": "new",
    "expires_at": null,
    "auto_renewal": {
      "state": "off",
      "next_renewal_at": null,
      "stop_reason": null,
      "can_stop": false
    }
  }
}

Его заказ, ваше подтверждение и отказ партнёра:

curl -sS -X POST https://api.sandbox.xwires.ai/company/v1/sandbox/orders \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"employee_id":"5f3a9c21-7d4e-4b86-a1c2-9e8d7f6b5a43"}'

curl -sS -X POST https://api.sandbox.xwires.ai/company/v1/orders/8e1b4d7a-2c9f-4a63-b5e0-3d7c1f9a2b68/approve \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

curl -sS -X POST https://api.sandbox.xwires.ai/company/v1/sandbox/orders/8e1b4d7a-2c9f-4a63-b5e0-3d7c1f9a2b68/advance \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"failed"}'

Ваша система получит order.awaiting_approval, order.approved с actor вашего ключа, затем order.awaiting_check, order.scheduled, order.sent и order.failed без него. Завершить активную подписку и проверить subscription.expired — POST /sandbox/employees/{id}/expire-subscription.

Справочник собран из того же описания, что и openapi.json (OpenAPI 3.0.3), поэтому совпадает с тем, что API делает. Базовый адрес — https://api.xwires.ai/company/v1, у каждого запроса заголовок Authorization: Bearer с ключом.

Схемы

Поля ответа обязательны и приходят всегда, иногда со значением null; «необязательное» — поле, которого может не быть. В v1 поля только добавляются.

Заголовки ответа

События — это изменения заказов, сотрудников и подписок компании. Их можно читать лентой GET /events и получать вебхуками на адреса HTTPS ваших систем. В событии только идентификаторы, статусы, план, вид заказа, роль, время и ключ, если действовал он; подробности система берёт через API.

Типы

• order.<status> — заказ, который оплачивает компания, перешёл в этот статус. previous_status: null — заказ только что стал заказом компании. После ухода сотрудника события его заказа приходят с employee_id: null.
• employee.joined — человек стал сотрудником: вошёл с почтой домена компании, принял приглашение, открыл ссылку для сотрудников или его добавил оператор. employee.left — его отметили уволившимся, он перешёл в другую компанию или удалён. employee.role_changed — стал админом или перестал им быть (previous_role).
• subscription.activated, subscription.renewed, subscription.expired — подписка сотрудника заработала, продлена (новый expires_at) или истекла. Приходят компании, в которой человек сейчас.
• subscription.auto_renewal_started — заказ с автопродлением выполнен, подписка будет продлеваться сама; subscription.auto_renewal_stopped — автопродление выключили, stop_reason говорит, кто или почему. Приходят компании, в которой человек сейчас.
• Личные заказы и подписки людей вне компании в события не попадают никогда.

Событие

Конверт одинаков у всех типов: id, type, timestamp (когда это случилось), position, company_id, actor и data своей группы (схемы Event и WebhookEvent). actor.api_key_id — ключ компании, чей запрос к API вызвал событие; null — кто угодно другой: админ в кабинете, сотрудник, xWires. Заказ, который почта, добавленная ключом, подтвердит позже, когда сотрудник его оформит, придёт с actor: null и approved_via: "api_key". Заказ, который подтвердил сам запрос POST /approved-emails (он есть в approved_order_ids), придёт с actor.api_key_id этого ключа.

{
  "id": "e5b1a7c3-2d9f-4e60-8b4a-1c7e3f9d2a85",
  "type": "order.approved",
  "timestamp": "2026-10-15T09:30:12.345678+00:00",
  "position": 1042,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": {
    "api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60"
  },
  "data": {
    "order_id": "9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14",
    "status": "approved",
    "previous_status": "awaiting_approval",
    "kind": "renewal",
    "plan": "plus",
    "renewal_mode": "once",
    "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
    "approved_via": "api_key",
    "approved_by_api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60"
  }
}

{
  "id": "4f2a9c61-0b8e-4d37-9e5c-3a1d7b6f2e08",
  "type": "employee.role_changed",
  "timestamp": "2026-10-15T11:02:47.902316+00:00",
  "position": 1043,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": null,
  "data": {
    "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
    "role": "admin",
    "previous_role": "employee"
  }
}

{
  "id": "b8e3d1f7-6c2a-4b90-8f15-2e7c9a4d6b31",
  "type": "subscription.renewed",
  "timestamp": "2026-10-15T12:41:09.664051+00:00",
  "position": 1044,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": null,
  "data": {
    "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
    "status": "active",
    "previous_status": "active",
    "plan": "plus",
    "expires_at": "2026-12-14T08:03:51.207114+00:00"
  }
}

{
  "id": "2c9f4e7a-1d3b-4a68-9e05-7b1c3d5f8a24",
  "type": "subscription.auto_renewal_stopped",
  "timestamp": "2026-10-19T10:15:32.402917+00:00",
  "position": 1051,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": {
    "api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60"
  },
  "data": {
    "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
    "status": "active",
    "previous_status": null,
    "plan": "plus",
    "expires_at": "2026-11-14T08:03:51.207114+00:00",
    "stop_reason": "api_key"
  }
}

Позиция

position — номер события в компании: по всем типам, без пропусков, 1, 2, 3… События одного изменения могут получить номера не подряд, если в то же время менялось что-то ещё. После восстановления базы xWires из резервной копии позиции уходят скачком вперёд, а на позицию, которой больше нет, лента отвечает 410 events_cursor_expired — с фильтром types и без, при первом же запросе: перечитайте списки, как на эту ошибку. С фильтром types позиции, конечно, идут с пропусками.

Лента

after=0 — с самого старого хранимого события (мы храним их 30 дней), after=latest — только новые, число — после этой позиции. types — типы через запятую, limit — до 200. Лента работает независимо от вебхуков, также когда они выключены.

curl -sS "https://api.xwires.ai/company/v1/events?after=1041" \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

{
  "data": [
    {
      "id": "e5b1a7c3-2d9f-4e60-8b4a-1c7e3f9d2a85",
      "type": "order.approved",
      "timestamp": "2026-10-15T09:30:12.345678+00:00",
      "position": 1042,
      "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
      "actor": {
        "api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60"
      },
      "data": {
        "order_id": "9c2e4b71-6a3f-4d58-b1e0-7f3a2c9d5e14",
        "status": "approved",
        "previous_status": "awaiting_approval",
        "kind": "renewal",
        "plan": "plus",
        "renewal_mode": "once",
        "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
        "approved_via": "api_key",
        "approved_by_api_key_id": "0b7d9e2a-5c13-4f6e-8a21-9d4c3b7e1f60"
      }
    },
    {
      "id": "4f2a9c61-0b8e-4d37-9e5c-3a1d7b6f2e08",
      "type": "employee.role_changed",
      "timestamp": "2026-10-15T11:02:47.902316+00:00",
      "position": 1043,
      "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
      "actor": null,
      "data": {
        "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
        "role": "admin",
        "previous_role": "employee"
      }
    },
    {
      "id": "b8e3d1f7-6c2a-4b90-8f15-2e7c9a4d6b31",
      "type": "subscription.renewed",
      "timestamp": "2026-10-15T12:41:09.664051+00:00",
      "position": 1044,
      "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
      "actor": null,
      "data": {
        "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
        "status": "active",
        "previous_status": "active",
        "plan": "plus",
        "expires_at": "2026-12-14T08:03:51.207114+00:00"
      }
    }
  ],
  "next_after": 1044,
  "has_more": false
}

410 events_cursor_expired: событий сразу после этой позиции уже нет — они старше 30 дней, или базу xWires восстановили из резервной копии и они потерялись. Запросите after=latest и сохраните next_after, перечитайте списки и продолжайте с сохранённой позиции.

Вебхуки

Адреса добавляет админ компании: «Компания → Интеграции → Вебхуки». У адреса — URL, описание и типы событий: все, включая будущие, или выбранные. Секрет whsec_… показывается один раз. О каждом новом адресе и смене адреса письмом узнают все админы компании, история изменений хранится. Ключ API адресами не управляет.

• Адрес — https:// на порту 443, имя с A-записью (IPv4) и сертификатом из публично доверенных; сертификат от Russian Trusted Root CA (Минцифры) не подойдёт. Перенаправления не выполняются: ответ 3xx — неудача. Адреса в локальных и частных сетях и на доменах xWires не принимаются.
• Запросы приходят с IP 135.106.174.63: разрешите его на своей стороне. Смену адреса объявим за 30 дней.
• Ответьте 2xx за 10 секунд: примите событие, ответьте, а обработайте потом, например в своей очереди.
• Доставка «хотя бы раз»: событие может прийти дважды, повторы отбрасывайте по webhook-id. На один адрес запросы идут по одному, обычно в течение минуты после события, первые попытки — по порядку позиций. Повторы, тесты и «Повторить» в кабинете порядок меняют, поэтому действуйте по данным API: статус заказа берите из GET /orders/{id}, а не из порядка событий.
• Не получилось — повторим с паузами в 1, 5, 15, 30, 60, 120, 240, 360 и 480 минут: до 10 попыток, примерно за 22 часа. После 3 неудач подряд адрес «не принимает события»: туда идут только пробные запросы по тому же расписанию, а как только пробный пройдёт, уйдёт и всё накопленное.
• Через 1 час неудач админам придёт письмо. Событие, которое не удалось доставить за 3 дня с первой попытки, мы больше не отправляем. События, накопившиеся, пока адрес не принимал запросы или оператор xWires останавливал вебхуки компании, придут позже, по порядку, и могут быть старше 3 дней: когда это случилось, смотрите в timestamp. Через 5 дней без успешной доставки адрес выключается, и админам снова придёт письмо.
• Включённый снова адрес не получит событий, случившихся, пока он был выключен: заберите их из ленты. Событие, которое не удалось доставить до выключения, после включения мы ещё попробуем отправить, если с первой попытки прошло меньше 3 дней.

Заголовки и подпись

Подпись — по Standard Webhooks: подходят его библиотеки (standardwebhooks в npm и PyPI) или код ниже.

Проверяйте подпись по телу запроса как оно пришло, до разбора JSON: тот же JSON, записанный заново, не сойдётся. Секрет храните на сервере, как ключ API, например в XWIRES_WEBHOOK_SECRET.

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: whsec_… из «Компания → Интеграции»; headers: заголовки запроса, имена в нижнем
// регистре, как их даёт Node; body: тело запроса как пришло (строка или Buffer), до JSON.parse.
export function verifyWebhook(secret, headers, body) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !signatures || !/^\d{1,12}$/.test(timestamp ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.`).update(body).digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    const given = Buffer.from(signature ?? "", "base64");
    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

import base64
import hashlib
import hmac
import time


# secret: whsec_… из «Компания → Интеграции»; headers: заголовки запроса (во Flask и Django
# имена без учёта регистра); body: тело запроса как пришло, в байтах, до json.loads.
def verify_webhook(secret: str, headers, body: bytes) -> bool:
    msg_id = headers.get("webhook-id") or ""
    timestamp = headers.get("webhook-timestamp") or ""
    signatures = headers.get("webhook-signature") or ""
    if not msg_id or not signatures:
        return False
    if not (timestamp.isascii() and timestamp.isdigit() and len(timestamp) <= 12):
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature.encode(), expected):
            return True
    return False

Смена секрета

«Выпустить новый секрет» в кабинете: прежний подписывает ещё 24 часа, и в это время у запроса две подписи. Перенесите новый секрет в свою систему. Вторая смена за эти сутки выводит самый старый секрет сразу. Смените секрет, когда уходит человек, который мог его видеть: админ, разработчик, подрядчик.

Тестовое событие

«Отправить тестовое событие» в кабинете присылает webhook.test: без позиции и ключа, в data — адрес, который проверяли. Оно уходит и на адрес, который не принимает события. У теста одна попытка, и не доставленный за 10 минут тест считается неудачным. В ленте тестовых событий нет.

{
  "id": "7a3c5e91-2f4b-4d68-b0a7-9c1e3f5d8b26",
  "type": "webhook.test",
  "timestamp": "2026-10-15T10:05:00.000+00:00",
  "position": null,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": null,
  "data": {
    "endpoint_id": "c4d8f2a6-1b3e-4a75-9c0d-5e2f7a1b3c69"
  }
}

Что и когда ушло на каждый адрес, видно в кабинете в «Журнале доставки»; там же неудачную доставку можно повторить. Оператор xWires может остановить вебхуки компании, тогда в кабинете об этом будет написано.

• Компания — оператор персональных данных своих сотрудников, xWires обрабатывает их по её поручению (152-ФЗ, ст. 6 ч. 3). Ключ и адрес вебхука, которые создал админ компании, — поручение передавать эти данные в системы компании.
• Если ваша система или адрес вебхука за пределами России, это трансграничная передача, и оформляет её компания.
• Ответы API — персональные данные: почты и имена сотрудников. Храните их и логи интеграции так же, как другие данные сотрудников. Ключи и секреты — только на сервере, в хранилище секретов.
• В событиях почт, имён и цен нет: только идентификаторы, статусы, план, вид заказа, роль, время и ключ, если действовал он.
• У нас тела запросов и ответов в логи не пишутся, почты не попадают в адреса, IP-адреса не хранятся. Ключ хранится только как отпечаток, секрет вебхука — зашифрованным. Адрес вебхука не попадает в логи и письма, только имя сервера; на какие серверы и с какого времени уходили события компании, хранится в истории адресов.
• Session сотрудника — доступ к его ChatGPT. Принимайте его только от самого сотрудника, передавайте только в теле POST /subscriptions, не храните и не пишите в логи. У нас сайт сразу шифрует его так, что расшифровать может только сервис, который передаёт заказ партнёру; в ответах, событиях и логах его нет.
• Письма тем, чьи почты добавила система, уходят постепенно: на большой список — несколько минут. Суточный лимит в 5000 почт и приглашений не даёт утёкшему ключу превратить xWires в рассылку.
• Уходит человек, который мог сохранить ключ или секрет, — смените их: ключ, секрет.

В v1 изменения только добавляются: новые поля, значения статусов и типы событий. Несовместимые изменения выйдут как v2 по новому адресу, а v1 проработает рядом не меньше 6 месяцев. Смену IP-адреса вебхуков объявим за 30 дней.