Udvikler platform · General API · webkroge · konnektorer

Lav din platform - Kan betjenes.

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 nøgle Læs doku menterne OpenAPI-kontrakt

Scoped Bearer nøgler2,418 contract actionsOpenAPI 3.0.3 + PostmanHMAC webhook levering

Spændt anmodning i

Underskrevet webhook ud → 200 OK

Levende

2,418Opkaldt til general API -aktioner

69Mindst-priviligerede scopes

dry_runvalidere skriftlige kontrakter før udførelse

24tsuccesfuld idempotent- write spil

Anmodningen livscyklus

- Jeg har bedt om det. Underskrevet.

PATTERSON en aktion til /api/v1.php med en scoped Bearer nøgle. OpsIQ pins arbejdsrummet, validerer den handling kontrakt og tilladelser, derefter udfører eller tør- kører det. Tegnet kanoniske begivenheder forlade gennem en HMAC-signeret levering kø med sporbare forsøg og afgrænset genveje.

HMAC- SHA256-webkroge - Indgående og udgående webhook nyttelaster er signeret over den rå krop; API opkald autentificere med en scoped Bearer nøgle.

Automatisk relæer - Fejlede leverancer tilbage off og prøve igen, med en levering ID du kan spore.

Replay- safe writers - succesfulde idempotent skriver returnere samme svar på 24 timer; samtidige duplikater dele en fordring.

01 Bærer anmodning 02 pin arbejdsområde 03 validere kontrakt 04 udføre eller tør- run 05 køens signerede begivenhed

Hurtig start

Fra nøgle til styret integration i tre trin.

Udsted en least-privilege nøgle, opdage den genererede kontrakt, tør- køre en skrive, og derefter abonnere på en webhook, når din ansøgning har brug for baggrund begivenhed levering.

KontraktkonsolForbundet

Kørdry_run → godkendt skrive, samme kontrakt

Få en nøgle

Tilmeld og generér en opfanget Beater API nøgle (opq_…) i udviklerindstillinger, og give hver integration kun de overflader, det har brug for.

Oplev & validitetName

Læs meta.actions, meta.action og meta.scopes; brug dry_run at validere skriver før henrettelse.

Kør & abonnement

Tilføj en idempotens-nøgle til skriver, og skriv derefter dit endepunkt på de kanoniske begivenheder din ansøgning har brug for.

Hvordan det passer sammen

Et stik mønster. Fem rene primitive.

Alt platform- specifikke lever i en konnektor. OpsIQ kerne forbliver generiske, AI forbliver forudsigelig, og din integration forbliver audible.

Triggere

Fortæl OpsIQ, hvad der lige skete.

Emit kanoniske begivenheder fra din platform, eller definere en styret brugerdefineret begivenhed. Abonnenter modtager begivenheden gennem den registrerede prioritet og leveringsregler.

Begivenhedsreference

Universal + brugerdefinerede begivenhederinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up eller din egen. Fanoout abonnenterAI-hjernen, automatiseringsregler, spejlkonnektorer og dine webhook endepunkter reagerer alle. Prioriteret rækkefølgeAfsendelsessystemet er deterministisk, så spejle skriver før ild.

02 / Action kontrakter

Fortælle OpsIQ hvad AI 'en har lov til at gøre.

Hver navngivet operation modtager en genereret kontrakt: omfang, funktion, læse eller skrive art, risiko, bekræftelsespolitik, anmodning og svar skema, tørrun støtte, idemagogi og stabile fejl.

Handlingsplan

AI 'en kan ikke opfinde handlingerDet kan kun bede om at køre dem, du har registreret. BekræftelsespolitikRisikaske handlinger udløser et preview-kort før nogen sideeffekt. Rolle + overfladebehandlingHver handling erklærer de roller og overflader, der tillades at køre den.

genereret aktionskontrakt · 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 / Signerede webkroge

Skub begivenheder til din stak - med kryptografisk 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.

GenafspilningsbeskyttelseSporbar leverings- ID5-step back-off

Webhook- reference

