개발자 플랫폼 · 일반 API · webhooks · 커넥터

당신의 플랫폼을 만드십시오 AI 운영 가능.

Call 2,415 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 키 받기 docs를 읽으십시오 OpenAPI 계약

스코프 Bearer 키2,415 contract actionsOpenAPI 3.0.3 + 포스트맨HMAC webhook 배송

Scoped 요청

웹훅을 호출→ 200ᄋᄉᄋ

레벨

2,415일반 API 동작

69최소 배당 범위

dry_run실행하기 전에 유효한 쓰기 계약

24시간성공적인 idempotent-write 재생

요청 수명주기

Scoped 요청. 로그인 이벤트

POST에 대한 작업 /api/v1.php 범위의 Bearer 키로. OpsIQ 핀 작업 공간, 작업을 검증하고 권한이 부여되며 실행하거나 건조를 실행합니다. 추적 가능한 시도와 경계된 retries가 HMAC 서명 된 배달 큐를 통해 구독한 후보 이벤트가 남깁니다.

HMAC-SHA256 웹훅 - inbound 및 아웃 바운드 webhook 페이로드는 원료 몸에 서명됩니다. API 은 범위의 Bearer 키로 정통합니다.

자동적인 retries - 배송을 다시 중단하고 재발송하지 않고 배송 ID를 추적 할 수 있습니다.

Replay-safe 쓰기 - 성공적인 idempotent는 24 시간의 동일한 응답을 반환합니다. 동시 복제는 하나의 주장을 공유합니다.

01 Bearer 요청 02 핀 작업 공간 03 계약의 유효성 04 실행 또는 건조-런 05 queue 서명 이벤트

퀵스타트

키에서 관리 통합 3 단계.

최소의 개인 키에 문제가 발생하면 생성 된 계약을 발견하고 서면을 건조 한 다음 응용 프로그램이 배경 이벤트 배달을 필요로 할 때 webhook을 구독하십시오.

계약 콘솔연결됨

실행Dry_run → 승인된 쓰기, 동일한 계약

키 받기

스코어의 수퍼 API 키 (을)를 호출하고 생성opq_…) 개발자 설정에서 각 통합을 필요로 하는 표면만 제공합니다.

디스커버리 & 검증

빨간색 meta.actions, meta.action 그리고 meta.scopes; 사용 dry_run 실행하기 전에 쓰기를 검증합니다.

실행 및 구독

쓰기에 대한 idempotency 키를 추가하고 응용 프로그램 요구의 후보자 이벤트에 최종 지점을 구독하십시오.

어떻게 함께 적합

1개의 연결관 본. 5개의 청결한 원시.

어떤 플랫폼 별은 커넥터에 살고 있습니다. OpsIQ 코어는 일반 유지, AI는 예측 가능, 귀하의 통합 감사를 유지.

트리거

OpsIQ 그냥 일어난 일에 대해 이야기하십시오.

플랫폼에서 공평한 이벤트를 진행하거나, 지배적인 사용자 정의 이벤트를 정의합니다. 구독자는 등록 된 우선 순위와 배달 규칙을 통해 이벤트를받습니다.

이벤트 참조

Universal + 맞춤 이벤트invoice.paid, ticket.created, subscription.cancelled, customer.signed_up 또는 당신의 자신의. 팬 아웃 가입자AI 뇌, 자동화 규칙, 거울 연결관 및 당신의 webhook 엔드포인트는 모든 반응합니다. 우선순위Deterministic 파견 그래서 거울은 경고를 불의 앞에 씁니다.

02 / 동작 계약

OpsIQ AI가 할 수 있는 것을 말해줍니다.

모든 이름의 작업은 생성 된 계약을받습니다 : 범위, 기능, 읽기 또는 쓰기 종류, 위험, 확인 정책, 요청 및 응답 스키마, 건조 실행 지원, idempotency 및 안정적인 오류.

활동 schema

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 / 로그인 웹훅

쌓아 올리는 이벤트 - 암호화 증거.

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.

Replay 보호추적 가능한 납품 ID5-step back-off

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 참고 senders 플러스 노드와 파이썬 통합 클라이언트 커버 서명된 이벤트 및 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 HTTPOpenAPI 3.0.3 를Postman 수집통합 helpers

