Платформа разработчика · Общие API · веб-хуки · разъемы

Создайте свою платформу Работает с ИИ.

Call 2,420 named operations through one contract-generated API, with least-privilege scopes, workspace pinning, dry-run validation and replay-safe writes. Subscribe to canonical events through HMAC-signed background webhooks, or build a governed package in the six-stage Connector Builder.

Получить ключ API Читать ДОКС Контракт OpenAPI

Скошенные ключи Bearer2,420 contract actionsOpenAPI 3.0.3 + ПочтальонHMAC Web-cook доставка

Скорпионская просьба

Подписанный webhook out → 200 Хорошо

Живи

2,420Названы действия General API

69сфера наименее привилегий

dry_runПроверка письменных контрактов перед исполнением

24hУспешный перезапись идемпотента

Жизненный цикл запроса

Запрос был сбит. Подписано событие.

Позволить действию /api/v1.php с помощью ключа Bearer. OpsIQ закрепляет рабочее пространство, проверяет договор действия и разрешения, затем выполняет или обрабатывает его. Подписанные канонические события уходят через подписываемую HMAC очередь доставки с отслеживаемыми попытками и ограниченными повторами.

Веб-хук HMAC-SHA256 - входящие и исходящие полезные нагрузки веб-хука подписаны на необработанный корпус; API вызовы аутентифицируются с помощью приложенного ключа Bearer.

Автоматические повторы - неудавшиеся поставки назад и повторный, с идентификатором доставки вы можете отследить.

Replay-safe пишет - успешные идемпотентные записи возвращают один и тот же ответ за 24 часов; одновременные дубликаты разделяют одно утверждение.

01 Запрос на предъявителя 02 PIN-пространство 03 валидация договора 04 выполнять или сушить 05 Очередь подписанного события

Быстро стартовать

От ключа к регулируемой интеграции Три шага.

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

Контрактная консольподключенный

казнитьdry_run → утвержденный контракт

Получить ключ

Зарегистрируйтесь и создайте ограниченный ключ Bearer API (opq_…) в настройках разработчика и придавать каждой интеграции только те поверхности, которые ей необходимы.

Discover & Validate

Читать meta.actions, meta.action и meta.scopes; использование dry_run Проверка записей перед казнью.

Исполнитель & Подписка

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

Как они сочетаются

Один шаблон разъема. Пять чистых примитивов.

Все, что касается платформы, живет в разъеме. Ядро OpsIQ остается общим, ИИ остается предсказуемым, а ваша интеграция остается поддающейся аудиту.

Триггеры

Рассказать OpsIQ Что только что произошло.

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

Ссылка на событие

Универсальные + пользовательские событияinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up Или свой собственный. Подписчики Fan-outМозг ИИ, правила автоматизации, зеркальные разъемы и конечные точки вашего веб-хука реагируют. Приоритетный порядокДетерминистическая посылка, так что зеркала пишут перед тем, как предупредить о пожаре.

02 / Договоры на выполнение

Скажите OpsIQ, что ИИ может делать.

Каждая названная операция получает сгенерированный контракт: объем, функция, тип чтения или записи, риск, политика подтверждения, схема запроса и ответа, поддержка в сухом режиме, импотенция и стабильные ошибки.

Схема действий

ИИ не может изобретать действияОн может попросить только те, которые вы зарегистрировали. Политика подтвержденияРискованные действия запускают предварительную карту до любого побочного эффекта. Роль + поверхностное зудящееКаждое действие объявляет роли и поверхности, которые позволяют ему выполняться.

сгенерированный договор действия · JSON

{
  "action": "tickets.reply",
  "kind": "write",
  "scopes": ["tickets.write", "admin"],
  "feature": "ticket_system",
  "risk": "medium",
  "confirmation": "recommended",
  "idempotency": "supported",
  "dry_run": true,
  "request": { "type": "object" },
  "response": { "required": ["success"] }
}

03 / Подписанные веб-хуки

Нажмите события в свой стек - с криптографическим доказательством.

