Utvecklarplattform · Allmänt API · webhooks · kontakter

Gör din plattform AI-operativ.

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.

Få en API nyckel Läs docs OpenAPI-kontrakt

Scoped Bearer Keys2,418 contract actionsOpenAPI 3.0.3+ PostmanHMAC webhook leverans

Skopad begäran i

Signerad webhook out → 200 OK

Livet Live

2,418Allmänt API åtgärder

69Minstprivilege Omfattningar

dry_runvalidera skrivkontrakt innan verkställighet

24h_framgångsrik idempotent-write replay

Förfrågan livscykel

Scoped request in. Signerad händelse ut.

POST en åtgärd för /api/v1.php med en omfångad Bearer-nyckel OpsIQ Pinnar arbetsytan, validerar åtgärdsavtalet och behörigheterna, utför sedan eller torr kör det. Abonnerade kanoniska händelser lämnar genom en HMAC-signerad leveranskö med spårbara försök och bundna retries.

HMAC-SHA256-webhooks - Inkommande och utgående webhook nyttolaster är signerade över den råa kroppen; API samtal autentisera med en omfattad bärare nyckel.

Automatiska retries - misslyckade leveranser tillbaka och retry, med ett leverans-ID kan du spåra.

Replay-safe skriver - framgångsrika idempotent skriver returnerar samma svar för 24 timmar; samtidiga dubbletter delar ett krav.

01 Bearer request 02 Pin Workspace 03 validera avtal 04 Utför eller torr kör 05 Kö undertecknad händelse

Snabbstart

Från nyckel till styrd integration i tre steg.

Utfärda en minsta-privilege nyckel, upptäcka det genererade kontraktet, torr kör en skriv, sedan prenumerera en webhook när din ansökan behöver bakgrund händelse leverans.

Kontrakt konsolAnsluten

Utförligtor_run → godkänt skriv, samma kontrakt

Få en nyckel

Registrera dig och skapa en omfångad Bearer API -nyckel (opq_…) i utvecklarinställningar och ge varje integration endast de ytor den behöver.

Upptäck och validera

Läs mer meta.actions, meta.action och meta.scopesAnvänd dry_run för att validera skrifter före avrättning.

Utför & prenumerera

Lägg till en idempotensnyckel för skriv, prenumerera sedan på slutpunkten till de kanoniska händelser som din ansökan behöver.

Hur det passar ihop

Ett kontaktmönster. Fem rena primitiva.

Allt plattformsspecifikt lever i en kontakt. OpsIQ Kärnan förblir generisk, AI förblir förutsägbar, och din integration förblir revisionsbar.

Utlösare

Berätta OpsIQ vad som just hände.

Emit kanoniska händelser från din plattform, eller definiera en styrd anpassad händelse. Abonnenter får evenemanget genom den registrerade prioritet och leveransregler.

Event referens

Universal + anpassade händelserinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up eller din egen. Fan-out abonnenterAI-hjärnan, automationsreglerna, spegelkontakterna och din webhook slutpunkter alla reagerar. Prioriterad orderDeterministisk avsändning så speglar skriver innan varningar brand.

02 / Åtgärdsavtal

Berätta OpsIQ vad AI är tillåtet att göra.

Varje namngiven operation får ett genererat kontrakt: omfattning, funktion, läs eller skriv typ, risk, bekräftelsepolicy, begäran och svarsschema, torrstöd, idempotens och stabila fel.

Åtgärdsschema

AI kan inte uppfinna åtgärderDet kan bara be att köra de du har registrerat. BekräftelsepolicyRisky-handlingar utlöser ett förhandsgranskningskort innan någon bieffekt. Role + ytbeläggningVarje handling förklarar roller och ytor som tillåts att köra den.

genererat åtgärdsavtal · 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 / Signerade webhooks

Tryck på händelser till din stack - med kryptografiska bevis.

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 skyddSpårbar leverans ID5-step back-off

Webhook referens

Verifiera 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:er

Använd direkt HTTP eller skapa den klient du föredrar.

