Piattaforma di sviluppo · Generale API · webhooks · connettori

Fai la tua piattaforma AI-operabile.

Call 2,415 named operations through one contract-generated API, with least-privilege scopes, workspace pinning, dry-run validation and replay-safe writes. Subscribe to canonical events through HMAC-signed background webhooks, or build a governed package in the six-stage Connector Builder.

Prendi una API chiave Leggi i documenti Contratto OpenAPI

Tasti del cuscinetto scoppiato2,415 contract actionsAprire l'API 3.0.3 + PostmanHMAC webhook consegna

Richiesta scomposta in

Firmato webhook out → 200 Ok.

Vivi

2,415nominato Generale API azioni

69obiettivi meno privati

dry_runconvalidare i contratti di scrittura prima dell'esecuzione

24hriproduzione di scrittura idempotent

Il ciclo di vita della richiesta

Ho ricevuto una richiesta. E' un evento firmato.

POST a un'azione /api/v1.php con una chiave per Bearer.OpsIQpins lo spazio di lavoro, convalida il contratto d'azione e le autorizzazioni, quindi lo esegue o la gestisce a secco.HMAC-segnata la coda di consegna con tentativi rintracciabili e ritiri legati.

Webhooks HMAC-SHA256 - i carichi di pagamento in entrata e in uscita webhook sono firmati sopra il corpo grezzo; API chiama autentica con una chiave di Bearer a portata di mano.

Ritmo automatico - le consegne fallite e riprovano, con un documento di consegna che puoi rintracciare.

Scrive di riproduzione-sicuro - gli scritti idempotent di successo restituiscono la stessa risposta per le ore 24; i duplicati concomitanti condividono una richiesta.

01 Richiesta del cuscinetto 02 spazio di lavoro perno 03 convalidare il contratto 04 eseguire o a secco 05 coda evento firmato

Avvio rapido

Dalla chiave all'integrazione governata tre passi.

Emettere una chiave meno-privilegia, scoprire il contratto generato, a secco-run un scrittura, quindi sottoscrivere un webhook quando la vostra applicazione ha bisogno di consegna evento sfondo.

Console di contrattoCollegato

Esecuzionedry_run → scritto approvato, stesso contratto

Prendi una chiave

Registrati e genera un Bearer di portata API key (opq_…) nelle impostazioni dello sviluppatore, e dare ogni integrazione solo le superfici di cui ha bisogno.

Scopri e valida

Leggi meta.actions, meta.action e meta.scopes; uso dry_run per convalidare le scritture prima dell'esecuzione.

Esecuzione e abbonamenti

Aggiungi una chiave di idempotency per le scritture, quindi abbona il tuo endpoint agli eventi canonici che la tua applicazione ha bisogno.

Come si adatta insieme

Un modello di connettore. Cinque primitivi puliti.

Qualsiasi piattaforma-specifica vive in un connettore. Il core OpsIQ rimane generico, l'intelligenza artificiale rimane prevedibile e la tua integrazione resta verificabile.

Trigger

Dillo. OpsIQ quello che e' appena successo.

Emettere eventi canonici dalla vostra piattaforma, o definire un evento personalizzato regolato. Gli abbonati ricevono l'evento attraverso le regole di priorità e consegna registrate.

Riferimento

Eventi universali + personalizzatiinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up o il tuo. Abbonati Fan-outIl cervello AI, regole di automazione, connettori a specchio e i endpoint webhook reagiscono tutti. Ordine prioritarioLa spedizione di deternistica così gli specchi scrivono prima di avvisare il fuoco.

02 / Contratti di azione

Dillo. OpsIQ che cosa l'IA è permesso di fare.

Ogni operazione denominata riceve un contratto generato: portata, funzionalità, lettura o scrittura tipo, rischio, politica di conferma, schema di richiesta e risposta, supporto a secco, idempotency e errori stabili.

Schema di azione

L'IA non può inventare azioniPuò solo chiedere di eseguire quelli che hai registrato. Politica di confermaLe azioni risky innescano una scheda di anteprima prima di qualsiasi effetto collaterale. Role + superficie di garofanoOgni azione dichiara i ruoli e le superfici per poterlo eseguire.