05 / 커넥터 패턴

한번에 빌드하세요. 아무것도 입력하세요.

커넥터는 Identity, Auth, Test, Actions, Triggers 및 Review를 통해 생성되거나 수입 된 지배 패키지입니다. 그 표현은 기능 표면 OpsIQ 을 노출 할 수 있다고 선언합니다.

6단계 빌더를 엽니다.

6개의 가이드 단계Identity, Auth, Test, Actions, Triggers 및 Review는 패키지 생성을 설명합니다. 계약 구동8 profiles and 57 capability types declare the surfaces a package implements. 출시예정안전, 입증 및 준수 검사는 패키지가 준비되기 전에 실행됩니다.

안전한 행동에 intent에서

일반 영어 감사 작업.

OpsIQ 절대로 올바른 전화를 발명하지 않습니다. 등록 된 계약을 통해 걸어, 지불량을 준비, 작업이 필요할 때 확인을 요청하고, 실행 할 때 완벽한 감사 행을 생성, 그래서 AI는 할 수 행위 신뢰가 없을 수 없는 AI가 되십시오.

계약하행. AI는 단지 당신이 등록한 행동을 제안합니다.

부작용의 앞에 확인하십시오. 위험 작업 표면 미리보기 카드 먼저.

총 회신. 모든 신속한, 응답 및 행동 결과 AI History에 캡처.

활동 schema를 보십시오

4 단계intent → 감사

HMAC의 특징시작하기 전에 서명

발명 통화계약 레지스트리 만

견적 요청부작용의 앞에 시동

관련 상품actor + 계약 + 결과

참조

API 표면 한 눈에.

One JSON POST surface exposes 2,415 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.writeDry_run + idempotency를 제거하십시오구성 / 시간

ACTION security.reportsecurity.writeDry_run + idempotency를 제거하십시오구성 / 시간

ACTION platform.routes.write관리자확인 + 키구성 / 시간

읽기 & 발견 작업동일한 POST 표면 · 안정 봉투

ACTION meta.actions공공의 discovery읽기구성 / 시간

ACTION tickets.listtickets.read읽기구성 / 시간

ACTION connectors.listconnectors.read읽기구성 / 시간

PeopleOS HR 활동의약 hr.* 계약 · hr.read / hr.write 의 범위

ACTION hr.people.listhr.read읽기구성 / 시간

ACTION hr.people.createhr.writeDry_run + idempotency를 제거하십시오구성 / 시간

ACTION hr.org.treehr.read읽기구성 / 시간

PeopleOS HR은 아웃바운드 HR 웹훅 이벤트를 보내지 않습니다. 동일한 POST 표면으로 도달하거나 다른 모듈 출판 행사에 가입하십시오. 전체 참조 : PeopleOS API 및 커넥터 그리고 PeopleOS 개발자 참조 섹션. 단위는 entitlement 문질러, 그래서 열쇠 없이입니다 hr refusal을 얻고 빈 목록이 아닙니다. PeopleOS HR이란?.

속도 제한은 한 시간 창에 키 당 구성. 응답 노출 X-RateLimit-Limit, X-RateLimit-Remaining 그리고 X-RateLimit-Reset; 거부된 요청 반환 429 으로 Retry-After. 사용 OpenAPI 3.0.3 계약 또는 Postman 수집 같은 실행 시간 등록에서 생성.

연결관을 건설하십시오

빌드, 테스트 및 출시 6 단계.

관리된 프로파일에서 시작하거나 계약을 직접 정의합니다. Builder는 자체 유지한 커넥터 패키지를 생성하기 전에 각 단계를 검증합니다.

1이름 * 이름, 진창, 단면도 및 선언된 기능 표면.

2의. API 키, Bearer, 기본, OAuth 2.0, HMAC 또는 주문 클라이언트.

3시험. 포장하기 전에 경계 연결 설정을 유효.

4Actions. 운영, 매개 변수, 범위 및 위험이라는 맵.

5트리거. Declare inbound 이벤트, webhooks, polling 및 동기화 동작.

6Review. 생성된 계약을 검사하고 방출 문을 통과하십시오.

배송하기 전에 테스트