verificer 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

Brug direkte HTTP eller generere den klient, du foretrækker.

Den fulde generalAPI er offentliggjort som OpenAPI 3.0.3 og Postman. PHP reference sendere plus Node og Python integration klienter dækker signeret begivenhed og webhook strømme; enhver stak kan kalde det samme JSON aktionsoverflade direkte.

klienteksempler

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

Direkte JSON HTTPOpenAPI 3.0.3PostmansamlingIntegrationshjælpere

05 / Forbindelsesmønsteret

Byg engang, sæt dig ind i alt.

Et stik er en styret pakke genereret eller importeret gennem Identitet, Auth, Test, Handlinger, Triggers og anmeldelse. Dens manifest erklærer de kapacitetsområder OpsIQ er tilladt at afsløre.

Åbn 6-trins bygherre

Seks guidet trinIdentitet, Auth, Test, Handlinger, Triggers og anmeldelse holde pakkegenerering forklares. Kontraktdrevne8 profiles and 57 capability types declare the surfaces a package implements. RelæsvingedKontrol af sikkerhed, herkomst og overensstemmelse foretages før en pakke behandles som klar.

Fra hensigt til sikker handling

- Enkelt engelsk. - Den er færdig.

OpsIQ opfinder aldrig det rigtige opkald. Det går gennem de registrerede kontrakter, forbereder nyttelasten, beder om bekræftelse, når handlingen kræver det, og producerer en komplet revision række, når det udfører, så en AI, der kan handling bliver aldrig en AI, man ikke kan stole på.

- Kontrakt. AI 'en foreslår kun handlinger, du har registreret.

Bekræft før bivirkninger. Risikaske handlinger overflade et preview kort først.

Fuldstændig tilbagekaldelse. Hver prompt, svar og handling resultat fanget i AI Historie.

Se handlingsskemaet

4 trinintent→ revision

HMACsigneret før udførelse

Ingen opfandt opkaldKun kontraktregister

Konfirmationer- gatedforhåndsvisning før sideeffekter

Anmoder om sporskuespiller + kontrakt + resultat

Henvisning

API overflade på et blik.

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 -reference

HandlingAutorisationSkriv sikkerhedGrænse

Skriv handlingerPOST /api/v1.php · kontrakt valideret

ACTION tickets.replytickets.writedry_run + idempotensKonfiguration / time

ACTION security.reportsecurity.writedry_run + idempotensKonfiguration / time

ACTION platform.routes.writeadminbekræftelse + nøgleKonfiguration / time

Læs & opdagelseshandlingerSamme POST overflade · stabile kuverter

ACTION meta.actionsOffentlig opdagelseKun læstKonfiguration / time

ACTION tickets.listtickets.readKun læstKonfiguration / time

ACTION connectors.listconnectors.readKun læstKonfiguration / time

PeopleOS HR-aktionerKurateret hr.* kontrakter · hr.read / hr.write Scopes

ACTION hr.people.listhr.readKun læstKonfiguration / time

ACTION hr.people.createhr.writedry_run + idempotensKonfiguration / time

ACTION hr.org.treehr.readKun læstKonfiguration / time

PeopleOS HR sender ikke outbound HR webhook-begivenheder. Ræk den gennem samme POST overflade, eller abonnere på de begivenheder andre moduler publicerer. PeopleOS API og konnektorer og PeopleOS-sektionen i udviklerreferencenModulet er berettiget til at blive åbnet, så en nøgle uden hr får en afvisning, ikke en tom liste. PeopleOS HR 's virkning.

Rate grænser er konfigureret pr. nøgle på en time vindue. Responses blockage X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset; en afvist anmodning returneres 429 med Retry-After. Brug OpenAPI 3.0.3 kontrakt eller Postmansamling genereres fra de samme runtime registre.

Byg en konnektor

Byg, test og slip ind seks etaper.

Start fra en styret profil eller definer selv kontrakten. Byggeren validerer hvert trin, før den genererer en selvbehersket konnektor pakke.

