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

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

Ещё система выпускает виртуальные карты компании для подписок и сервисов, пополняет их и выводит с них деньги, замораживает, закрывает и получает их реквизиты (раздел 11).

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

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

1. Админ компании открывает «Кабинет компании → Интеграции» и в «Ключах API» создаёт ключ: название, например «1С: кадры», и доступ — «Только чтение» или «Чтение и действия». Ключ показывается один раз, скопируйте его сразу. Всем админам компании придёт письмо о новом ключе. Ключ можно и попросить у оператора xWires: он выпустит его и передаст вам, а у ключа в «Интеграциях» будет видно, что его выпустил оператор.
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",
    "cards": true
  },
  "company": {
    "id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
    "name": "Ромашка",
    "cards_enabled": true
  }
}

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 (раздел 12). Передавайте его только в заголовке Authorization: Bearer xwc_…. Без ключа, с испорченным или незнакомым ключом ответ — 401 invalid_api_key.

Картам компании (раздел 11) нужно ещё право «Карты»: его дают при выпуске ключа, у ключей, выпущенных раньше, его нет. Без него все запросы карт отвечают 403 api_key_no_cards. С правом и доступом «Только чтение» ключ читает карты, их операции и транзакции, с «Чтение и действия» — ещё выпускает, пополняет, выводит, замораживает, размораживает, закрывает карты и видит их реквизиты. Есть ли право у ключа, говорит key.cards в GET /me.

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

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

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

Отзыв и смена

• Отозвать ключ может любой админ компании в «Интеграциях» и оператор 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 согласует с компанией отдельно. Суммы есть только у карт компании: деньги на карте и в её операциях — строкой в долларах с двумя знаками, "48.20", суммы транзакций — строкой в их валюте. Суммы в запросах — тоже строки, а не числа.
• Поля, значения и типы событий в v1 только добавляются. Незнакомые поля и типы событий пропускайте, незнакомый статус заказа считайте «в работе».
• Каждый ответ, и ошибка тоже, несёт заголовок X-Request-Id: назовите его поддержке (support@xwires.ai), если что-то пошло не так. Ответы на запросы с ключом несут и 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: пути полей и коды проверки, без присланных значений, и где есть — нарушенное правило: minimum и maximum (длина, число элементов, значение), expected (тип), format, allowed (допустимые значения). Тело, которое не разобрать как JSON, — issue: invalid_json с пустым path. У 400 invalid_session в details — path: session и причина. У 400 invalid_amount, когда сумма за границами вида карты, — path: amount, minimum и maximum.

{
  "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 и card_details_rate_limited подождите столько секунд, сколько в Retry-After. У api_email_quota_exceeded заголовка нет: суточный лимит освобождается постепенно.
• 500 — ошибка у нас: сначала прочитайте данные, потом повторяйте. Не проходит — напишите на support@xwires.ai с 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 (раздел 14): в ней те же события, что приходят на вебхуки.

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 нет: каждое действие и так безопасно повторить. Выпуск, пополнение и вывод с карты двигают деньги, поэтому у них в теле reference — id операции в вашей системе (раздел 11). Его же можно прислать в POST /subscriptions: заказ подписки тоже стоит денег.

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

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,
  "invalid_emails": [],
  "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": "Олег Смирнов",
  "reference": "hr-2026-1018-oleg",
  "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.
• Если почта сотрудника с этим планом уже ждёт в списке, заказ её использует, и из GET /approved-emails она уходит: следующий заказ сотрудника она не подтвердит.
• Отправляя session, система заверяет, что сотрудник согласился передать его партнёру. Без поля renewal подписка разовая. С "renewal": "monthly" она будет продлеваться каждый месяц за счёт компании: система заверяет и согласие сотрудника на это. Так можно, только пока автопродление для компании открыто — иначе 409 auto_renewal_closed, — и в session нужен sessionToken — 400 session_token_required. Пока автопродление сотрудника включено, заказывать продление не нужно: 409 auto_renewal_on.
• Если человек с этой почтой не в компании — личный клиент xWires или сотрудник другой компании, — или почта на домене другой компании, ответ 202 с outcome: invited. Ему уходит приглашение, почта ждёт в списке с планом, а session не сохраняется: приняв приглашение, человек сам оформит заказ, и почта его подтвердит. У компании с white-label приглашений нет (ниже).
• Session не подошёл — 400 invalid_session, причина в details.issues; на expired попросите прислать свежий. Такой session мы не храним, а причину отказа и почту сотрудника запоминаем: поддержка xWires видит, что не так, и может подсказать.
• reference — id запроса в вашей системе, по желанию, как у операций с картой. Повтор с тем же reference и тем же телом отвечает 200 тем же заказом в его нынешнем состоянии или тем же приглашением, без нового заказа и писем, даже если заказ уже выполнен; session при сравнении не учитывается. С другим телом — 409 reference_conflict. Без reference повтор, пока заказ открыт, получит 409 open_order_exists, а после выполненного заказа тот же запрос оформит продление.

Новый session к заказу

Session нужен заказу в статусе approved: компания его подтвердила, а сотрудник session ещё не прислал, или оператор xWires при проверке попросил новый — тогда приходит order.approved с previous_status: awaiting_check. Обычно сотрудник вставляет session в своём кабинете, но ваша система может прислать его сама, взяв у сотрудника свежий:

{
  "session": {
    "user": {
      "id": "user-Xq3vT8LmN2",
      "name": "Олег Смирнов",
      "email": "o.smirnov@example.ru"
    },
    "expires": "2027-01-18T09:41:07.000Z",
    "accessToken": "eyJhbGciOiJSUzI1NiIs…",
    "sessionToken": "eyJhbGciOiJkaXIiLCJlbmMiOi…"
  }
}

curl -sS -X POST https://api.xwires.ai/company/v1/orders/a4c7e1b9-5d2f-4a83-b6e0-2f9c7d1a3e58/session \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @session.json

{
  "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-18T11:02:44.918305+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"
  }
}