Subscribe any URL to any of the 52 deliverable events. OpsIQ POSTs the JSON payload signed with HMAC-SHA256 over the scheme version, the timestamp, the delivery ID and the body together, not the body alone, so yesterday's delivery cannot be replayed at you today.

Защита от повторовИдентификатор прослеживаемой доставки5-step back-off

Ссылка на Web-cook

Проверить webhook - php

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_OPSIQ_SIGNATURE'] ?? '';   // "v2=<hex>"
$ts  = (int)($_SERVER['HTTP_X_OPSIQ_TIMESTAMP'] ?? 0);
$id  = (int)($_SERVER['HTTP_X_OPSIQ_DELIVERY'] ?? 0);

if (abs(time() - $ts) > 300) http_response_code(401);   // replay window
[$ver, $hex] = array_pad(explode('=', $sig, 2), 2, '');  // split the prefix

$signed   = $ver . '.' . $ts . '.' . $id . '.' . $raw;   // NOT the body alone
$expected = hash_hmac('sha256', $signed, $secret);
if (!hash_equals($expected, $hex)) http_response_code(401);

$event = json_decode($raw, true);   // $id is stable across retries

04 /SDKs

Используйте HTTP или создайте клиент, который вам больше нравится.

Полный генерал API Публикуется как OpenAPI 3.0.3 PHP-отправители ссылок, а также клиенты интеграции Node и Python охватывают подписанные события и потоки веб-хуков; любой стек может называть то же самое JSON Поверхность действия непосредственно.

Примеры клиентов

const response = await fetch(`${base}/api/v1.php`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPSIQ_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    action: "tickets.reply",
    dry_run: true,
    idempotency_key: crypto.randomUUID(),
    body: "Thanks. We are checking this now."
  })
});

$payload = json_encode([
  'action' => 'tickets.reply',
  'dry_run' => true,
  'idempotency_key' => bin2hex(random_bytes(16)),
  'body' => 'Thanks - we are checking this now.',
]);

$ch = curl_init($base . '/api/v1.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('OPSIQ_KEY'),
    'Content-Type: application/json',
  ],
]);

response = requests.post(
    f"{base}/api/v1.php",
    headers={
        "Authorization": f"Bearer {os.environ['OPSIQ_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "action": "tickets.reply",
        "dry_run": True,
        "idempotency_key": str(uuid.uuid4()),
        "body": "Thanks - we are checking this now.",
    },
)

Direct JSON HTTPOpenAPI 3.0.3Коллекция PostmanИнтеграция помощников

05 / Модель разъема

Построй один раз, подключи что угодно.

Разъем - это управляемый пакет, генерируемый или импортируемый через идентификатор, аутентификацию, тест, действия, триггеры и обзор. его манифест заявляет, что поверхности возможностей OpsIQ могут быть раскрыты.

Откройте шестиступенчатый конструктор

Шесть управляемых этаповИдентичность, аутентификация, тест, действия, триггеры и обзоры позволяют объяснить генерацию пакетов. контрактный8 profiles and 57 capability types declare the surfaces a package implements. освобожденныйПроверки безопасности, происхождения и соответствия выполняются до того, как пакет будет обработан.

От намерения к безопасным действиям

Просто английский. Проверенная операция.

OpsIQ никогда не изобретает правильный вызов. Он проходит через зарегистрированные контракты, готовит полезную нагрузку, просит подтверждения, когда это требуется действием, и производит полную строку аудита, когда он выполняется, поэтому ИИ, который может действовать Никогда не становитесь ИИ, которому нельзя доверять.

Контрактный. ИИ предлагает только те действия, которые вы зарегистрировали.

Подтвердите побочные эффекты. Рискованные действия сначала отображают карту предварительного просмотра.

Полный отзыв. Каждый результат, ответ и действие запечатлены в истории ИИ.

См. схему действия

4 шаговЦель → аудита

HMACподписано до исполнения

Не придуманные звонкитолько договорный реестр

Подтвержденныйпредварительный просмотр перед побочными эффектами

