Developer platform · General API · webhooks · connectors

Направете своя платформа - Може да се оперира.

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 ключ Прочети документите. Договор за отваряне на АПК

Ключове за мерници2,418 contract actionsOpenAPI 3.0.3 + ПощальонHMAC уеб-касина доставка

Обхват на искането в

Подписано уебкасетофон → 200 OK

Живо

2,418Име на генерала API действия

69най-малко за целите на наказателното правораздаване

dry_runда валидира договорите за записване преди изпълнението

24hуспешно възпроизвеждане на идмопотентния запис

Искане за жизнен цикъл

Включена е заявка. Подписан случай.

POST действие за /api/v1.php с оптичен ключ на Мечока. OpsIQ Закопчава работното пространство, утвърждава договора за действие и разрешенията, след което го изпълнява или изсушава HMAC-подписано доставка опашка с проследими опити и ограничени ретрита.

HMAC- SHA256 webhooks - входящи и изходящи полезни товари са подписани върху сурово тяло; API призовава за удостоверяване с стъклен ключ.

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

Записи за повторно възпроизвеждане - успешни idempotent пише връщане на същия отговор за 24 часа; едновременни дубликати споделят едно вземане.

01 Искане за отговор 02 Работно пространство на пиновете 03 удостоверен договор 04 изпълнява или изсушава 05 Подписано събитие на опашката

Бързо стартиране

От ключ към регламентирана интеграция в три стъпки.

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

Конзола на договораСвързва се

Изпълнениесух_ run → одобрен запис, същия договор

Вземи ключ.

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

& Откриване и утвърждаване

Четене meta.actions, meta.action както и meta.scopes; употреба dry_run да валидирате писанията преди екзекуцията.

Изпълнение на & абониране

Добавяне на ключ за нежеланост за писане, след това абонирайте крайната си точка за канонични събития, които трябва да кандидатствате.

Как се връзват

Един конектор. Пет чисти примитивни.

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

Тригери

Кажи. OpsIQ какво се случи току що.

Излъчвайте канонични събития от вашата платформа или дефинирайте регулирано по поръчка събитие. Абонатите получават събитието чрез регистрираните правила за приоритет и доставка.

Справка за събитието

Универсални + потребителски събитияinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up или твоя собствена. Абонати за развлекателни програмиAI мозъка, правилата за автоматизация, огледалните конектори и вашите уеб-кабини всички реагират. Приоритетно нарежданеОгледалата пишат преди да се разпалят.

02 / Договори за действие

Кажи. OpsIQ какво може да прави Ал.

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

Екшън схема

AI не може да изобрети действияМоже да поиска само да проверите тези, които сте регистрирали. Политика за потвърждениеРискови действия предизвикват преглед на картата преди всеки страничен ефект. Роля + повърхностен сглобяванеВсяко действие декларира ролите и повърхностите, които са му позволени да изпълнява.

генериран договор за действие · 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 / Signed 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.

Защита срещу повторениеИдентификационен код на доставката за проследяване5-step back-off

Справочник на уебкок

проверка на уеб-кабината - 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 интеграция клиенти обхващат подписано събитие и 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 HTTPOpenAPI3.0.3Пощенска колекцияПомощници за интеграция

05 / Конекторът модел

Включи всичко.

Конекторът е управляван пакет, генериран или внесен чрез идентичност, Auth, Тест, Действия, Тригери и преглед OpsIQ е позволено да се изложи.

Отвори шестетапния строител.

Шест етапа на насочванеСамоличност, Auth, Тест, Действия, Тригери и преглед поддържат пакет поколение обяснимо. Задвижвани от договор8 profiles and 57 capability types declare the surfaces a package implements. С бутален двигател с искрово запалванеПроверката за безопасност, произход и съответствие се извършва преди пакетът да бъде третиран като готов.

От намерение за безопасна работа

Влизаме на английски. Проверката приключи.

OpsIQ никога не изобретява правилното обаждане. Тя минава през регистрираните договори, подготвя полезния товар, иска потвърждение кога действието го изисква и произвежда пълен одитен ред, когато изпълнява, така че един 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 Референтен номер

ДействиеУдостоверяванеБезопасност при писанеГраници

Запис на действияПост /api/v1.php · валидиран договор

ACTION tickets.replytickets.writedry_run + idempotentityНастройване / час

ACTION security.reportsecurity.writedry_run + idempotentityНастройване / час

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

& Действия за четенеСъщата повърхност на 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.writedry_run + idempotentityНастройване / час

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. Използвайте Отворен API 3.0.3 договор или Пощенска колекция генериран от същите регистри за движение.

Изграждане на конектор

Изграждане, изпитване и освобождаване в Шест етапа.

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

1Самоличност. Име, плужек, профил и обявени повърхности на способностите.

2Аут. API Ключ, Беърър, Бейс, OAuth 2.0, HMAC или клиент по поръчка.

3Тест. Валидирайте ограничените настройки на връзката преди опаковката.

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

5Спусъци. Обявяване на входящи събития, уеб-хукове, анкети и синхрон поведение.

6Преглед. Проверете генерирания договор и преминете през изхода на освобождаването.

Тествайте преди да сте кораб

Потвърди безопасно, след това мини през вратата.

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

Сухи надписи Изпитване за свързване с облицовка Съответствие на договора Доставката с cron-driver