• Session — от ChatGPT-аккаунта заказа (employee.chatgpt_email), иначе 409 chatgpt_email_mismatch. Заказ снова ждёт проверки оператора (awaiting_check), потом уходит партнёру.
• Отправляя session, система заверяет, что сотрудник согласился передать его партнёру. Заказ, который компания подтвердила с автопродлением, станет monthly только с "renewal": "monthly" — согласием сотрудника на ежемесячные продления, — и тогда в session нужен sessionToken; без поля заказ разовый.
• Заказ не ждёт session — 409 order_not_awaiting_session: его ещё не подтвердили, session уже прислан или заказ закрыт. Session не подошёл — 400 invalid_session, как в POST /subscriptions.

White-label: подписки для ваших клиентов

Если вы перепродаёте подписки ChatGPT своим клиентам, xWires может оставаться для них невидимым. White-label включает xWires по договору с компанией. Тогда:

• Клиент вставляет session на вашей странице, а ваша система присылает его POST /subscriptions с почтой клиента и планом. Клиент — человек вашей компании в xWires: так его видят GET /employees, заказы и события.
• Людям компании xWires не пишет ничего: ни о заказах и подписках, ни приглашений. О ходе заказа вы узнаёте из событий и вебхуков (раздел 14) и сообщаете клиенту сами. Письма xWires получают только админы компании.
• Почта — ваш клиент и только ваш: если с той же почтой в xWires есть кто-то ещё — наш личный клиент или сотрудник другой компании, — это другой человек, он вам не мешает, и никто никого не приглашает. В ответах и в GET /employees клиент — с той почтой, что прислали вы, и POST /employees/search находит его по ней. Писем на неё xWires не шлёт.
• Если оператор xWires попросил новый session, придёт order.approved с previous_status: awaiting_check: возьмите у клиента свежий и пришлите POST /orders/{id}/session.
• Один аккаунт ChatGPT — у одного человека. Если на аккаунт клиента в xWires уже есть подписка другого человека, ответ 409 chatgpt_email_taken. Когда подписка нашего личного клиента или другого вашего клиента на этот аккаунт закончилась, аккаунт переходит к вашему клиенту, и заказ проходит.
• Подписка разовая, на месяц. На следующий месяц пришлите POST /subscriptions с новым session того же аккаунта: заказ продлит подписку.

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