Проверить следыАктер + контракт + результат

Ссылка

API поверхность С первого взгляда.

One JSON POST surface exposes 2,420 named actions. Each generated contract declares auth scopes, read/write kind, risk, confirmation, request schema, dry-run, idempotency and stable errors.

OpenAPI 3.0.3 Ссылка

МерыАутаПиши про безопасностьпредел

Пишите действияPOST /api/v1.php · Подтвержденный контракт

ACTION tickets.replytickets.writeСухой_рюн + идемпотенцияНастроенный / час

ACTION security.reportsecurity.writeСухой_рюн + идемпотенцияНастроенный / час

ACTION platform.routes.writeадминПодтверждение + ключНастроенный / час

Read & Discovery ActionsТа же поверхность POST · стабильные оболочки

ACTION meta.actionsОткрытое открытиеЧитать толькоНастроенный / час

ACTION tickets.listtickets.readЧитать толькоНастроенный / час

ACTION connectors.listconnectors.readЧитать толькоНастроенный / час

PeopleOS HR-действияЩедрый hr.* контрактов; hr.read / hr.write охват

ACTION hr.people.listhr.readЧитать толькоНастроенный / час

ACTION hr.people.createhr.writeСухой_рюн + идемпотенцияНастроенный / час

ACTION hr.org.treehr.readЧитать толькоНастроенный / час

PeopleOS HR не отправляет исходящие события в HR-хук. Достигните его через ту же поверхность POST или подпишитесь на опубликованные другие модули событий. Полная ссылка: PeopleOS API и разъемы и PeopleOS раздел ссылки разработчикаМодуль закрыт, поэтому ключ без hr Получается отказ, а не пустой список. Что такое PeopleOS HR.

Ограничения ставок настроены для ключа в почасовом окне. X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-ResetОтклоненный запрос возвращается 429 с Retry-AfterИспользуй OpenAPI 3.0.3 контракт или Коллекция Postman генерируется из тех же реестров времени выполнения.

Построить разъем

Создать, протестировать и выпустить в Шесть этапов.

Начните с управляемого профиля или определите контракт сами. Строитель проверяет каждый этап, прежде чем он генерирует автономный пакет разъема.

1Идентичность. Имя, слизь, профиль и заявленные поверхности возможностей.

2Ауф. API Ключ, Медведь, Базовый, OAuth 2.0 HMAC или пользовательский клиент.

3Тест. Проверяйте настройки ограниченного соединения перед упаковкой.

4Действия. Карта, которая называется операциями, параметрами, масштабами и рисками.

5Триггеры. Объявлять входящие события, веб-хуки, опросы и синхронизировать поведение.

6Обзор. Проверить сгенерированный контракт и пройти ворота выпуска.

Испытание перед отправкой

Проверяйте безопасно, затем пройдите ворота выпуска.

Использовать dry_run на поддерживаемых действиях записи, запустить тест ограниченного соединения Строителя и проверить сгенерированный манифест и контракт до выпуска. Проверка пакета проверяет имена возможностей, настройки, происхождение и необходимые файлы; фоновые работники обрабатывают реактивный опрос и исходящую доставку.

Сухой бег пишет Испытание на соединение с привязкой Согласование контрактов Доставка на основе крон

Открытый коннектор Builder Ссылка на Web-cook

connector. php · php

класс AcmeConnector расширять AbstractConnector { общественная функция слизняк(): струна { возвращение "акме"; } общественная функция Имя(): струна { возвращение "Акме"; } общественная функция Описание(): струна { возвращение «Акме Бридж»; } Используйте имена из ConnectorContract общественная функция Возможности(): массив { возвращение ["Действия", "вебхук"]; } общественная функция SettingSchema(): массив { возвращение [["ключ" => "Токен", "тип" => "пароль"]]; } общественная функция Тестовая связьмассив $settings): массив { возвращение ["успех" => истинный]; } общественная функция handleWebhook( массив $payload, массив $headers, массив $settings ): массив { возвращение ["успех" => истинный]; } }

