Платформа за разработчици · общ API · уебхукове · конектори

Направете своя платформа Управляемо от AI.

Извиквайте 2,430 именувани операции през един API, генериран от договора, с обхвати с минимални права, обвързване с работното пространство, проверка на проба и записи, безопасни при повторение. Абонирайте се за каноничните събития чрез фонови webhook с HMAC подпис или изградете управляван пакет в шестстъпковия Connector Builder.

Вземи. API ключ Прочети документите. Договор за отваряне на АПК

Ключове с обхват BearerДоговорни действия: 2,430OpenAPI 3.0.3 + _PostmanДоставка на HMAC уебхукове

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

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

Живо

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

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

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

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

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

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

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

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

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

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

01 Заявка за Bearer 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 / Подписани уебхукове

Натиснете събитията към стека си - с криптографски доказателства.

Абонирайте се с произволен URL за всяко от 53 доставяни събития. OpsIQ изпраща JSON товара чрез POST, подписан с HMAC-SHA256 върху версията на схемата, времевия печат, ID на доставката и тялото заедно, не само тялото, така че вчерашна доставка да не може да бъде повторена срещу вас днес.

Защита срещу повторениеИдентификационен код на доставката за проследяванеОтлагане на повторенията в 5 стъпки

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

проверка на уеб-кабината - 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 или генерирайте клиента, който предпочитате.

Пълният General 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 HTTPOpenAPI3.0.3Колекция от PostmanПомощници за интеграция

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

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

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

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

Шест етапа на насочванеСамоличност, Auth, Тест, Действия, Тригери и преглед поддържат пакет поколение обяснимо. Задвижвани от договорПрофилите (8) и типовете възможности (59) декларират повърхностите, които пакетът реализира. С бутален двигател с искрово запалванеПроверката за безопасност, произход и съответствие се извършва преди пакетът да бъде третиран като готов.

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

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

OpsIQ никога не изобретява правилното обаждане. Тя минава през регистрираните договори, подготвя полезния товар, иска потвърждение кога действието го изисква и произвежда пълен одитен ред, когато изпълнява, така че един AI, който може да го изпълни действие Никога не ставаш Ал, на когото не можеш да вярваш.

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

Потвърдете преди страничните ефекти. Рискови действия се появяват първо на предварителен преглед карта.

Напълно отзован. Всеки бърз, отговор и действие водят до залавяне в историята на ИИ.

Вж. схемата за действие

4 стъпкинамерение → одит

HMACПодписан преди изпълнение

Не са измислили обаждания.само регистър на договорите

Потвърденопреглед преди странични ефекти

Искане за проследяванеучастник + договор + резултат

Референтен номер

API повърхност с поглед.

Една JSON POST повърхност предоставя 2,430 именувани действия. Всеки генериран договор декларира обхватите за удостоверяване, типа четене/запис, риска, потвърждението, схемата на заявката, пробното изпълнение, идемпотентността и стабилните грешки.

OpenAPI 3.0.3 Референтен номер

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

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

ACTION tickets.replytickets.writedry_run + идемпотентностНастройване / час

ACTION security.reportsecurity.writedry_run + идемпотентностНастройване / час

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 + идемпотентностНастройване / час

ACTION hr.org.treehr.readСамо за четенеНастройване / час

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

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

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

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

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

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

2Аут. API ключ, Bearer, Basic, OAuth 2.0, HMAC или персонализиран клиент.

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

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

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

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

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

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

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

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

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

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

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

01 · Договор за конектор 2.7

Пакетът не може да претендира за възможност Кодът му не е такъв.

OpsIQ\Connectors\ConnectorContract "Откритието на времето, строителя, пакетите от първа партия, конформацията, генералът." API и всяка препратка чете, че един регистър. декларират способност и три файлове трябва да се съгласуват помежду си преди OpsIQ Насочва един ред към вас.

Фиг. 01комплект конектор, части манифест мащаб 1:1 · договор 2.7

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 доказателство за произход

Матрица на капацитета всички 59, както са записани

действия задейства webhook journey_events context guest_lookup самоличност sales sales_reconciliation плащания payments Търговия inbound_ticket outbound_reply ticket_merge ticket_custom_fields secure_details_request 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 crm 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

генерирано 32 декларативен 20 разширение 7

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

hmac-sha256 над детерминистичен полезен товар на файл SHA-256 hashes отговори е променяно от подписването на споразумението. А 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 · Съгласие

Сертифицирането е команда с код за изход.

Не е опашка за преглед, в която някой чете кода ви и си съставя мнение. Преди да изпратите, пуснете на собствената си машина същите тестови пакети, които пускаме и ние. Публикуваните JSON схеми (8) в doc/contracts/schemas/ обхващат настройки, действия, спецификации на Builder, съпоставяне на събития за пътуване и търговия, рецепти за работни процеси, договори за конектори и манифести на версиите.

manifests Сподели и се съгласи един с друг
възможности съществува в класа по време на бягане
interfaces изпълнявано, когато е декларирано
files всеки необходим файл, който е налице
действия съвпада с манифеста за действията
destructive декларация за потвърждение
самоличност стабилен външен ключ, а не електронна поща
повторение повтаряне на актуализациите, никога дублирани
предприятие декларациите съответстват на разширението
docs ПРОЧЕТЕТЕ, РАЗВИТИ, ПРОМЕНЛИВ
схеми Всеки JSON валидира

изход 0 acme: conformant against contract 2.7 Ако не успееш да назовеш чека и файла, ти ще го оправиш, не ние.

$ 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 операцията Ви

ОТМЕНЕНО

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