Подписку с автопродлением (заказ с 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.

За 3 дня до next_renewal_at появляется заказ продления: origin: auto_renewal, сразу в scheduled, без подтверждения и без session (order.scheduled), а state становится in_progress. Оплату в дату продления списывает сам OpenAI с карты, которую xWires держит для подписки. Списал — заказ выполнен (order.succeeded), подписка продлена на календарный месяц (subscription.renewed), state снова on. Если OpenAI получил отказ, xWires ждёт его повтора до недели; если не пытался списать — до суток. Не дождался или карта оплаты не годится — продление не прошло: order.failed, subscription.renewal_failed с failure_reason и subscription.auto_renewal_stopped (stop_reason failed или openai_off). Подписка действует до expires_at, дальше её продлевают новым заказом. Пока продление разбирает оператор xWires, state — attention.

{
  "id": "8d4b2f61-7a3e-4c95-b1d8-6e2a9f4c7b13",
  "type": "subscription.renewal_failed",
  "timestamp": "2026-11-15T08:04:12.538206+00:00",
  "position": 1188,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": null,
  "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",
    "order_id": "f3a8c2d6-9b1e-4f74-a5c0-3d7e1b9f6a28",
    "failure_reason": "not_charged"
  }
}

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, потом подписка не продлится. Карту оплаты xWires сразу удалит, и OpenAI больше не спишет; сотруднику и админам компании придёт письмо. Включить снова до expires_at нельзя; новый заказ с renewal: monthly уйдёт партнёру, когда оплаченный месяц кончится.
• Отключить можно, только пока автопродление включено и платит за него ваша компания (can_stop: true), иначе 409 auto_renewal_not_on; повтор отвечает так же. Заказ продления, который ещё ждёт оплаты OpenAI, отменяется вместе с ним (order.cancelled).
• Отключить его может и сам сотрудник, админ компании в кабинете и оператор 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"
  ]
}

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

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

Выполненные заказы приходят событиями order.succeeded: подписка на них у адреса вебхука или фильтр ленты. План, вид заказа и время выполнения (completed_at) берите из заказа: GET /orders/{id}. Сумм за подписки в API нет: их стоимость xWires согласует с компанией отдельно.

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 уже нет;
• submitting → scheduled: передать заказ партнёру не вышло, и до партнёра ничего не дошло; заказ уйдёт следующей попыткой.
• sent → scheduled: заказ без автопродления не прошёл у партнёра, деньги не списаны; заказ уходит другому партнёру, и подписка остаётся в работе.

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

Подписка

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

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

Планы

Компания, которой xWires включил карты, выпускает виртуальные карты для подписок и сервисов: чтобы оплатить ChatGPT сотрудника или другой сервис. Деньги на карты идут с баланса компании в xWires: его пополняют по счёту, а выпуск и пополнение списывают с него сумму и комиссию. Тот же баланс тратят запросы к моделям, которые оплачиваются с него. Баланса, комиссий и условий компании в API нет — только деньги на картах. Карта принадлежит компании; сотрудника у неё можно указать как пометку.

• Нужен ключ с правом «Карты» (раздел 3), без него — 403 api_key_no_cards. Есть ли право, говорит key.cards в GET /me, включены ли карты компании — company.cards_enabled. Пока они выключены, выпуск и пополнение отвечают 409 cards_not_enabled, а карты, что уже есть, можно читать, выводить с них деньги, замораживать и закрывать.
• Своих лимитов на число карт нет: выпуск и пополнение ограничивает баланс компании. Не хватает — 409 insufficient_funds, банку ничего не уходит. Если деньги успели уйти на запросы к моделям, пока операция ждала очереди, она не пройдёт: card.operation_failed с failure_code insufficient_funds, деньги вернутся на баланс.
• Операция принимается сразу (202), а итог приходит через секунды или минуты: событием card.* и в самой операции (GET /card-operations/{id}). На карте одна операция за раз, она видна в pending_operation карты; вторая отвечает 409 card_operation_pending.
• Суммы — строки в долларах США, с точкой и не больше чем двумя знаками: "50.00" или "50". Число вместо строки, третий знак и сумма за границами вида — 400 invalid_amount.

Выпустить карту и оплатить подписку

1. Выпустите карту: вид, сумма и reference — id операции в вашей системе. Подпись и сотрудник — по желанию.

curl -sS -X POST https://api.xwires.ai/company/v1/cards \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"chatgpt","amount":"50.00","reference":"1c:card-0042","label":"ChatGPT Plus, Анна","employee_id":"3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90"}'