Отваряне на конектора Справочник на уебкок

конектор. php · php

клас AcmeConnector Разширяване AbstractConnector { Публична функция implate (=): низ { връщане "акме"; } Публична функция Име(): низ { връщане "Акме"; } Публична функция описание [6]: низ { връщане Мост на акме; } / / Използване на имена от Connector договор Публична функция възможности(): масив { връщане ["Действия", 'webhook']; } Публична функция settingsSchema(): масив { връщане [["Ключ" => "Токен", "тип" => "Парола"]]; } Публична функция Изпитване на контакта [6]масив $settings): масив { връщане ["успех" => Вярно е.]; } Публична функция дръжка Webhook [6] масив $payload, масив $headers, масив $settings ): масив { връщане ["успех" => Вярно е.]; } }

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 съвместяване на продажбите()
04 actions.json име на операциите
05 settings.json конфигурация на оператора
06 connector_contract.json орган, който чете машини

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

Матрица на капацитета all 57, as registered

действия задейства webhock 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 crum 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 hashes отговори е променяно от подписването на споразумението. An ed25519 отговори на подписа Беше ли подписано от Nabtech, проверява се с пакетирания публичен ключ и не споделя тайна. Редактиране на един байт и първата спира съвпадението.

marketplace.json е извън подписа по дефиниция: инсталаторът го пише след подписването, така че издателят никога не би могъл да го подпише.

02 · инструменти/mutation_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.

Неуспешно доказателство е Никога Доказателството, че е сбъркал чека не е доказателство, че пазачът работи.

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

Текстът на търсенето не съвпада, файлът е недокоснат, апартаментът е приет и доказателството записано зелено под стария код За код, който никога не е бил стар. Хванат чрез изисква точно един текстов мач и сравняване на файл hashes от двете страни.

Мутацията счупи нещо друго.

Апартаментът се е зачервил, защото файлът е спрял да се анализира или капана за ботушите е умрял и доказателството е записано в червено, което няма нищо общо с пазача. Име тест сред неуспехите.

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

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

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/ обхваща настройки, действия, Builder спецификации, пътуване и търговски събития mappings, рецепти за работния процес, договори за конектори и освобождаване манифести.

manifests Сподели и се съгласи един с друг
възможности съществува в класа по време на бягане
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 · Търговия с роли.json

Обявявам какво можете да продадете. е файл, не регистрация.

Конектор, който може да продава декларира кой от Собствена Отговор на операциите OpsIQ_ каноничните търговски роли. Присъствието на файла е претенцията. Тя се появява в настройките за продажба в момента, в който декларира и изчезва, когато тя спре. Няма списък, към който да се присъедините и никой да поиска.

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

ОТМЕНЕНО

Каноникал weather forecast ролева карта на запис. Мачът е структуриран: съществително устройство за съхранение освен мутирал глагол, независимо от това, че сте се събрали на него. Писането на бизнес ред директно пропуска ценообразуването на платформата, заключване на наличността и потвърждение поща, и произвежда поръчка на собствената система търговец само половината вярва в. Не 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 интеграция.

Каква свързана с договора, подписана, одитирана платформа ви дава възможност да се въргаляте в собствените си уеб-hooks и AI-action водопровод никога няма да.

Възможност	Снимайте си сам.	OpsIQ
Scoped Bearer API + HMAC-signed webhooks	С дебелина, превишаваща 0,10 mm	✓
Сухата писмена версия пише + 24-часово успешно повторение	ДИЙ	✓
1m → 5m → 30 m → 2h → 12h Възвръщания	DIY опашка	✓
Регистър на договорите за действие (AI не може да изобрети повиквания)	—	✓
Политика за потвърждение преди странични ефекти	—	✓
Стабилна опаковка за грешка + заявки за самоличност	Ръчна сеч	✓
Директни HTTP + генерирани опции на клиенти	Напиши си сам.	✓
OpenAPI 3.0.3 договор за машинно четене	Може би.	✓
Шестетапен строител + пакетна врата	Изграждане на инструментна верига	✓
Ключове с вързано работно пространство и почасови ограничения	Различно	✓
Конекторен модел: кодът на платформата остава изолиран	—	✓

Често задавани въпроси

Разработчиците задават въпроси. Отговори.

Автентичност, договори, ретрити, клиентско поколение, безопасно тестване и конектор модел, преди първото искане за производство.

Общи положения API Изпратени обаждания Authorization: Bearer opq_…. Ключовете могат да бъдат неограничени, ограничени или само за четене, да носят най-малко privilege оптическите възможности, да се подчиняват на един час лимит и може да бъде прикачен към работно пространство. X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event както и X-OpsIQ-Delivery.

Не. AI може да предлага само посочени операции в регистъра за действие. Всеки генериран договор декларира обхват, искания полета, риск и политика на потвърждение; операции, чиято политика изисква потвърждаване се появяват човешко преглед преди изпълнението.

Повторение hash_hmac('sha256', $rawBody, $secret) и да сравните шестопръстното му храносмилане с X-OpsIQ-Signature (800 mg / дневно) 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/workers, така че поведението трябва да бъде проверено срещу инсталираното освобождаване, вместо да се приема от облачна среда.

Конекторът е управляван пакет, съдържащ адаптера. settings.json, по избор actions.jsonШестетапният строител го сглобява; регистърът го открива; конформността и освобождава портите го утвърждават.