안전하게 유효하고, 그 후에 방출 문을 통과하십시오.

사용 dry_run 지원된 쓰기 행동에, Builder의 경계 연결 시험을 실행하고, 방출하기 전에 생성한 표정 및 계약을 검사합니다. 패키지 검증은 기능 이름, 설정, 입증 및 필요한 파일을 확인합니다; 배경 노동자는 민감하는 polling 및 outbound 납품을 취급합니다.

건조 런 쓰기 Bounded 연결 시험 계약 준수 Cron 구동 납품

열린 연결관 Builder Webhook 참조

커넥터. php · PHP

클래스 AcmeConnector 확장 AbstractConnector { 공공 기능 스크랩(): 문자열 { 돌아가기 ᄋᄋ; } 공공 기능 이름 (): 문자열 { 돌아가기 'Acme'의 특징; } 공공 기능 묘사 (): 문자열 { 돌아가기 'Acme 브리지'; } // ConnectorContract의 이름을 사용하십시오. 공공 기능 기능 (): 배열 { 돌아가기 ['작성', '웹훅']; } 공공 기능 settingsSchema(): 배열 { 돌아가기 [[닌자 => 'token'의 장점, '타입' => '암호']]; } 공공 기능 testConnection(테스트커넥션)배열 $settings): 배열 { 돌아가기 ['success'의 장점 => 참]; } 공공 기능 handleWebhook(웹훅) 배열 $payload, 배열 $headers, 배열 $settings ): 배열 { 돌아가기 ['success'의 장점 => 참]; } }

01 · Connector contract 2.4

패키지는 기능을 주장 할 수 없습니다. 그 코드는 없습니다.

OpsIQ\Connectors\ConnectorContract 권한입니다. 실행 시간 발견, 빌더, 첫 번째 파티 패키지, 적합성, 일반 API 그리고 모든 참고는 하나의 레지스트리라고 읽습니다. 기능과 세 개의 파일이 서로의 동의를 받아야합니다 OpsIQ 한 줄을 한번에 길러보세요.

FIG. 01의 경우연결관 포장, 부속은 나타냅니다 scale 1:1 · contract 2.4

01 connector.php 런타임 클래스
02 IdentityProvider.php 안정되어 있는 외부 열쇠
03 SalesIngest.php reconcileSales()의
04 actions.json 이름 작업
05 settings.json 통신망 설정
06 connector_contract.json 기계 학습 권위

07 signature.json 1,900 원 HMAC SHA- 이상256 위 각 파일의 ed25519 원산지 증명

기능 matrix 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 로컬 seo 의 site_intelligence 의 특징 comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

의제한 30 의례 20 의 확장 7

두 개의 서명, 두 가지 질문.

hmac-sha256 per-file SHA-256 hashes의 결정적인 페이로드 이상 답변 로그인이 수정되었습니다.. 아니 ed25519 서명 답변 Nabtech에 의해 서명되었습니다, 번들 공개 키와 공유 비밀을 확인. 하나의 바이트를 편집하고 첫 번째는 일치합니다.

marketplace.json 정의에 의해 서명 밖에있다: 설치자는 서명 후 그것을 작성, 그래서 게시자는 결코 그것을 서명 할 수 없었다.

02 · 도구/mutation_proof. php

실패하지 않은 가드 은하지 않습니다.

녹색 테스트는 오늘 깨지지 않습니다. 그들은 당신이 쓴 것을 중지하는 것이 썼다는 것을 말하지 않는다, 결코 운동이 아무것도하지 않는 경비처럼 정확히 통과하지 않기 때문에. 그래서 우리는 목적에 그것의 마음을 멈추고, 모니터 비명은 수요를 중단한다.

guard · 읽는 역할은 파괴적인 가동을 거부해야합니다. 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    }

의 특징 1개 텍스트 일치는 필요합니다. 0 경기, 또는 두 가지, 그리고 그것이 거짓말을하기 전에 증거 정지.

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

실패한 증거는 입니다 은지 기록. 체크가 잘못되었는지 증거는 가드가 작동한다는 증거입니다.

뮤테이션은 결코 적용되지 않습니다.