{
  "card": {
    "id": "8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60",
    "kind": "chatgpt",
    "status": "issuing",
    "network": null,
    "last4": null,
    "expires": null,
    "available": null,
    "label": "ChatGPT Plus, Анна",
    "employee_id": "3a9e5c71-8b2d-4f04-a6c9-1e7b2d5f8a90",
    "pending_operation": {
      "id": "2b7e9c4f-1a3d-4e85-9f06-5c8a2d1e7b39",
      "type": "issue"
    },
    "closed_reason": null,
    "replaced_by": null,
    "created_at": "2026-10-21T10:04:17.302518+00:00",
    "updated_at": "2026-10-21T10:04:17.302518+00:00"
  },
  "operation": {
    "id": "2b7e9c4f-1a3d-4e85-9f06-5c8a2d1e7b39",
    "card_id": "8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60",
    "type": "issue",
    "amount": "50.00",
    "reference": "1c:card-0042",
    "status": "pending",
    "failure_code": null,
    "created_at": "2026-10-21T10:04:17.302518+00:00",
    "completed_at": null
  }
}

1. Дождитесь card.issued: карта active, у неё последние 4 цифры, сеть, срок и остаток. Не пришло событие — спросите операцию: GET /card-operations/{id}. Все операции карты, с итогами, — GET /cards/{id}/operations. Выпуск не прошёл — card.operation_failed, карта failed, деньги вернулись на баланс.

{
  "id": "3c8f1a6d-9b2e-4e75-8a41-6d2c9f5b1e07",
  "type": "card.issued",
  "timestamp": "2026-10-21T10:04:29.811604+00:00",
  "position": 1060,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": null,
  "data": {
    "card_id": "8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60",
    "operation_id": "2b7e9c4f-1a3d-4e85-9f06-5c8a2d1e7b39",
    "type": "issue",
    "reference": "1c:card-0042",
    "amount": "50.00",
    "available": "50.00",
    "closed_reason": null,
    "new_card_id": null,
    "failure_code": null
  }
}

1. Прочитайте реквизиты и введите их в форме оплаты сервиса. Имя держателя у всех карт одно, кода 3-D Secure нет: карта платит без него.

curl -sS https://api.xwires.ai/company/v1/cards/8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60/details \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

{
  "card_id": "8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60",
  "number": "4000000000000002",
  "cvv": "123",
  "expires": "2028-10",
  "holder_name": "GPT Payment",
  "billing_address": {
    "line1": "1209 Orange St",
    "line2": "",
    "city": "Wilmington",
    "state": "DE",
    "country": "US",
    "postal_code": "19801"
  }
}

1. Списание сервиса придёт событием card.transaction (раздел 14); магазин и сумма в его валюте — в списке транзакций карты.

curl -sS "https://api.xwires.ai/company/v1/cards/8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60/transactions?limit=20" \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

Повтор: reference

Выпуск, пополнение и вывод сам запрос двигает деньги, поэтому «прочитать, потом повторить» здесь не спасает от двойного списания. В теле у них reference — id операции в вашей системе: 1–64 латинских букв, цифр и знаков . _ : -, уникальный в компании. Тот же reference с тем же телом — та же операция в её нынешнем состоянии и 200 вместо 202; с другим телом — 409 reference_conflict. После таймаута или 5xx повторяйте сразу с тем же reference. Заморозка, разморозка и закрытие без reference: повтор отвечает 409 по статусу карты.

Пополнить к продлению

Лимит карты — её остаток (available). Перед продлением подписки пополните карту на нужную сумму: итог — card.topped_up с новым остатком. Пополнять можно только активную карту.

curl -sS -X POST https://api.xwires.ai/company/v1/cards/8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60/top-ups \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"20.00","reference":"1c:topup-0107"}'

{
  "id": "c1a8e5d2-7f4b-4c39-8e60-9d2b5f1a3c74",
  "card_id": "8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60",
  "type": "top_up",
  "amount": "20.00",
  "reference": "1c:topup-0107",
  "status": "pending",
  "failure_code": null,
  "created_at": "2026-11-12T09:00:04.118302+00:00",
  "completed_at": null
}

Снизить лимит

Вывод возвращает деньги с карты на баланс компании: сумму или "all" — всё, что можно. На карте остаётся минимум вида, деньги под холдом не выводятся. Итог — card.withdrawn, его amount — сколько ушло с карты. Попросили больше, чем можно, — card.operation_failed с insufficient_available. Комиссию пополнения вывод не возвращает.

curl -sS -X POST https://api.xwires.ai/company/v1/cards/8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60/withdrawals \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"all","reference":"1c:refund-0042"}'

Заморозить и закрыть