contratto d'azione generato · 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 / Segnalato webhooks

Spingere gli eventi al vostro stack - con la prova crittografica.

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.

Protezione da riproduzioneID di consegna trascurabile5-step back-off

Riferimento Webhook

verifica 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/ SDKs

Utilizzare HTTP diretto o generare il client che si preferisce.

L'intero generaleAPI è pubblicato come OpenAPI 3.0.3 e Postman. I mittenti di riferimento PHP più i client di integrazione Node e Python coprono flussi firmati evento e webhook; qualsiasi stack può chiamare lo stesso JSON superficie di azione direttamente.

esempi di client

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

Regia JSON HTTPAprire l'API 3.0.3Collezione PostmanAiuti all'integrazione

05 / Il modello del connettore

Costruisci una volta, infilati in qualsiasi cosa.

Un connettore è un pacchetto governato generato o importato attraverso Identity, Auth, Test, Azioni, Triggers e Review. Il suo manifesto dichiara che le superfici di capacità OpsIQ è permesso di esporre.

Aprire il costruttore di sei stadi

Sei tappe guidateIdentitÃ, tÃ, test, azioni, trigger e revisione mantenere la generazione di pacchetti spiegabile. Contratti8 profiles and 57 capability types declare the surfaces a package implements. CongedatoI controlli di sicurezza, provenienza e conformità funzionano prima che un pacchetto venga trattato come pronto.

Dall'intento all'azione sicura

In inglese. E' stata controllata.

OpsIQ non inventa mai la chiamata giusta. Passa attraverso i contratti registrati, prepara il carico di pagamento, chiede la conferma quando l'azione lo richiede e produce una riga di audit completa quando esegue, in modo da un AI che può atto non diventa mai un'intelligenza artificiale di cui non puoi fidarti.

Contratto. L'IA propone solo azioni che hai registrato.

Confermare prima degli effetti collaterali. Le azioni risky superficie una carta di anteprima prima.

Ricordo totale. Ogni risultato di risposta e azione catturato nella storia dell'intelligenza artificiale.

Vedi lo schema di azione

4 passiintento → audit

HMACfirmato prima dell'esecuzione

Nessuna chiamata inventatasolo il registro di contratto

Confermatoanteprima prima degli effetti collaterali

Richiesta tracciaattore + contratto + risultato

Riferimento

API superficie a colpo d'occhio.

One JSON POST surface exposes 2,415 named actions. Each generated contract declares auth scopes, read/write kind, risk, confirmation, request schema, dry-run, idempotency and stable errors.

OpenAPI 3.0.3 riferimento

AzioneAutorizzazioneScrivi la sicurezzaLimite

Scrivere le azioniPOST /api/v1.php · contratto convalidato

ACTION tickets.replytickets.writeDry_run + idempotConfigurato / ora

ACTION security.reportsecurity.writeDry_run + idempotConfigurato / ora

ACTION platform.routes.writeadminconferma + chiaveConfigurato / ora

Leggere e scoprire le azioniStessa superficie POST · buste stabili

ACTION meta.actionsLa scoperta pubblicaLeggi soloConfigurato / ora

ACTION tickets.listtickets.readLeggi soloConfigurato / ora

ACTION connectors.listconnectors.readLeggi soloConfigurato / ora

PeopleOS HR azioniRivestimento hr.* contratti hr.read / hr.write Campo di applicazione

ACTION hr.people.listhr.readLeggi soloConfigurato / ora

ACTION hr.people.createhr.writeDry_run + idempotConfigurato / ora

ACTION hr.org.treehr.readLeggi soloConfigurato / ora

PeopleOS HR non invia eventi webhook di uscita HR. Raggiungere attraverso la stessa superficie POST, o sottoscrivere agli eventi altri moduli pubblicare. PeoplesAPIe connettori e la Sezione PeopleOS del riferimento sviluppatore. Il modulo è diritto recintato, quindi una chiave senza hr ottiene un rifiuto, non una lista vuota. Quello che PeopleOS HR è.