01 · Connector contract 2.4

Пакет не может претендовать на способность Его код не имеет.

OpsIQ\Connectors\ConnectorContract Раскрытие времени выполнения, Строитель, пакеты первой партии, соответствие, Генерал API и каждая ссылка гласила, что один реестр. Объявить возможность и три файла должны согласиться друг с другом прежде чем OpsIQ Путешествуйте по одной строке к вам.

Фиг. 01соединительный пакет, части манифестируют scale 1:1 · contract 2.4

01 connector.php класс Runtime
02 IdentityProvider.php стабильный внешний ключ
03 SalesIngest.php Для сравнения()
04 actions.json Названы операции
05 settings.json конфигурация оператора
06 connector_contract.json машиночитаемый авторитет

07 signature.json один HMAC над SHA-256 каждого файла выше, плюс доказательство происхождения ed25519

Матричная способность all 57, as registered

действия триггеры веб-хук journey_events контекст guest_lookup личность sales sales_reconciliation выставление счетов payments торговля inbound_ticket outbound_reply ticket_merge sync_users sync_departments sync_orders sync_products sync_projects customer_import security_events security_native_block survey reply_feedback promo_audience promo_feed email_mailbox inbound_email outbound_email mailbox ai_tickets ai_reply ai_brain_aware native_api platform_bridge native_data смазывать block_registry inbound_comment outbound_note outbound_notification oauth reviews местный сео site_intelligence аналитика comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

генерируемый 30 декларативный 20 расширение 7

Две подписи, два вопроса.

hmac-sha256 - по детерминированной полезной нагрузке каждого файла SHA-256 хэш-ответов Это было изменено с момента подписанияАн. ed25519 Подпись Ответы Подпись под NabtechПроверяемый с помощью пульта открытого ключа и без общего секрета. Редактировать один байт и первые остановки согласования.

marketplace.json по определению находится вне подписи: установщик пишет ее после подписания, поэтому издатель никогда не мог бы подписать ее.

02 · Инструменты/мутация_proof. php

Охранник, который никогда не терпел неудачу Это не доказано.

Зеленые тесты говорят вам, что ничего не сломалось сегодня. Они не говорят вам о том, что охранник, которого вы написали, остановит то, что было написано, чтобы остановить, потому что охрана, которая никогда не тренируется, проходит точно так же, как охранник который ничего не делает. Поэтому мы специально останавливаем его сердце и требуем, чтобы монитор кричал.

Охрана · Читательская роль должна отказаться от разрушительной операции CH1 verify_commerce_contracts

src/Connectors/CommerceRoleMapVerifier.php мутативный