1Identitet. Navn, kugle, profil og erklærede kapacitetsområder.

2- Auth. API nøgle, Beerer, Basic, OAuth 2.0, HMAC eller en brugerdefineret klient.

3Test. Validér de afgrænsede tilslutningsindstillinger før emballering.

4Handlinger. Kort navngivet operationer, parametre, rækkevidde og risiko.

5Triggers. Deklare indgående begivenheder, webkroge, meningsmåling og sync adfærd.

6Revision. Undersøg den genererede kontrakt og passere udløsningsporten.

Test før du sender

Validér sikkert, og send så udløsningsporten.

Anvendelse dry_run på understøttede skrive handlinger, køre Builder 's afgrænset forbindelse test, og inspicer den genererede manifest og kontrakt før udgivelse. Pakke validering kontrol af kapacitet navne, indstillinger, herkomst og nødvendige filer; baggrund arbejdere håndterer reaktiv polling og udgående levering.

Dry- run skriver Prøvning af boldtilslutning Kontraktoverensstemmelse Cron- drevet levering

Åbn forbindelseskonstruktør Webhook- reference

connector. php · php

klasse AcmeConnector extensions AbstractConnector { offentlig funktion kugle (): streng { Returnering "acme"; } offentlig funktion navn (): streng { Returnering 'Acme'; } offentlig funktion beskrivelse (): streng { Returnering 'Acme broge'; } / / Brug navne fra ConnectorContract offentlig funktion kapacitet (): array { Returnering ['actions', 'webhook']; } offentlig funktion settingsSchema (): array { Returnering [['key' => 'TOR', 'type' => 'password']]; } offentlig funktion testForbindelse (array $settings): array { Returnering ["Succession" => sand]; } offentlig funktion håndled Webhook ( array $payload, array $headers, array $settings ): array { Returnering ["Succession" => sand]; } }

01 · Connector contract 2.4

En pakke kan ikke kræve en kapacitet dens kode ikke har.

OpsIQ\Connectors\ConnectorContract er den myndighed. Runtime opdagelse, Builder, first-part pakker, overensstemmelse, Den generelle API og hver reference læste, at en registreringsdatabasen. Declare en evne og tre filer er nødt til at være enige med hinanden før OpsIQ ruterne en enkelt række til dig.

FIG. 01konnektor, dele manifest scale 1:1 · contract 2.4

01 connector.php klasse af køretid
02 IdentityProvider.php stabil ekstern nøgle
03 SalesIngest.php AftalSalg ()
04 actions.json navngivne operationer
05 settings.json operatørkonfiguration
06 connector_contract.json maskinlæsbar myndighed

07 signature.json én HMAC over en share-256 af hver fil ovenfor, plus et ed25519 bevis for oprindelse

Kapacitetsmatrix all 57, as registered

aktioner udløsere webhook journey_events sammenhæng guest_lookup identitet sales sales_reconciliation fakturering payments handel 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 lokal dette site_intelligence analytics comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

genereret 30 deklarativ 20 forlængelse 7

To underskrifter, to spørgsmål.

hmac-sha256 over en deterministisk nyttelast af per- fil SHA-256 hash- svar er blevet ændret siden undertegnelsen. An ed25519 signatursvar var det underskrevet af Nabtech, kan kontrolleres med den bundtede offentlige nøgle og ingen delt hemmelighed. Redigér en byte og de første stopper matchning.

marketplace.json er uden for underskriften pr. definition: installeringsprogrammet skriver det efter underskrift, så forlaget kunne aldrig have underskrevet det.

02 · værktøj /mutation_proof.php

En vagt, der aldrig har fejlet er ubevist.

De siger ikke, at den vagt, du skrev, ville stoppe det, der stod skrevet for at stoppe, fordi en vagt, som aldrig bliver udøvet, går nøjagtig som en vagt der intet gør. Så vi stopper dens hjerte med vilje og kræver, at monitoren skriger.

Oplæsningsrollen skal afvise en destruktiv operation CH1 verify_commerce_contracts