POST /cards/{id}/freeze — карта отклоняет списания, деньги ждут на ней; POST /cards/{id}/unfreeze — снова платит. Закрытие — навсегда: остаток вернётся на баланс компании, когда банк подтвердит закрытие (card.closed, amount — сколько ушло с карты). Закрыть можно и замороженную карту. Подписки, которые она оплачивала, отмените у сервисов заранее.

curl -sS -X POST https://api.xwires.ai/company/v1/cards/8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60/close \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY"

Карту заменили

Банк может закрыть карту сам: после нескольких отказов подряд, по блокировке BIN или риск-контролю. Тогда придёт card.closed без operation_id и с closed_reason: issuer. Если условия компании это предусматривают, xWires за свой счёт выпускает замену того же вида, с тем же остатком, подписью и сотрудником, и присылает card.replaced: в card_id — закрытая карта, в new_card_id — новая. Прочитайте реквизиты новой карты и введите их в сервисах заново. Без замены остаток закрытой карты вернётся на баланс, если банк его отдаст.

{
  "id": "1f6c3e9a-2d8b-4b57-9e13-4a7d2c6f8b91",
  "type": "card.replaced",
  "timestamp": "2026-11-20T16:41:55.902137+00:00",
  "position": 1094,
  "company_id": "6f1c2b9e-3d4a-4c71-9a5e-2b8f0d1c7a43",
  "actor": null,
  "data": {
    "card_id": "8d3f6a1c-4e2b-4f97-a5c8-1b9e7d2f4a60",
    "operation_id": "a7d3f1c9-5e2b-4b68-9c04-1d8e6a3f7b25",
    "type": "replace",
    "reference": null,
    "amount": "30.00",
    "available": "30.00",
    "closed_reason": "issuer",
    "new_card_id": "6e9a2c5f-8b1d-4d37-a4e8-2f7c1b9d5a06",
    "failure_code": null
  }
}

Реквизиты

• Номер, CVV, срок и адрес плательщика читает только ключ с правом «Карты» и доступом «Чтение и действия», и только у карты active или frozen: у выпускаемой — 409 card_not_active, у закрытой — 409 card_closed.
• xWires реквизиты не хранит: каждый показ читает их у банка и записывает в журнал — кто открыл, админ в кабинете или ключ, и когда. Журнал видят админы компании, а ключ с правом «Карты» читает его через GET /cards/{id}/details-reveals; чтение журнала — не показ. Ключу — до 10 показов в час, сверх — 429 card_details_rate_limited с Retry-After. Банк не ответил — 503 service_unavailable: повторите позже, показ уже засчитан.
• На своей стороне не пишите реквизиты в логи и не держите в браузере, отдавайте только тому сервису, который ими платит. Хранить их можно только так, как требует PCI DSS; проще не хранить и читать заново.

Состояния

Незнакомый статус карты считайте картой, которая не платит.

failure_code не прошедшей операции: insufficient_available — на карте меньше, чем просили вывести; card_closed_by_issuer — банк закрыл карту; provider_declined — банк отказал; provider_unavailable — банк не выполнил операцию за сутки; insufficient_funds — выпуску или пополнению не хватило баланса, его успели потратить запросы к моделям. Перечень растёт: незнакомый код — просто отказ.

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

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

Почты у всех компаний песочницы общие, как в рабочем xWires. Почту, которую уже взяла другая компания, ваша не получит: в POST /subscriptions будет 202 с приглашением или 409 chatgpt_email_taken. Поэтому в своих запросах вместо почт из примеров берите свои, например под .invalid. Session песочница проверяет, как рабочий API, но не хранит и никуда не передаёт. Пришлите придуманный той же формы, как subscription.json выше, со своей почтой ChatGPT и expires в будущем. Настоящий session сотрудника не нужен.

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

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

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