I limiti di tasso sono configurati per chiave su una finestra oraria. X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; una richiesta respinta 429 con Retry-After. Usare Aprire l'API 3.0.3 contratto o Collezione Postman generato dagli stessi registri di runtime.

Costruire un connettore

Costruisci, testa e rilascia sei tappe.

Inizia da un profilo governato o definisci il contratto stesso. Il Costruttore convalida ogni fase prima di generare un pacchetto di connettori autocontenuto.

1Identita'. Nome, slitta, profilo e superfici di capacità dichiarate.

2Auth. API chiave, cuscinetto, base, OAuth 2.0, HMAC o un cliente personalizzato.

3Prova. Convalida le impostazioni di connessione delimitate prima dell'imballaggio.

4Azioni. Mappa chiamata operazioni, parametri, ambiti e rischi.

5Trigger. Dichiara eventi in entrata, webhooks, polling e sincronizzazione comportamento.

6Recensione. Ispezionare il contratto generato e passare la porta di rilascio.

Prova prima di spedire

Convalida in modo sicuro, quindi passare il cancello di rilascio.

Uso dry_run su azioni di scrittura supportate, eseguire il test di connessione limitato del Costruttore e ispezionare il manifesto generato e contrarsi prima della pubblicazione.

Scritzioni a secco Test di connessione a vuoto Conformità del contratto Consegna Cron-driven

Aprire il Costruttore di connettori Riferimento Webhook

connettore. php · php