src/Connectors/CommerceRoleMapVerifier.php MUSTED

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    }

Præcis én tekstmæssig match er påkrævet. Nul kampe, eller to, og beviset stopper før det kan lyve.

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

Et mislykket bevis er Aldrig Beviser på, at en check gik galt er ikke bevis på, en vagt arbejder.

Mutationen har aldrig fundet sted.

Søgningsteksten matcher ikke, filen var uberørt, suiten passerede, og beviset er optaget grøn under den gamle kode om kode, der aldrig var gammel. Fanget ved at kræve præcis en tekstmæssig match og sammenligne fil hashes begge sider.

Mutationen ødelagde noget andet.

Suiten gik rød, fordi filen stoppede parsing eller bootstrap døde, og beviset indspillet en rød, der ikke havde noget at gøre med vagten. Fanget ved linting mutanten og kræver navngivet test blandt fejlene.

Det kan ikke efterlade en mutant på disken.

Hver mutation kopierer originalen til en sidevogn uden for webserveret træ, skriver et markør navngivning den udestående ændring, og er fortrudt af en nedlukning håndteringskanal på hver exit sti. En markør fra en styrtede løb er hædret før den næste mutation af filen.

03 · Conduct

Certificering er en kommando med en udgangskode.

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/ dække indstillinger, handlinger, Builder specs, rejse og handel begivenhed tilknytninger, workflow opskrifter, konnektor kontrakter og release manifester.

manifests parse og aftale med hinanden
kapaciteter findes på runtime klassen
interfaces gennemføres, hvis det er anmeldt
files hver krævet fil til stede
aktioner matche de handlinger manifestere
destructive Bekræft
identitet en stabil ekstern nøgle, ikke e-mail
spil igen en gentagelse af opdateringer, aldrig duplikerer
virksomhed erklæringer, der matcher forlængelsen
Dokumenter README, REYOPER, CHANGELOG
skemaer hver JSON validerer

exit 0 acme: conformant against contract 2.4 En mislykket suite giver os checken og filen.

$ 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

Punkter den første på en reel ikke-produktion konto med --live-settings=/secure/test-acme.jsonMens du stadig er iterating, byt den sidste for --unsigned-ok: det behandler en manglende underskrift som en forventet advarsel snarere end foregive, at det er fint.

04 · commerce_roles.json

Erklærer hvad du kan sælge er en fil, ikke en registrering.

En konnektor, der kan sælge erklærer, hvilken af sine egne Operationer besvarer OpsIQ 's kanoniske handelsroller. Tilstedeværelsen af filen er kravet. Det vises i salgsindstillingerne det øjeblik, den erklærer og forsvinder, når den stopper. Der er ingen liste at deltage i, og ingen at spørge.

kanonisk rolle commerce_roles.json din operation

NÆGTELSE

En kanonisk skrive rolle kortlagt til en generisk rekord skrive. Kampen er strukturel: et lagernavneord ved siden af et muterende verbum, uanset din navngivning konvention. Skrivning business række direkte springer platformens priser, tilgængelighed låsning og bekræftelse mail, og producerer en ordre handelsmandens eget system kun halvdelen tror på. recovery - Så en timeout er uinddrivelig.

commerce_roles.jsonGYLDIG

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

Dens egen fil med vilje: connector_contract.json genereres og dens skema sæt additionalProperties:false, så en håndskrevet blok der ville mislykkes validering og derefter blive overskrevet på den næste generator køre.

Lukket ordforråd

En rolle, der ikke CommerceRole findes ikke. OpsIQ udleder aldrig en fra et operations navn, fordi et navn ikke er et løfte.

Din egen handling

Operationen skal vises i din actions.jsonAt erklære en, der ikke eksisterer, lover kunden noget, som så ikke producerer noget.

Skrifter erklærer inddrivelse

Den farligste timeout er den, efter at platformen kan allerede har gjort arbejdet. Uden en idempotent "gjorde min skrive land" opslag, de eneste muligheder er prøve blind eller miste ordren.

Betalingsroller attesterer