Full GeneralAPI publiceras som OpenAPI 3.0.3 och Postman. PHP-referenssändare plus Node and Python integrationskunder täcker signerade händelse- och webhookflöden; varje stack kan kalla samma JSON Åtgärd yta direkt.

Kundexempel

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.",
    },
)

Direkt JSON HTTPOpenAPI 3.0.3_Postman collectionIntegrationshjälpare

05 _/ Anslutningsmönstret

Bygg en gång. Anslut till allt.

En kontakt är ett styrt paket som genereras eller importeras genom identitet, Auth, Test, Åtgärder, Triggers och Review. Dess manifest förklarar förmågans ytor OpsIQ Tillåts att exponera.

Öppna sexstegsbyggaren

Sex styrda stadierIdentitet, Auth, Test, Åtgärder, Triggers och Review håller paketgenerering förklaras. Kontraktsdriven8 profiles and 57 capability types declare the surfaces a package implements. Release-gatedSäkerhet, provenans och kontroller överensstämmelse löper innan ett paket behandlas som klart.

Från avsikt till säker åtgärd

Smärta engelska i. Auditerad operation ute.

OpsIQ uppfinner aldrig rätt samtal. Det går genom de registrerade kontrakten, förbereder nyttolast, ber om bekräftelse när åtgärden kräver det och producerar en fullständig revisionsrad när den utför, så ett AI som kan Handling Aldrig blir ett AI du inte kan lita på.

Kontraktsbunden. AI föreslår bara åtgärder du har registrerat.

Bekräfta före biverkningar. Risky-handlingar visar ett förhandsgranskningskort först.

Total återkallelse. Varje snabb, svar och handling resulterar i AI History.

Se handlingsschemat

4 stegAvsikt → revision

HMAC_undertecknad innan avrättning

Inga uppfunna samtalKontraktsregistret endast

Bekräftelse-GatedFörhandsgranskning före biverkningar

Begär spårSkådespelare + kontrakt + resultat

Hänvisning

API yta vid en blick.

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 referens

ÅtgärderAutentiseringSkriv säkerhetBegränsning

Skriva handlingarPOST /api/v1.php · Kontrakt validerat

ACTION tickets.replytickets.writetor_run + idempotensKonfigurerad / timme

ACTION security.reportsecurity.writetor_run + idempotensKonfigurerad / timme

ACTION platform.routes.writeAdminBekräftelse + NyckelKonfigurerad / timme

Läs & upptäckt åtgärderSamma POST-yta · stabila kuvert

ACTION meta.actionsOffentlig upptäcktLäs endastKonfigurerad / timme

ACTION tickets.listtickets.readLäs endastKonfigurerad / timme

ACTION connectors.listconnectors.readLäs endastKonfigurerad / timme

PeopleOS HR-åtgärderCurated hr.* Kontrakt · hr.read / hr.write Omfattningar

ACTION hr.people.listhr.readLäs endastKonfigurerad / timme

ACTION hr.people.createhr.writetor_run + idempotensKonfigurerad / timme

ACTION hr.org.treehr.readLäs endastKonfigurerad / timme

PeopleOS HR skickar inte utgående HR-webbhook-evenemang. Nå det genom samma POST-yta eller prenumerera på de händelser som andra moduler publicerar. Full referens: PeopleOSAPIoch connectors och PeopleOS-delen av utvecklarens referensmodulen är rätt till gated, så en nyckel utan hr Får en vägran, inte en tom lista. Vad PeopleOS HR är.

Betygsgränser är konfigurerade per nyckel på ett timfönster. Responses exponerar X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reseten förkastad begäran återkommer 429 med Retry-AfterAnvända OpenAPI 3.0.3 kontrakt eller Postman collection genereras från samma löptidsregister.

Bygg en kontakt

Bygg, testa och släppa i sex steg.

Börja från en styrd profil eller definiera kontraktet själv. Byggaren validerar varje steg innan den genererar ett fristående kontaktpaket.

