開発者プラットフォーム・全般 API · webhooks · コネクタ

プラットフォームを作る人工知能の運用性

Call 2,418 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 契約

スコープ付きベアラーキー2,418 contract actionsOpenAPI 3.0.3 + 郵便利用者HMAC Webhook デリバリー

リクエストのスキャッピング

署名されたwebhook アウト → 200 OK

ライブ

2,418名前概要 API アクション

69少なくとも特権範囲

dry_run実行前に書き込み契約を検証する

24時間成功したidempotent-writeリプレイ

ライフサイクルの要求

リクエストのスキャプサイン会を終了しました。

アクションをPOSTする /api/v1.php スコープ付きベアラーキーを使って。OpsIQ ワークスペースをピンで止め、アクション契約と権限を検証し、実行またはドライランを実行します。購読されたキャノンイベントは、追跡可能な試みと拘束されたレトリーを持つHMAC署名の配送キューによって残されます。

HMAC-SHA256 Webhooksの使い方 - インバウンドとアウトバウンドのWebhookペイロードは、生体の上に署名されます。 API コールはスコープ付きベアラーキーで認証します。

自動レトリー - 発送を返し、再配達に失敗しました。配送IDで追跡できます。

再生安全書き込み - 成功する idempotent writes は、同じ応答を返します。24 時間;同時重複は1つの主張を共有します。

01 ベアラーリクエスト 02 ピンワークスペース 03 契約を検証 04 実行またはドライラン 05 キュー署名イベント

クイックスタート

キーから、統合を管理 3つのステップ。

少なくとも優先キーを発行し、生成された契約を発見し、書き込みを実行してからアプリケーションが背景イベントの配信を必要とするときにWebhookを購読します。

契約コンソール接続先

実行するDry_run → 承認された書き込み、同じ契約

鍵をつけよう

スコープ付きベアラーの登録と生成 API キー ()opq_…) 開発者の設定で、各統合が必要な表面だけに与えます。

発見と検証

読み込み meta.actions, meta.action それに meta.scopes; 使用 dry_run 実行前に書き込みを検証します。

実行とサブスクリプション

書き込み用の出金キーを追加し、アプリケーションのニーズを満たす観点から必要なイベントにエンドポイントを購読します。

一緒に合う方法

コネクターのパターン1つ。きれいなプリミティブ5本

プラットフォーム固有のものは、コネクタに住んでいます。 OpsIQ コアは汎用性を維持し、AIは予測可能であり、統合は監査可能になります。

トリガー

OpsIQ に何が起こったのかを教えてください。

プラットフォームからキャノンイベントを省略したり、規制されたカスタムイベントを定義したりします。登録者は登録された優先順位と配送ルールでイベントを受け取ります。

イベントの参照

ユニバーサル+カスタムイベントinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up または、あなた自身の。 ファンアウト加入者AI の脳、オートメーションの規則、ミラーのコネクターおよびあなたの webhook はすべての原子炉を終点見ます。 優先注文決定的なディスパッチは、警告が火を前に書き込むようにミラーをします。

02 / アクション契約

お問い合わせ OpsIQ AIができること。

名称を付けられた操作は、スコープ、機能、読み取り、書き出しの種類、リスク、確認ポリシー、要求および応答スキーマ、ドライランサポート、不在性および安定したエラー。

アクションスキーマ

AIはアクションを発明できません登録したものを全て実行するように依頼できます。 確認ポリシーリスクアクションは、副作用が発生した前にプレビューカードをトリガーします。 ロール+表面にgatingアクションは、実行する権限を持つロールと表面を宣言します。

生成されたアクション契約・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 _/ 署名されたwebhooks

暗号化証拠でイベントをスタックにプッシュする。

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.

再生の保護トレーサブルデリバリーID5-step back-off

Webhook リファレンス

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 /SDK の一覧

直接HTTPを使用して、またはお好みのクライアントを生成します。

完全な一般API OpenAPI として公開 3.0.3 と Postman. PHP 参照の送信者プラス Node および Python インテグレーションクライアントは、署名されたイベントと webhook フローをカバーします。任意のスタックが同じを呼び出すことができます 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.",
    },
)

ダイレクト JSON コンテンツOpenAPI 3.0.3_ は、ポストマンコレクション統合ヘルパー