검색 텍스트는 일치하지 않았다, 파일이 untouched, 스위트 통과, 그리고 증거 기록 이전 코드의 밑에 녹색 거의 오래된 코드에 대해. 정확히 하나의 문자 일치를 필요로하고 파일 해시를 어느 쪽이든 상관해서 잡았다.

의 붓기는 다른 것을 깨어.

이 스위트는 파일이 파싱 또는 부츠 스트랩 사망했기 때문에 빨간색을 기록했으며 증거는 경비원과 함께 할 필요가 없었습니다. 돌연변이를 linting하여 잡았고 필요한 적색 이름 * 실패 중 테스트.

디스크에 돌연변이를 낼 수 없습니다.

모든 뮤테이션은 웹 보호 나무 밖에 사이드카에 원본을 복사하고, 마커가 뛰어난 변화를 남는 것을 쓰고, 각 출구 경로에 폐쇄 핸들러로 번들입니다. 충돌 실행의 감적은 그 파일의 다음 뮤션 이전에 영광됩니다.

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/ 설정, 행동, 빌더 specs, 여행 및 상거래 이벤트 매핑, 워크플로우 레시피, 커넥터 계약 및 릴리스가 나타납니다.

manifests 파스와 다른 것에 동의합니다.
제품정보 런타임 클래스에 존재
interfaces 선언된 곳
files 모든 필수 파일 현재
동작 행동을 일치
destructive 선언 확인
정체성 안정되어 있는 외부 열쇠, 이메일 아닙니다
재생 반복 업데이트, 결코 중복
엔터프라이즈 선언은 확장과 일치
docs의 README, 개발자, 프로젝트
뚱 베어 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의 대외 상거래 역할. 파일의 존재는 주장입니다. 그것은 그것이 중지 될 때 선언하고 사라지는 순간을 판매 설정에서 나타납니다. 참여할 목록이 없으며 요청 할 아무도 없습니다.

canonical 역할 commerce_roles.json 당신의 가동

OpsIQ 대 DIY 통합.

계약 경계선, 서명, 감사 플랫폼은 자신의 웹훅과 AI-action 배관을 결코 회전시키는 것을 제공합니다.

기능 제품	당신의 자신의 목록	OpsIQ
Scoped Bearer API + HMAC 서명 웹훅	손 목록	✓
건조 런 쓰기 + 24 시간 성공적인 재생	은	✓
1m → 5m → 30m →2h → 12h 뚱 베어	DIY 큐	✓
Action-contract 레지스트리 (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) 그리고 그것의 hexadecimal digest를 비교하십시오 X-OpsIQ-Signature 의 특징 hash_equals. 유효성 X-OpsIQ-Timestamp 재생 창에서 사용 X-OpsIQ-Delivery 추적 가능한 납품 식별자로.

비 교육 시도는 배경 배달 큐를 입력합니다. OpsIQ 에 대한 이야기1- 분, 5- 분, 30- 분,2- 시간 및 12- 시간 ladder는 배달 식별자를 유지하고 진단에 대한 역사를 시도.

전화 번호 JSON 직접 작용 표면, 생성 된 Postman 수집을 가져 오거나 OpenAPI 에서 클라이언트를 생성합니다. 3.0.3. PHP 참고 senders 및 Node/Python 통합 클라이언트 지원 사건과 webhook 교류; 그들은 다른 사람 보다는 오히려 도우미입니다API 계약.

사용 dry_run 생성된 계약이 그것을 지원하는 행동에, 연결관 건축업자의 경계 연결 시험을 실행하고, 그것의 생성한 파일을 검열하고, 연결관을 준비하기 전에 포장과 방출 문을 전달합니다.

설치된 릴리스는 그것의 생성 API 그리고 커넥터 계약에서 자신의 실행 시간 등록. 당신의 배포 소유의 공개 URL, 비밀, 저장 및 cron/workers, 그래서 행동은 클라우드 환경에서 가정하는 것보다 설치 된 릴리스에 대해 확인해야합니다.

연결관은 접합기를 포함하는 지배한 포장입니다, settings.json, 선택 actions.json, 생성 된 기능 계약, 문서 및 옵션 기업 확장. 여섯 단계 빌더 그것을 조립; 레지스트리 발견; 준수 및 게이트 유효성.