Enhver betalings- klasse rolle også erklærer payment_profile med miljø, webhook_verify ved hjælp af udbyderens egen ordning, og event_map. Et uangivet miljø er, hvordan en test- mode udbyder tager en live betaling.

Builder validerer disse som du skriver og verifikatoren validerer den leverede pakke. Begge kalder de samme funktioner, så de kan ikke være uenige.

⚖️ Hvordan det sammenligner

OpsIQ vs en Det er en integration.

Hvilket kontraktbundet, underskrevet, revideret platform giver dig, at rullende dine egne webkroge og AI- action VVS aldrig vil.

Kapacitet	Rul din egen	OpsIQ
Scoped Beater API + HMAC- signerede webkroge	Håndvalset	✓
Dry- run skriver + 24- time succesfuld spil	Det gør jeg.	✓
1m → 5m → 30m →2h → 12h Retues	DIY kø	✓
Action- contract register (AI kan ikke opfinde opkald)	—	✓
Bekræftelsespolitik før bivirkninger	—	✓
Stabil fejlkonvolut + anmodningsID	Manuel logning	✓
Direkte HTTP + genererede klientindstillinger	Skriv dine egne	✓
OpenAPI 3.0.3 maskinlæsbar kontrakt	Måske.	✓
Six- stage Builder + pakke release gate	Opbygge en værktøjskæde	✓
Arbejdsrumstaster og timegrænser	Varers	✓
Forbindelsesmønster: platformkode forbliver isoleret	—	✓

Ofte stillede spørgsmål

Udvikler spørgsmål, Det er ikke det, jeg vil sige.

Autentificering, kontrakter, genforsøg, kundegenerering, sikker prøvning og stikkontakt model, før den første produktionsanmodning.

Generelt API opkald sende Authorization: Bearer opq_…. Nøgler kan være ubegrænset, begrænset eller read- only, bære mindst-priviligation scope, adlyde en time grænse og kan fastgøres til et arbejdsområde. Webhook signering er separat: udgående leverancer carry X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event og X-OpsIQ-Delivery.

Nej. AI kan kun foreslå navngivne operationer i handlingsregistret. Hver genereret kontrakt erklærer omfang, forespørgselsfelter, risiko og bekræftelsespolitik; operationer hvis politik kræver bekræftelse overflade en menneskelig forhåndsvisning før udførelse.

Genopput hash_hmac('sha256', $rawBody, $secret) og sammenligne sin hexadecimal digest med X-OpsIQ-Signature brug hash_equals. Validér X-OpsIQ-Timestamp inden for dit genafspilningsvindue og brug X-OpsIQ-Delivery som identifikatoren for den sporbare levering.

Et ikke-vellykket forsøg ind i baggrunden levering kø. OpsIQ forsøger igen på1- minut, 5- minut, 30- minut,2- time og 12-time stigen, mens du bevarer leveringsdato og forsøge historie for diagnostik.

Ring til JSON action overflade direkte, importere den genererede Postman samling, eller generere en klient fra OpenAPI 3.0.3. PHP reference sendere og Node / Python integration klienter støtte begivenhed og webhook strømme; de er hjælpere snarere end separateAPI kontrakter.

Anvendelse dry_run på handlinger, hvis genereret kontrakt understøtter det, køre Connector Builder 's afgrænset forbindelse test, inspicere sine genererede filer, og passere pakken overensstemmelse og frigive gates før behandling af stikket som klar.

Den installerede udgivelse genererer sine API og konnektor kontrakter fra sine egne runtime registre. Din implementering ejer sin offentlige URL, hemmeligheder, opbevaring og cron / arbejdstagere, så adfærd bør verificeres mod den installerede udgivelse snarere end antages fra et cloud-miljø.

En konnektor er en reguleret pakke, der indeholder adapteren settings.json, fakultativ actions.json, en genereret kapacitet kontrakt, dokumentation og valgfri enterprise udvidelser. Den seks- trins Builder samler det; registret opdager det; overensstemmelse og frigivelse gates validere det.