1Identitet. Namn, snigel, profil och deklarerade förmåga ytor.

2Auth. API Nyckeln, Bearer, Basic OAuth 2.0 HMAC eller en anpassad kund.

3Test. Validera de gränsade anslutningsinställningarna före förpackningen.

4Åtgärder. Karta med namngivna operationer, parametrar, omfattningar och risk.

5Triggers. Förklara inkommande händelser, webhooks, polling och synkronisera beteende.

6Granska. Inspektera det genererade kontraktet och skicka släppporten.

Testa innan du skickar

Validera säkert, sedan passera släppporten.

Användning dry_run på stödda skrivåtgärder, köra byggarens gränsade anslutningstest och inspektera det genererade manifestet och kontraktet innan release. Förpackningsvalidering kontrollerar kapacitetsnamn, inställningar, beprövning och nödvändiga filer; bakgrundsarbetare hanterar reaktiv omröstning och utgående leverans.

Dry-run skriver Bundat anslutningstest Kontraktsöverensstämmelse Cron-driven leverans

Open Connector Builder Webhook referens

connector. php · php

klassklass klass AcmeConnector Förlängningar AbstractConnector { Offentlig funktion Släkt(): Sträng { returnera "Acme"; } Offentlig funktion Namn(): Sträng { returnera "Acme"; } Offentlig funktion Beskrivning(): Sträng { returnera "Acme bridge"; } // Använd namn från ConnectorContract Offentlig funktion Förmågor(): array { returnera ["Actions", "webhook"]; } Offentlig funktion InställningarSchema(): array { returnera [["Key" => "token", "typ" => "lösenord"]]; } Offentlig funktion TestConnection(array $settings): array { returnera [Framgång » => sant]; } Offentlig funktion hanteraWebhook( array $payload, array $headers, array $settings ): array { returnera [Framgång » => sant]; } }

01 · Connector contract 2.4

Ett paket kan inte göra anspråk på en förmåga dess kod har inte.

OpsIQ\Connectors\ConnectorContract är myndigheten. Runtime-upptäckten, Builder, förstapartspaket, överensstämmelse, General API och varje referens läser att ett register. Deklarera en förmåga och tre filer måste komma överens med varandra innan OpsIQ sträcker en enda rad till dig.

FIG. 01_Anslutningspaket, delar manifest scale 1:1 · contract 2.4

01 connector.php Rörelsetidsklassen
02 IdentityProvider.php Stabil extern nyckel
03 SalesIngest.php ReconcileSales()
04 actions.json namngivna operationer
05 settings.json operatörskonfiguration
06 connector_contract.json maskinläsbar myndighet

07 signature.json en HMAC över en SHA-256 av varje fil ovan, plus ett ed25519 ursprungsbevis

Förmåga matrix all 57, as registered

Åtgärder utlösare Webhook journey_events sammanhanget guest_lookup identitet sales sales_reconciliation fakturering payments Handels 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 crm_ block_registry inbound_comment outbound_note outbound_notification oauth reviews lokalt Seo site_intelligence Analytics comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

genererad 30 deklarativt 20 Förlängning 7

Två signaturer, två frågor.

hmac-sha256 över en deterministisk nyttolast av per-fil SHA-256 hashes svar har detta ändrats sedan undertecknandet. en ed25519 signatur svar var den signerad av NabtechKontrollera med den buntade offentliga nyckeln och ingen delad hemlighet. Redigera en byte och de första stopp matchning.

marketplace.json är utanför signaturen per definition: installationsprogrammet skriver det efter signering, så förlaget kunde aldrig ha undertecknat den.

02 · verktyg/mutation_proof. php

En vakt som aldrig misslyckats är obevisad.

Gröna tester säger att ingenting bröt idag. De berättar inte för dig den vakt du skrev skulle stoppa det som det var skrivet att sluta, eftersom en vakt som aldrig utövas passerar precis som en vak som gör ingenting. Så vi stoppar sitt hjärta på avsikt och kräver att bildskärmen skriker.

Värd · Läs rollen måste vägra en destruktiv operation CH1 verify_commerce_contracts

src/Connectors/CommerceRoleMapVerifier.php MUTATED

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    }