• Ключ песочницы в рабочем API и рабочий ключ в песочнице получают 401 invalid_api_key, а в message сказано, куда этот ключ отправлять.
• Шаги, которые в рабочем xWires делают сотрудник, оператор и партнёр, делает песочница: сама (автопилот) или по вашему запросу. В событиях этих шагов actor — null, как у действий людей, поэтому система, которая отбрасывает эхо своих запросов по actor.api_key_id, их увидит.
• Автопродление открыто каждой компании песочницы: {"renewal": "monthly"} не получает 409 auto_renewal_closed. Заказ с автопродлением выполняется, как в рабочем xWires: оно включается, приходит subscription.auto_renewal_started, его можно отключить. Продление от OpenAI песочница показывает, когда вы заканчиваете оплаченный месяц запросом POST /sandbox/employees/{id}/expire-subscription: подписка продлевается (subscription.renewed), а с renewal в теле продление не проходит (subscription.renewal_failed).
• Чего в песочнице не увидеть: статуса submitting (заказ с автопродлением идёт из scheduled сразу в sent), отмены заказа самим сотрудником, продлений по расписанию (месяц кончается только по вашему запросу) и stop_reason user, operator, payer_changed, plan_changed и openai_off: за придуманных сотрудников и оператора никто не действует. Обработку этих событий и значений проверяйте по их описанию в руководстве.
• Карты компании песочницы включены с первого входа, вместо банка — подставной (ниже).
• Лимиты, ошибки и форма ответов — те же, что в рабочем API.

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

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

Автопилот

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

Продление активной подписки, как в рабочем xWires, уходит партнёру в scheduled_for, когда кончится оплаченный месяц: до тех пор заказ стоит в scheduled, и дальше его не перевести (409 sandbox_invalid_transition). Чтобы не ждать, закончите месяц сейчас запросом POST /sandbox/employees/{id}/expire-subscription: продление сразу уйдёт партнёру, подписка останется active, а после выполнения придёт subscription.renewed с expires_at через месяц. Без ждущего продления тот же запрос завершает подписку: subscription.expired.

Подписку с включённым автопродлением тот же запрос продлевает так, как это делает OpenAI: оплаченный месяц кончается сейчас, заказ продления с origin: auto_renewal выполняется, приходят order.scheduled, order.sent, order.succeeded и subscription.renewed, а expires_at — через календарный месяц от этого момента. Чтобы увидеть неудачу продления, пришлите {"renewal": "declined"}, not_charged или card_unusable: заказ не выполнится, придут subscription.renewal_failed с этим failure_reason, subscription.auto_renewal_stopped и subscription.expired.

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

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

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 или, с ждущим продлением, subscription.renewed — POST /sandbox/employees/{id}/expire-subscription.

Карты

У компании песочницы карты включены с первого входа: тариф «риски на нас» и $10 000 тестовых денег на балансе. Ключу нужно право «Карты», как в рабочем API. Вместо банка — подставной: операцию с картой он заканчивает сам, когда её подхватит автопилот, обычно меньше чем за полторы минуты, и приходит то же событие card.*, что в рабочем xWires.

• Выпущенная карта — Visa с последними цифрами 0002 на 24 месяца. Её реквизиты (GET /cards/{id}/details) — тестовый номер 4000000000000002 и CVV 123: им нигде не заплатить. Показ записывается в журнал и идёт в лимит, как в рабочем API.
• Сумму с центами .13 — выпуск, пополнение или вывод "10.13" — банк отклоняет: card.operation_failed с failure_code provider_declined, деньги вернулись на баланс. Вывод больше, чем можно, — insufficient_available, как в рабочем xWires.
• Покупку, холд, отказ или возврат по карте изображает POST /sandbox/cards/{id}/transactions: приходит card.transaction, транзакция видна в GET /cards/{id}/transactions, остаток карты меняется. Четвёртый отказ по карте закрывает её, как банк: card.closed с closed_reason issuer, а при тарифе «риски на нас» — card.replaced и карта-замена с тем же остатком.
• В «Интеграциях» песочницы можно сменить тариф карт: без тарифа выпуск и пополнение отвечают 409 cards_not_enabled. Кнопка «Добавить $10 000» пополняет баланс; когда денег мало, выпуск и пополнение отвечают 409 insufficient_funds.

Отказ по карте, как его записал бы банк:

curl -sS -X POST https://api.sandbox.xwires.ai/company/v1/sandbox/cards/b3e7a1d5-9c2f-4e68-a0b4-6d1c8f3e5a27/transactions \
  -H "Authorization: Bearer $XWIRES_COMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"decline","amount":"20.00"}'

{
  "id": "4a9d2c6e-1f7b-4b35-8e90-3c5a7d1f9b62",
  "type": "purchase",
  "status": "declined",
  "amount": "20.00",
  "currency": "USD",
  "merchant_amount": "20.00",
  "merchant_currency": "USD",
  "merchant_name": "OPENAI *CHATGPT SUBSCR",
  "occurred_at": "2026-10-25T09:14:03.518204+00:00"
}

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

Схемы

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