05 /コネクターパターン

一度ビルドします。何かに差し込む。

コネクタは、Identity, Auth, Test, Actions, Triggers and Review で生成またはインポートされたパッケージです。そのマニフェストは機能面を宣言します OpsIQ を公開することができます。

6段のビルダーを開く

6つのガイドされた段階アイデンティティ、Auth、テスト、アクション、トリガー、レビューはパッケージ生成を説明可能に保ちます。 契約主導8 profiles and 57 capability types declare the surfaces a package implements. リリースパッケージが準備される前に安全、証明および適合の点検は動くことを確認します。

意図から安全な行動まで

英語でのプレーン監査された操作。

OpsIQ は、正しい呼び出しを発明しません。登録契約を通り抜けてペイロードの準備を行い、アクションが要求されると確認を求め、実行時に完全な監査行を作成して、AIが実行できる アクション 信頼できないAIになることはありません。

契約締結 登録されたアクションだけをAIが提案する。

副作用の前に確認して下さい。 リスクアクションは、プレビューカードを最初に表します。

トータルリコール AIの歴史で捉えられたあらゆるプロンプト、応答および行動結果。

アクションスキーマを見る

4 手順意図した → 監査

HMAC実行前に署名

発明された呼び出しなし契約レジストリのみ

確認ゲート副作用前のプレビュー

リクエストトレース俳優 + 契約 + 結果

リファレンス

API 表面一見で。

One JSON POST surface exposes 2,418 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乾燥_run + 出土構成/時間

ACTION security.reportsecurity.write乾燥_run + 出土構成/時間

ACTION platform.routes.write管理者確認 + キー構成/時間

読書と発見のアクション同じポストの表面・安定した封筒

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乾燥_run + 出土構成/時間

ACTION hr.org.treehr.read読むだけ構成/時間

PeopleOS HRは、アウトバウンドのHR Webhookイベントを送らない。同じPOST面でそれに到達するか、他のモジュールを公開するイベントに購読します。完全な参照: スタッフAPIコネクターおよびとは開発者向けリファレンスの PeopleOS セクション. モジュールは刻まれた、従ってキー無しです hr 空のリストではなく、拒否を取得します。 PeopleOS HRとは.

レート制限は、キーごとに1時間単位で設定されます。応答の露出 X-RateLimit-Limit, X-RateLimit-Remaining それに X-RateLimit-Reset;拒否された要求のリターン 429 とりあえず Retry-After. 使用して下さい OpenAPI 3.0.3 契約またはポストマンコレクション同じランタイムレギュストリーから生成される。

コネクターを造って下さい

ビルド、テスト、リリース 6段階。

管理されたプロファイルから始めて、契約を自分で定義します。Builderは、各ステージで検証し、自己完結型のコネクタパッケージを生成することができます。

1アイデンティティ。名前、スラグ、プロフィールおよび宣言された機能表面。

2投稿ナビゲーション API キー, ベアラー, 基本, OAuth 2.0、HMACか習慣の顧客。

3試験。パッケージング前の境界接続設定を検証します。

4アクション操作、パラメータ、スコープ、リスクをマップします。

5トリガ。インバウンドイベント、Webhooks、ポーリング、および同期動作を宣言します。

6インタビュー生成された契約を点検し、解放ゲートを渡して下さい。

発送前にテスト

安全に検証し、リリースゲートを通過します。

利用条件 dry_run サポートされている書き込みアクションで、Builderの境界接続テストを実行し、生成されたマニフェストと契約を検査してリリース前に。パッケージ検証では、機能名、設定、実証済みファイル、および必要なファイルをチェックします。背景ワーカーは反応性ポーリングとアウトバウンド配信を処理します。

ドライランの書き込み境界接続テスト契約の適合クロネ駆動のデリバリー

コネクターのビルダーを開けて下さい Webhook リファレンス

コネクタ. php・php