classe AcmeConnector Prolungamento AbstractConnector { funzione pubblica slitta(): stringa { ritorno 'acme'; } funzione pubblica nome(): stringa { ritorno "Acme"; } funzione pubblica descrizione(): stringa { ritorno 'Ponteggio acme'; } // Utilizzare i nomi da ConnectorContract funzione pubblica capacità(): array { ritorno ["azioni", "webhook"]; } funzione pubblica impostazioniSchema(): array { ritorno [["Key" => "token", "Tipo" => "password"]]; } funzione pubblica testConnezione(array $settings): array { ritorno ['successo' => vero]; } funzione pubblica manigliaWebhook( array $payload, array $headers, array $settings ): array { ritorno ['successo' => vero]; } }

01 · Connector contract 2.4

Un pacchetto non può rivendicare una capacità il suo codice non ha.

OpsIQ\Connectors\ConnectorContract La scoperta di Runtime, il Costruttore, i pacchetti di prima parte, la conformità, il Generale API e ogni riferimento legge che un registro. Dichiarare una capacità e tre file devono concordare l'uno con l'altro prima OpsIQ percorri una sola fila a te.

FIG. 01pacchetto connettore, parti manifeste scale 1:1 · contract 2.4

01 connector.php la classe runtime
02 IdentityProvider.php chiave esterna stabile
03 SalesIngest.php riconciliareSales()
04 actions.json operazioni nominate
05 settings.json configurazione dell'operatore
06 connector_contract.json autorità leggibile dalla macchina

07 signature.json uno HMAC su una SHA...256 di ogni file sopra, più un ed25519 prova d'origine

Matrice di capacità all 57, as registered

azioni trigger webhook journey_events contesto guest_lookup identità sales sales_reconciliation fatturazione payments Commercio 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 C'è un problema. block_registry inbound_comment outbound_note outbound_notification oauth reviews locale questo site_intelligence analisi comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

generato 30 Dichiarazioni 20 Estensione 7

Due firme, due domande.

hmac-sha256 sopra un carico di paga deterministica per-file SHA-256 hashes risposte è stato modificato dalla firma. An ed25519 risposte firma è stato firmato da Nabtech, selezionabile con la chiave pubblica in bundle e nessun segreto condiviso. Modificare un byte e le prime fermate di corrispondenza.

marketplace.json è fuori dalla firma per definizione: l'installatore lo scrive dopo la firma, in modo che l'editore non avrebbe mai potuto firmare.

02 · strumenti/mutation_proof. php

Una guardia che non ha mai fallito non è provato.

I test verdi non ti dicono niente di rotto oggi, ma la guardia che hai scritto fermerebbe la cosa che è stata scritta per fermarsi, perché una guardia che non viene mai esercitata passa esattamente come una guardia senza fare nulla.

guardia · ruolo di lettura deve rifiutare un'operazione distruttiva 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    }

Esattamente. uno È necessario un match testuale, zero partite o due e la prova si ferma prima che possa mentire.

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

Una prova fallita è mai Evidence che un assegno è andato storto non è la prova che una guardia funziona.

La mutazione non si è mai applicata.

Il testo di ricerca non corrispondeva, il file era intatto, la suite passò e la prova registrata verde sotto il vecchio codice Caught richiedendo esattamente una corrispondenza testuale e confrontando i file hashes sia lato.

La mutazione ha rotto qualcos'altro.

La suite è andata rossa perché il file ha smesso di parsing o la bootstrap è morta, e la prova ha registrato un rosso che non aveva nulla a che fare con la guardia. Nome prova tra i fallimenti.

Non può lasciare un mutante sul disco.

Ogni mutazione copia l'originale a un sidecar al di fuori dell'albero web-servato, scrive un marcatore che nomina il cambiamento eccezionale e viene annullato da un gestore di chiusura su ogni percorso di uscita.

03 · Conformità

La certificazione è un comando con un codice di uscita.

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/ coprono le impostazioni, azioni, specifiche del costruttore, mappature di eventi di viaggio e commercio, ricette di flusso di lavoro, contratti di connettori e manifesti di rilascio.

manifests parse e concordate l'un con l'altro
capacità esistere sulla classe runtime
interfaces attuato in caso di dichiarata
files ogni file richiesto presente
azioni corrispondere il manifesto delle azioni
destructive dichiara conferma di
identità una chiave esterna stabile, non e-mail
ripetizione aggiornamenti ripetuti, mai duplicati
impresa le dichiarazioni corrispondono all'estensione
Docs README, SVILUPPO, CHANGELOG
schemi ogni JSON validazione

uscita 0 acme: conformant against contract 2.4 Una suite incandescente nomina il conto e il file.

$ 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

Indicare il primo in un vero e proprio account non di produzione con --live-settings=/secure/test-acme.json. Mentre stai ancora iterating, scambia l'ultimo per --unsigned-ok: tratta una firma mancante come un avvertimento previsto piuttosto che fingere di essere a posto.

04 · Trade_roles.json

Dichiarare ciò che si può vendere è un file, non una registrazione.

Un connettore che può vendere dichiara quale di il Le operazioni rispondono ai ruoli di commercio canonico di OpsIQ. La presenza del file è la richiesta. Appare nelle impostazioni di vendita il momento in cui dichiara e scompare quando si ferma. Non c'è alcuna lista da iscriversi e nessuno chiedere.

ruolo canonico commerce_roles.json la tua operazione

RIFUSO

Un canonico Scrivi un commento La partita è strutturale: un sostantivo di stoccaggio accanto a un verbo mutante, qualunque sia la vostra convenzione di denominazione. Scrivere il business fila direttamente salta i prezzi della piattaforma, disponibilità di blocco e mail di conferma, e produce un ordine che il commerciante proprio sistema solo metà crede in. recovery O, quindi un timeout sarebbe irrilevante.

commerce_roles.jsonVALIDAZIONE

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

Il suo file di proposito: connector_contract.json è generato e i suoi set di schemi additionalProperties:false, quindi un blocco a mano autorizzato ci sarebbe mancato validazione e poi essere sovrascritto sul prossimo generatore di esecuzione.

Vocabolario chiuso

Un ruolo non in CommerceRole OpsIQ non ne fa mai riferimento a un nome di operazione, perché un nome non è una promessa.

La vostra azione

L'operazione deve apparire nel vostro actions.json. Dichiarare uno che non esiste promette al cliente qualcosa che poi produce nulla.

Scrive dichiarano il recupero

Il timeout più pericoloso è quello dopo la piattaforma può già aver fatto il lavoro. Senza un idempotent "did my write land" lookup, le uniche opzioni sono riprovare cieca o perdere l'ordine.

I ruoli di pagamento certificano

Qualsiasi ruolo di classe di pagamento dichiara anche payment_profile con il ambiente, webhook_verify utilizzando il proprio schema del fornitore, e event_map. Un ambiente non stabilito è come un fornitore di prova-mode prende un pagamento in tempo reale.

Il Costruttore convalida questi come si digita e il verificatore valida il pacchetto spedito. Entrambe chiamano le stesse funzioni, in modo che non possano essere disaccordo.

⚖️Come si confronta

OpsIQ contro un Integrazione fai da te.

Che una piattaforma a contratto, firmata e controllata ti dà che rotolare i tuoi webhooks e AI-action idraulico mai lo farà.

Capacità	Fai come ti pare.	OpsIQ
Cuscinetto scomposto API + HMAC-segnato webhooks	Laminato a mano	✓
Scrive a secco + 24-ora di successo riprova	DIO	✓
1m → 5m → 30m →2h → 12h Restrizioni	La coda del fai-da-te	✓
Registro di sistema di contratto d'azione (AI non può inventare chiamate)	—	✓
Politica di conferma prima degli effetti collaterali	—	✓
Busta di errore stabile + ID richiesta	Registrazione manuale	✓
Opzioni client HTTP dirette + generate	Scrivi la tua	✓
OpenAPI 3.0.3 contratto di lettura automatica	Forse.	✓
Six-Stage Builder + il cancello di rilascio del pacchetto	Creare un toolchain	✓
Tasti a foratura spaziale e limiti orali	Vasi	✓
Modello connettore: codice piattaforma rimane isolato	—	✓

FAQ

Domande sullo sviluppatore, rispose.

Autenticazione, contratti, retries, generazione del cliente, test sicuri e modello di connettore, prima della prima richiesta di produzione.

Generale API chiamate invio Authorization: Bearer opq_…. Le chiavi possono essere non restrizioni, ristrette o di sola lettura, portano scopi meno privati, obbediscono ad un limite orario e possono essere pinned a uno spazio di lavoro. La firma Webhook è separata: le consegne in uscita effettuano X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event e X-OpsIQ-Delivery.

No. L'IA può proporre solo operazioni nominate nel registro di azione. Ogni contratto generato dichiara campo di applicazione, campi di richiesta, politica di rischio e conferma; le operazioni la cui politica richiede una superficie di conferma un'anteprima umana prima dell'esecuzione.

Ricompenso hash_hmac('sha256', $rawBody, $secret) e confronta il suo digerente esadecimale con X-OpsIQ-Signature utilizzando hash_equals. Valida X-OpsIQ-Timestamp all'interno della finestra di riproduzione e uso X-OpsIQ-Delivery come identificatore di consegna tracciabile.

Un tentativo non riuscito entra nella coda di consegna di sfondo. OpsIQ i retries sul1- minuto, 5- minuto, 30- minuto,2-ora e 12- scala di ore pur mantenendo l'identificatore di consegna e tentare la storia per diagnostica.

Chiama il JSON superficie azione direttamente, importare la raccolta Postman generata o generare un client da OpenAPI 3.0.3. I mittenti di riferimento PHP e i clienti di integrazione Node/Python supportano l'evento e i flussi webhook; sono aiutanti piuttosto che separatiAPI contratti.

Uso dry_run su azioni il cui contratto generato lo supporta, eseguire il test di connessione bounded del Connettore Builder, ispezionare i suoi file generati e passare la conformità pacchetto e cancelli di rilascio prima di trattare il connettore come pronto.

Il rilascio installato genera la sua API e contratti di connessione da propri registri a tempo pieno. La vostra distribuzione possiede il suo pubblico URL, segreti, storage e cron/workers, quindi il comportamento dovrebbe essere verificato contro il rilascio installato piuttosto che assunto da un ambiente cloud.

Un connettore è un pacchetto governato contenente l'adattatore, settings.json, facoltativo actions.json, un contratto di capacità generato, documentazione e estensioni aziendali opzionali. Il costruttore a sei stadi lo assembla; il registro lo scopre; la conformità e le porte di rilascio convalidano.