Exakt En text match krävs. Zero matcher, eller två, och beviset stannar innan det kan ligga.

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

Ett misslyckat bevis är never Bevis på att en check gick fel är inte bevis för att en vakt fungerar.

Mutationen tillämpades aldrig.

Söktexten matchade inte, filen var orörd, sviten passerade och beviset inspelad. grönt under den gamla koden om kod som aldrig var gammal. fångad genom att kräva exakt en textmatch och jämföra filhasar endera sidan.

Mutationen bröt något annat.

Suite gick rött eftersom filen slutade parsing eller bootstrap dog, och beviset spelade in en röd som inte hade något att göra med vakten. fångad genom att luta mutanten och kräver att den kräver att vakt. Namnet namn test bland misslyckanden.

Det kan inte lämna en mutant på disken.

Varje mutation kopierar originalet till en sidovagn utanför det webb-serverade trädet, skriver en markör som namnger den enastående förändringen och är ogjord av en nedstängningshanterare på varje utgångsväg. En markör från en kraschad körning hedras före nästa mutering av filen.

03 · Överensstämmelse

Certifiering är ett kommando med en exit-kod.

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/ täcka inställningar, åtgärder, Builder specs, resa och handel händelse kartläggningar, arbetsflöde recept, kontaktkontrakt och frigör manifest.

manifests församling och enas med varandra
Förmågor existerar på runtime-klassen
interfaces genomförd där de förklarats
files varje obligatorisk fil närvarande
Åtgärder matcha handlingarna manifest
destructive Förklaring om bekräftelse
identitet en stabil extern nyckel, inte e-post
Replay En upprepad uppdatering, aldrig duplicerar
Företag Förklaringar matchar förlängningen
Docs LÄS MED DEVELOPER, CHANGELOG
scheman Alla JSON validerar

exit 0_ acme: conformant against contract 2.4 En felaktig svit namn checken och filen. Du fixar det, inte oss.

$ 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

Peka den första på ett verkligt icke-produktionskonto med --live-settings=/secure/test-acme.jsonMedan du fortfarande itererar, byta den sista för att --unsigned-okDet behandlar en saknad signatur som en förväntad varning snarare än låtsas att det är bra.

04 · commerce_roles.json

Förklara vad du kan sälja är en fil, inte en registrering.

En kontakt som kan sälja deklarerar vilken av sin egen operationer svarar OpsIQs kanoniska handel roller. Närvaron av filen är påståendet. Det verkar i säljinställningarna när det förklarar och försvinner när den slutar. Det finns ingen lista att gå med och ingen att fråga.

Kanonisk roll commerce_roles.json Din operation

Återanvändning

En kanonisk Skriv skrivande roll kartlagd till en generisk rekordskrivare. Matchen är strukturell: ett lagringsbrev bredvid ett muterande verb, oavsett din namnkonvention. Skriva affärsraden direkt hoppar plattformens prissättning, tillgänglighet låsning och bekräftelse post, och ger en order köpmannens eget system bara hälften tror på. recovery Så en timeout skulle vara oåterkallelig.

commerce_roles.jsonValid

{
  "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" }
    }
  }
}

Dess egen fil på ändamål: connector_contract.json genereras och dess schemauppsättningar additionalProperties:falseSå ett hand-auktorierat block skulle det inte vara validering och sedan skrivas över på nästa generatorkörning.

Stängt ordförråd

En roll inte i CommerceRole Det finns inte. OpsIQ sluter aldrig ett från ett operationsnamn, eftersom ett namn inte är ett löfte.

Din egen handling

Operationen måste visas i din actions.jsonAtt förklara en som inte existerar lovar kunden något som sedan producerar ingenting.

Skrifter förklarar återhämtning

Den farligaste timeouten är den efter att plattformen redan har gjort jobbet. Utan en idempotent "did my write land" -uppslag, de enda alternativen är förblindade eller förlora ordern.