レッスン AcmeConnector エクステンダー AbstractConnector { 公共機能 slug(): 文字列 { 返品 'acme' は、; } 公共機能名前(): 文字列 { 返品 'アッメ'; } 公共機能説明(): 文字列 { 返品 'アメ橋'; } // コネクターから名前を使うContract 公共機能機能(): 配列 { 返品 ['actions'の一覧, 'webhook'(ウェブホーク)]; } 公共機能設定Schema(): 配列 { 返品 [['key'のキー => 'token' をつけて, 'type' の => 'password' の使い方]]; } 公共機能試験接続(配列 $settings): 配列 { 返品 ['success'(成功) => ふりがな]; } 公共機能ハンドルWebhook() 配列 $payload, 配列 $headers, 配列 $settings ): 配列 { 返品 ['success'(成功) => ふりがな]; } }

01 · Connector contract 2.4

パッケージは機能を要求できませんソースコードは存在しない。

OpsIQ\Connectors\ConnectorContract 権威です。ランタイムの発見、ビルダー、ファーストパーティパッケージ、コンフォーマンス、一般 API そして、すべての参照は1つのレジストリを読んでいます。機能と3つのファイルを宣言するには、前に互いに同意する必要があります OpsIQ 1行を1列にルーティングします。

フィグ 01コネクターのパッケージ、部品のマニフェスト scale 1:1 · contract 2.4

01 connector.php 実行時間クラス
02 IdentityProvider.php 安定した外的なキー
03 SalesIngest.php セールス()
04 actions.json 名称の業務
05 settings.json オペレータ構成
06 connector_contract.json 機械読み取り可能な権限

07 signature.json 上記各ファイルのSHA-_256 に1 HMAC を上回る、および 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

二つの署名、2つの質問。

hmac-sha256 ファイルごとの決定的なペイロードを超える SHA-256 ハッシュは応答します 署名以来、この修正が. An ed25519 署名的な回答 Nabtech で署名しました, バンドルされた公開鍵と共有シークレットでチェック可能。 1バイトの編集と最初の停止マッチング。

marketplace.json 定義によって署名の外にある:インストーラは署名後に書きますので、出版社はそれを署名したことがないかもしれません。

02 · ツール/mutation_proof. php

失敗したことがないガード未確認です。

緑のテストは、今日何も壊れていないことを教えてくれます。彼らはあなたが書いたガードが止まるのを止めないと伝えません。監視は何もしないガードのように正確に通過しません。だから我々は目的にその心を停止し、モニターが叫ぶという要求をします。

ガード・読み取りロールは破壊的な操作を拒否しなければなりません チャイニーズ 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    }

事実上 ワンポイント テキストマッチが必要です。ゼロマッチ、または2つ、それを取り除く前にプルーフストップします。

$ 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.

失敗した証拠はあります 決してない 記録。チェックが間違っていた証拠は、ガードの動作を証明するものではありません。

突然変異が起きない。

検索テキストが一致しなかった、ファイルが無接触で、スイートが渡されたり、証拠が記録された 古いコードの下にある緑色 古くからなかったコードについて。正確に1つのテキストマッチと、ファイルハッシュを比較することによってキャッチします。

突然変異が起きた。

ファイルが解析やブートストラップが死亡しなくなったため、スイートは赤色になり、ガードで何もしないという証拠が記録されました。突然変異物を裏切って、ミュータントを要求することによってキャッチ 名義: 失敗の中でテストします。

ディスクにミュータントを残さない。

ミューテーションは、元のものをウェブ・サービスツリーの外側にサイドカーにコピーし、マーカーを記述して、顕著な変更を命じて、すべての出口経路上のシャットダウンハンドラで元に戻ります。クラッシュされたランからのマーカーが、そのファイルの次の変異の前に呼び出されます。

03 · Conformance

認証はコマンドです出口コードを使って。

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 互いに同意し、お互いに同意する
機能: 実行時に存在するクラス
interfaces 宣言された場所を実装
files 必要なファイルが存在するすべての
アクション アクションをマッチするマニフェスト
destructive 確認宣言
アイデンティティ 安定した外部キー、電子メールなし
再プレイ 繰り返し更新, 決して重複しません
エンタープライズ 宣言は拡張子に一致します
ドキュメント README、デベロッパー、CHANGELOG
スキーマ 全て 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. まだ反復している間、最後の1をスワップします --unsigned-ok: 未踏の署名を、その警告よりも優先するというような警告として扱います。

04 · 商取引_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 は、名前が約束ではないため、操作名から1つを決して劣らない。

あなた自身の行動

操作は、あなたの中に表示されなければなりません actions.json. 何も生成しない顧客の事を約束しないものを宣言する。