211    /* A read role must never reach a destructive operation. */
212-   if ($isRead && $isDestructive) {
212+   if (false) {
213        $errors[] = "read role '{$role}' points at a destructive op";
214        return false;
215    }

Точно. один Нулевые совпадения, или два, и доказательство останавливается прежде чем оно сможет солгать.

$ php tools/mutation_proof.php --spec=proofs.json

1[ ok ]hash    sha256 4f2a9c1e…
          remember the file exactly as it is
2[ ok ]control exit 0
          green BEFORE anything is touched
3[ ok ]mutate  1 match, lint ok
          one replacement, then php -l the mutant
4[RED ]prove   exit 1
          and "read role destructive" IS in the failures
5[ ok ]restore bytes written
          the original, not a regenerated copy
6[ ok ]verify  sha256 matches
          and the check is green again
 ══ PROVEN. file restored, hash matched, 1 proof run, 0 failed.

Неудавшееся доказательство является никогда Доказательства того, что проверка прошла неправильно, не являются доказательством того,что охранник работает.

Мутация никогда не применялась.

Текст поиска не совпадал, файл был нетронут, пакет прошёл, а доказательство записано Зеленый под старым кодом Код, который никогда не был старым. Пойман с помощью точного совпадения текста и сравнения хешей файлов с обеих сторон.

Мутация сломала что-то другое.

Сюита покраснела, потому что файл перестал разбирать или загрузочный шлюп умер, а доказательство зафиксировало красный цвет, который не имел ничего общего с охранником. названный Тестирование среди неудач.

Он не может оставить мутанта на диске.

Каждая мутация копирует оригинал в коляску за пределами дерева, обслуживаемого веб-сайтом, пишет маркер, называя выдающееся изменение, и отменяется обработчиком остановки на каждом пути выхода. Маркер из разбившегося пробега почитается перед следующей мутацией этого файла.

03 Соответствие

Сертификация – это команда с выходным кодом.

Not a review queue where somebody reads your code and forms an opinion. Run the same suites we run, on your own machine, before you submit. 8 published JSON Schemas under doc/contracts/schemas/ охватывают настройки, действия, спецификации строителя, отображения событий путешествия и коммерции, рецепты рабочего процесса, контракты разъема и манифесты выпуска.

manifests Посмотреть и согласиться друг с другом
возможности существуют в классе Runtime
interfaces осуществляется в том случае, если объявленное
files Каждый необходимый файл
действия Соответствие действиям манифеста
destructive заявлять о подтверждении
личность Стабильный внешний ключ, а не электронная почта
переигрывать Повторяющиеся обновления, никогда не дублируются
предприятие Заявления соответствуют продлению
документы ЧИТАЙТЕ, ДЕВЕЛОПЕР, КАНДЖЕЛОГ
схемы Все JSON проверяются

выход 0 acme: conformant against contract 2.4 Неудачный номер именует чек и файл, вы исправите его, а не мы.

$ php tools/test_connector_conformance_all.php --connector=acme $ php tools/test_connector_json_schemas.php $ php tools/verify_commerce_contracts.php $ php tools/release_gate_connectors.php --require-signatures

Напишите первый пункт на реальном непроизводственном счете --live-settings=/secure/test-acme.jsonПока вы все еще повторяете, поменяйте последний на --unsigned-okОн рассматривает отсутствующую подпись как ожидаемое предупреждение, а не притворяется, что это нормально.

04 · commerce_roles.json

Объясните, что вы можете продать Это файл, а не регистрация.

Коннектор, который может продавать, определяет, какой из собственный Операции отвечают каноническим ролям торговли OpsIQ. Наличие файла - претензия. Он появляется в настройках продажи в момент объявления и исчезает, когда он прекращается. Нет списка для присоединения и никого не спрашивайте.

каноническая роль commerce_roles.json Ваша операция

отстранённый

канонический писать Соответствие структурно: существительное хранилища рядом с мутирующим глаголом, независимо от вашего соглашения об именах. Написание бизнес-ряда напрямую пропускает цены платформы, блокировку доступности и почту подтверждения и производит заказ, в который собственная система продавца верит только наполовину. recovery И то, и другое было бы невозвратно.

commerce_roles.jsonВалид

{
  "commerce": {
    "roles": {
      "catalog_search": { "operation": "acme_search_products", "transport": "http" },
      "order_get":      { "operation": "acme_get_order",       "transport": "http" },
      "order_create":   { "operation": "acme_create_order",    "transport": "http",
                         "recovery":  "acme_get_order" }
    }
  }
}

Собственный файл по назначению: connector_contract.json генерируется и его наборы схем additionalProperties:falseТаким образом, блок с ручным авторством будет не валидироваться и затем перезаписываться на следующем запуске генератора.

Закрытый словарь

Роль, которая не в CommerceRole OpsIQ никогда не выводит имя из названия операции, потому что имя не является обещанием.

Собственные действия

Операция должна появиться в вашем actions.jsonОбъявление того, что не существует, обещает клиенту то, что затем ничего не производит.

Писать о восстановлении

Самый опасный тайм-аут — это тот, который после того, как платформа, возможно, уже сделала работу. Без идемпотентного поиска «сделала свою письменную землю», единственные варианты — это повторно ослепнуть или потерять заказ.

Платежные роли сертифицируются

Любая роль класса оплаты также декларируется payment_profile с помощью окружающая среда, webhook_verify использование собственной схемы поставщика, а также event_mapНезаявленная среда - это то, как поставщик тестового режима принимает оплату в реальном времени.

Строитель проверяет их по мере ввода, а проверяющий проверяет отправленный пакет. Оба называют одни и те же функции, поэтому они не могут не согласиться.

⚖️ Как это выглядит

OpsIQ против a Интеграция DIY.

Что связанная контрактом, подписанная, проверенная платформа дает вам, что прокатка ваших собственных веб-хуков и сантехника с искусственным интеллектом никогда не даст.

способность	Свернуть свой собственный	OpsIQ
Scoped Bearer API + HMAC-подписанные веб-хуки	ручной	✓
Dry-run пишет + 24-час успешной переигровки	ДИЙ	✓
1 мкм → 5 метров → 30 мкм → 2h → 12h повторные попытки	Очередь для DIY	✓
Реестр договоров действия (AI не может изобретать звонки)	—	✓
Политика подтверждения до побочных эффектов	—	✓
Стабильный конверт ошибок + идентификаторы запросов	Ручная рубка	✓
Direct HTTP + генерируемые клиентские опции	Напиши свой собственный	✓
OpenAPI 3.0.3 машиночитаемый контракт	Может быть	✓
Шестиступенчатый Builder + пакетный выпуск шлюза	Создайте инструментальную цепочку	✓
Ключи, привязанные к рабочему пространству и почасовые ограничения	Вариации	✓
Паттерн подключения: код платформы остается изолированным	—	✓

часто задаваемый вопрос

Вопросы разработчиков, ответил.

Аутентификация, контракты, повторные заказы, генерация клиентов, безопасное тестирование и модель разъема перед первым производственным запросом.

Общие API звонки отправить Authorization: Bearer opq_…Ключи могут быть неограниченными, ограниченными или только для чтения, иметь минимальные привилегии, соблюдать почасовой лимит и могут быть прикреплены к рабочему пространству. Подписание Webhook отдельно: исходящие поставки несут X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event и X-OpsIQ-Delivery.

Нет. ИИ может предлагать только названные операции в реестре действий. Каждый сгенерированный контракт объявляет область применения, поля запросов, политику риска и подтверждения; операции, политика которых требует подтверждения, выходят за рамки предварительного просмотра человеком перед выполнением.

рекомпьютер hash_hmac('sha256', $rawBody, $secret) и сравнить его с гексадециальным X-OpsIQ-Signature использовать hash_equalsПодтвердить X-OpsIQ-Timestamp В вашем окне воспроизведения и используйте X-OpsIQ-Delivery как отслеживаемый идентификатор доставки.

Неуспешная попытка входит в фоновую очередь доставки. OpsIQ петлица на 1- Минута, 5- Минута, 30- Минута, 2- час и 12- часовая лестница при сохранении идентификатора доставки и истории попыток для диагностики.

Звони. JSON непосредственное действие, импорт генерируемой коллекции Почтальона или создание клиента из OpenAPI 3.0.3 Отправители ссылок на PHP и клиенты интеграции Node/Python поддерживают события и потоки веб-хуков; они являются помощниками, а не отдельными.API контракты.

Использовать dry_run на действия, чей сгенерированный контракт поддерживает его, запустить тест ограниченного соединения разъема, проверить свои сгенерирован файлы и пройти пакет соответствия и выпустить шлюзы перед обработкой разъединения как готовое.

Установленный выпуск генерирует его API и контракты на разъем из собственных реестров времени выполнения. URL, секреты, хранение и cron/рабочие, поэтому поведение должно быть проверено на соответствие установленным параметрам, а не предполагаться из облачной среды.

Разъем представляет собой управляемый пакет, содержащий адаптер. settings.jsonфакультативный actions.json- сгенерированный контракт на предоставление возможностей, документация и дополнительные расширения предприятия. Шестиступенчатый конструктор собирает его; реестр обнаруживает его; соответствие и выпуск шлюзов подтверждают его.