Betalningsroller certifiera

Alla betalningsklass roll förklarar också payment_profile med Miljö, webhook_verify använda leverantörens eget system, och event_mapEn ostatlig miljö är hur en testlägeleverantör tar en levande betalning.

Byggaren validerar dessa när du skriver och verifiern bekräftar det skeppade paketet. Båda kallar samma funktioner, så att de inte kan hålla med om det.

⚖️ Hur det jämför

OpsIQvs a Gör det själv-integration.

Vilken kontraktsbunden, undertecknad, granskad plattform ger dig som rullar dina egna webhooks och AI-action VVS aldrig kommer att.

Förmåga	Rulla din egen	OpsIQ_
Scoped Bearer API HMAC-signerade webhooks	Hand-rolled	✓
Dry-run skriver + 24-timme framgångsrikt replay	DIY	✓
1m→5m→30m→ 2h → 12hRetries	DIY queue	✓
Action-contract registry (AI kan inte uppfinna samtal)	—	✓
Bekräftelsepolicy före biverkningar	—	✓
Stabil felkuvert + begäran ID	Manuell loggning	✓
Direct HTTP + genererade kundalternativ	Skriv din egen	✓
OpenAPI 3.0.3 maskinläsbart kontrakt	Maybe	✓
Six-steage Builder + paket release gate	Bygg en verktygskedja	✓
Workspace-pinned nycklar och timgränser	Varierar	✓
Anslutningsmönster: plattformskoden förblir isolerad	—	✓

Vanliga frågor och svar

Utveckla frågor, Svarat.

Autentisering, kontrakt, retries, klientgenerering, säker testning och kontaktmodellen före den första produktionsförfrågan.

Allmänt API samtal skicka Authorization: Bearer opq_…Nycklar kan vara obegränsade, begränsade eller lättlästa, bära minsta möjliga utrymmen, lyda en timmes gräns och kan fästas på ett arbetsyta. Webhook signing är separat: utgående leveranser bär X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event och X-OpsIQ-Delivery.

Nej. AI kan endast föreslå namngivna operationer i handlingsregistret. Varje genererat kontrakt förklarar omfattning, begära fält, risk- och bekräftelsepolicy; verksamhet vars policy kräver bekryftelse ytan en mänsklig förhandsgranskning innan verkställigheten utförs.

Rekommenderas hash_hmac('sha256', $rawBody, $secret) och jämföra dess hexadecimal smält med X-OpsIQ-Signature Använda hash_equalsValidate X-OpsIQ-Timestamp inom ditt replay-fönster och användning X-OpsIQ-Delivery som spårbar leveransidentifierare.

Ett icke-framgångsrikt försök går in i bakgrunden leveranskö. OpsIQ Retries på1Minut, 5Minut, 30 Minut,2timme och 12-timmestege medan du behåller leveransidentifieraren och försökshistorik för diagnostik.

Ringa till JSON åtgärd yta direkt, importera den genererade Postman-kollektionen eller skapa en klient från OpenAPI 3.0.3 PHP-referenssändare och Node/Python-integrationskunder stöder evenemang och webhookflöden; de är hjälpare snarare än separataAPI Kontrakt.

Användning dry_run på åtgärder vars genererade kontrakt stöder det, kör Connector Builders gränsade anslutningstest, inspektera dess genererade filer och passera paketets överensstämmelse och släppa grindar innan du behandlar kontakten som redo.

Den installerade versionen genererar dess API och kontaktkontrakt från sina egna drifttidsregistren. Din utplacering äger sin publik URL Hemligheter, lagring och krön/arbetare, så beteendet bör verifieras mot den installerade frisättningen snarare än antaget från en molnmiljö.

En kontakt är ett styrt paket som innehåller adaptern, settings.json, valfritt actions.json, ett genererat kapacitetskontrakt, dokumentation och valfria företagstillägg. Den sexstegsbyggare monterar den; registret upptäcker det; överensstämmelse och frigör grindar validera den.