回復を宣言する書き込み

プラットフォームがすでに作業をやった後、最も危険なタイムアウトは1つです。意図しない「私の書き込み土地を落とす」ルックアップなし、唯一のオプションは再試行または注文を失うことです。

支払ロールは認証を証明します

支払いクラスの役割も宣言します payment_profile とりあえず 社会招聘, webhook_verify プロバイダー独自のスキームを使用して、 event_map. 未定の環境は、テストモードプロバイダがライブ決済を要する方法です。

Builder は、タイプとしてこれらを検証し、検証者は出荷パッケージを検証します。どちらの呼び出しも同じ機能なので、解約できません。

⚖️ 比較方法

OpsIQ 対 a DIYの統合。

契約締結、署名、監査されたプラットフォームは、あなた自身のwebhookとAIアクション配管を決してロールアウトすることを可能にします。

機能の能力	自分をロールアウト	OpsIQ
スコープ付きベアラー API + HMAC-署名型webhooks	ハンドロール	✓
ドライランは、+ 24-hour 成功再生を書き込みます	ダイニング	✓
1m → 5m → 30m →2h → 12h リトリーズ	DIY キュー	✓
アクション・コントラクトレジストリ(AIは呼び出しを発明できません)	—	✓
副作用前の確認ポリシー	—	✓
安定したエラーエンベロープリクエスト + ID	手動ロギング	✓
直接 HTTP + 生成されたクライアントオプション	自分を自分で書き込む	✓
OpenAPIの使い方 3.0.3 機械で読める契約	たぶん	✓
6段ビルダー+パッケージリリースゲート	ツールチェーンの構築	✓
ワークスペースをピンキーと時間単位で制限	クーポン	✓
コネクターパターン: プラットホームコードは隔離されたままにします	—	✓

よくある質問

開発者の質問, 回答する。

認証、契約、レトリー、クライアント生成、安全なテスト、およびコネクタモデル、最初の生産要求の前に。

一般的な API 呼び出しは送信します Authorization: Bearer opq_…. キーは、制限されていないか、または読み取り専用にすることができます。少なくとも特権範囲を運びます。時間単位で上限を確保し、作業スペースにピン留めできます。 Webhookの署名は別です: アウトバウンド配送キャリー X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event それに X-OpsIQ-Delivery.

いいえ。AIは、アクションレジストリで名前付き操作だけを提案することができます。各生成された契約は、スコープ、リクエストフィールド、リスクおよび確認ポリシーを宣言します。ポリシーが実行前に確認面を人間のプレビューを必要とする操作。

リクルート hash_hmac('sha256', $rawBody, $secret) と六角形の消化を比較し、 X-OpsIQ-Signature 利用方法 hash_equals. 検証 X-OpsIQ-Timestamp 再生ウィンドウ内と使用 X-OpsIQ-Delivery 追跡可能な配達識別子として。

バックグラウンドデリバリーのキューに失敗しない試みが入ります。OpsIQ リトリーズオン1-分、5-分、30-分、2-時間および 12- 配達識別子および診断のための試みの履歴を維持している間時間の梯子。

コールする JSON アクション・サーフェスは、生成されたPostmanコレクションを直接インポートするか、OpenAPI からクライアントを生成するか 3.0.3. PHPリファレンスの送信者とNode/PythonインテグレーションクライアントがイベントやWebhookフローをサポートし、別々ではなくヘルパーです。API 契約。

利用条件 dry_run 生成されたコントラクトがサポートするアクションで、Connector Builderの境界接続テストを実行し、生成したファイルを検査し、パッケージ適合とリリースゲートを渡すことで、コネクタを準備できます。

インストールされたリリースは、そのリリースを生成します API 自社のランタイムレギュレージからコネクタ契約。展開は公開 URL, 秘密, ストレージと cron/workers, そう動作は、クラウド環境から想定されるのではなく、インストールされたリリースに対して検証する必要があります.

コネクターはアダプターを含む管理されたパッケージです、 settings.json、任意 actions.json、生成された機能契約、文書化およびオプションの企業拡張。 6段ビルダーはそれを組み立てます。レジストリはそれを発見します。適合とリリースゲートが検証します。

プラットフォームを作る 人工知能の運用性

リクエストのスキャプ サイン会を終了しました。