Plateforme de développement · Général API · webhooks · connecteurs

Rendez votre plateforme exploitable par l’IA.

Call 2,420 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.

Obtenez une clé API Lisez la documentation Contrat OpenAPI

Clés de portage à portée2,420 contract actionsOpenAPI 3.0.3 + PostmanLivraison en ligne de HMAC

Demande détaillée

Webhook signé sortant → 200 OK

En direct

2,420actions nommées générales API

69les zones de moindre privilège

dry_runvalider les contrats d'écriture avant l'exécution

24hreplay réussi idémpotent-write

Le cycle de vie de la demande

Demande détaillée. Événement signé.

POST une action pour /api/v1.php avec une clé de portage. OpsIQ pins l'espace de travail, valide le contrat d'action et les permissions, puis exécute ou fait fonctionner à sec. Les événements canoniques abonnés partent par une file d'attente de livraison signée HMAC avec des tentatives traçables et des rétries limitées.

webhooks HMAC-SHA256 - les charges utiles des webhooks entrants et sortants sont signées sur le corps brut ; les appels API s'authentifient avec une clé Bearer limitée.

Réessais automatiques - les livraisons échouées se retirent et réessaient, avec un ID de livraison que vous pouvez tracer.

Réjouissez-safe écrit - idémpotent écrit avec succès retourne la même réponse pour 24 heures; les duplicatas simultanés partagent une revendication.

01 Demande de présentation 02 espace de travail des broches 03 valider le contrat 04 exécuter ou exécuter à sec 05 événement signé de file d'attente

Démarrage rapide

De la clé à l'intégration régie dans trois étapes.

Émettre une clé moins privilège, découvrir le contrat généré, faire un essai à sec, puis s'abonner à un webhook lorsque votre application a besoin de la livraison d'un événement de fond.

Console contractuelleConnecté

Exécuterdry_run → écrit approuvé, même contrat

Obtenez une clé

Inscrivez-vous et générez une clé API Bearer limitée (opq_…) dans les paramètres développeur, et donnez à chaque intégration uniquement les surfaces dont elle a besoin.

Découvrez & valider

Lire meta.actions, meta.action et meta.scopes; utilisation dry_run valider les écrits avant l'exécution.

Exécuter & s'abonner

Ajoutez une clé d'idempotency pour écrire, puis inscrivez votre point final aux événements canoniques dont votre application a besoin.

Comment cela s'assemble

Un modèle de connecteur. Cinq primitives propres.

Tout ce qui est spécifique à la plateforme vit dans un connecteur. Le cœur d'OpsIQ reste générique, l'IA reste prévisible, et votre intégration reste auditable.

Déclencheurs

Dites à OpsIQ ce qui vient de se passer.

Émettre des événements canoniques de votre plateforme ou définir un événement personnalisé régi. Les abonnés reçoivent l'événement par le biais des règles de priorité et de livraison enregistrées.

Référence d'événement

Événements universels + personnalisésinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up ou votre propre. Abonnés en fan-outLe cerveau AI, les règles d'automatisation, les connecteurs miroir et vos points de terminaison webhook réagissent tous. Ordre de prioritéDispatch déterministe afin que les miroirs écrivent avant que les alertes ne se déclenchent.

02 / Contrats d'action

Dites à OpsIQ ce que l'IA est autorisée à faire.

Chaque opération nommée reçoit un contrat généré : portée, fonctionnalité, type de lecture ou d'écriture, risque, politique de confirmation, schéma de demande et de réponse, support à sec, idempotency et erreurs stables.

Schéma d ' action

L'IA ne peut pas inventer d'actionsIl ne peut demander d'exécuter que ceux que vous avez enregistrés. Politique de confirmationLes actions risquées déclenchent une carte d'aperçu avant tout effet secondaire. Gating par rôle + surfaceChaque action déclare les rôles et surfaces autorisés à l'exécuter.

contrat d'action généré · 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"] }
}

14. Changements

Poussez des événements vers votre pile - avec preuve cryptographique.

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.

Protection contre la relectureID de livraison traçable5-step back-off

Référence Webhook

vérifier le 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

Utilisez directement HTTP ou créez le client que vous préférez.

Le général en entierAPI est publié en tant qu'OpenAPI 3.0.3 et Postman. Les expéditeurs de référence PHP plus les clients d'intégration Node et Python couvrent les flux d'événements signés et webhook ; n'importe quelle pile peut appeler la même JSON surface d'action directement.

exemples de clients

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

HTTP direct JSONOuvrir l'API 3.0.3Collecte de courrierAides à l'intégration

05 / Le modèle de connecteur

Construisez une fois. Branchez-vous à tout.

Un connecteur est un paquet régi généré ou importé par l'intermédiaire de Identity, Auth, Test, Actions, Triggers et Review. Son manifeste déclare que les surfaces de capacité OpsIQ sont autorisées à exposer.

Ouvrir le constructeur en six étapes

Six étapes guidéesIdentité, Auth, Test, Actions, Triggers et Review maintiennent la génération de paquets explicables. Marchés8 profiles and 57 capability types declare the surfaces a package implements. DélivranceLes contrôles de sécurité, de provenance et de conformité se déroulent avant qu'un colis ne soit traité comme prêt.

De l'intention à l'action sécurisée

Anglais simple. Opération audité sortie.

OpsIQ n'invente jamais le bon appel. Il parcourt les contrats enregistrés, prépare la charge utile, demande confirmation lorsque l'action l'exige, et produit une ligne d'audit complète lorsqu'il exécute, donc une IA qui peut agir ne devient jamais une IA à laquelle vous ne pouvez pas faire confiance.

Lié par contrat. L'IA ne propose que des actions que vous avez enregistrées.

Confirmer avant les effets secondaires. Les actions risquées affichent d'abord une carte d'aperçu.

Un souvenir total. Chaque invite, réponse et résultat d'action capturé dans l'historique AI.

Voir le schéma d'action

4 étapesintention → audit

HMACsigné avant exécution

Pas d'appels inventésregistre de contrat uniquement

Confirmé par porteaperçu avant effets secondaires

Demande de traceacteur + contrat + résultat

Référence

Surface API en un coup d ' œil.

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

Référence OpenAPI 3.0.3

DécisionResp.: Ministère de l'Economie et des FinancesÉcrire la sécuritéLimite

Écrire des actionsPOSTE /api/v1.php · contrat validé

ACTION tickets.replytickets.write_cours sec + idempotencyConfiguration / heure

ACTION security.reportsecurity.write_cours sec + idempotencyConfiguration / heure

ACTION platform.routes.writeadministrateurconfirmation + cléConfiguration / heure

Actions de lecture et découverteMême surface POST · enveloppes stables

ACTION meta.actionsDécouverte publiqueLecture seuleConfiguration / heure

ACTION tickets.listtickets.readLecture seuleConfiguration / heure

ACTION connectors.listconnectors.readLecture seuleConfiguration / heure

Mesures prises par PeopleOS dans le domaine des ressources humainesCouvert hr.* contrats hr.read / hr.write portées

ACTION hr.people.listhr.readLecture seuleConfiguration / heure

ACTION hr.people.createhr.write_cours sec + idempotencyConfiguration / heure

ACTION hr.org.treehr.readLecture seuleConfiguration / heure

PeopleOS HR n'envoie pas d'événements de webhook HR sortants. Atteindre par la même surface POST, ou s'abonner aux événements d'autres modules publiés. PeopleOS API et connecteurs et le La section PeopleOS de la référence du développeur. Le module est fermé, donc une clé sans hr On obtient un refus, pas une liste vide. Ce que PeopleOS HR est.

Les limites de taux sont configurées par clé sur une fenêtre horaire. X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset; une demande rejetée renvoie 429 avec Retry-After. Utilisez le Contrat OpenAPI 3.0.3 ou Collecte de courrier généré à partir des registres d'exécution identiques.

Construisez un connecteur

Construisez, testez et relâchez six étapes.

Commencez par un profil régi ou définissez le contrat vous-même. Le Constructeur valide chaque étape avant de générer un paquet de connecteurs autonome.

1Identité. Nom, limace, profil et surfaces de capacité déclarées.

2- Oui. API clé, porteur, basique, OAuth 2.0, HMAC ou un client personnalisé.

3Essai. Valider les paramètres de connexion délimités avant l'emballage.

4Actions. Carte nommée opérations, paramètres, champs d'application et risques.

5Déclencheurs. Déclarez les événements entrants, les webhooks, le comportement de sondage et de synchronisation.

6Revue. Inspecter le contrat généré et passer la porte de sortie.

Testez avant de déployer

Valider en toute sécurité, puis passer la porte de sortie.

Utilisation dry_run sur les actions d'écriture supportées, exécuter le test de connexion limité du constructeur, et inspecter le manifeste généré et le contrat avant la libération. Vérification de validation du paquet noms de capacité, paramètres, provenance et fichiers requis; travailleurs de fond traitent le vote réactif et la livraison sortante.

Dry-run écrit Essai de connexion avec un ancrage en bon état Conformité au contrat Livraisons avec activation de la couronne

Ouvrir le constructeur de connecteurs Référence Webhook

connector. php · php

classe AcmeConnector étend AbstractConnector { fonction publique Limace(): chaîne { retour acme; } fonction publique nom(): chaîne { retour "Actème"; } fonction publique description(): chaîne { retour 'Pont d'Acme'; } // Utiliser des noms de ConnectorContract fonction publique capacités(): tableau { retour [«actions», "webhook"]; } fonction publique paramètresSchema(): tableau { retour [["Claque" => "Jeune", «type» => Mot de passe]]; } fonction publique testConnection(tableau $settings): tableau { retour ["succès" => vrai]; } fonction publique poignéeWebhook( tableau $payload, tableau $headers, tableau $settings ): tableau { retour ["succès" => vrai]; } }

01 · Connector contract 2.4

Un paquet ne peut pas réclamer une capacité son code n'a pas.

OpsIQ\Connectors\ConnectorContract est l'autorité. Découverte d'exécution, le Constructeur, les paquets de première partie, la conformité, le Général API et chaque référence lisait qu'un registre. Déclarer une capacité et trois fichiers doivent être d'accord avant OpsIQ vous mène à une seule rangée.

FIG. 01paquet de connecteurs, manifeste des pièces scale 1:1 · contract 2.4

01 connector.php la classe d'exécution
02 IdentityProvider.php clé extérieure stable
03 SalesIngest.php réconcilierVentes()
04 actions.json les opérations désignées
05 settings.json configuration de l'opérateur
06 connector_contract.json autorité lisible par machine

07 signature.json une HMAC sur un SHA...256 de chaque dossier ci-dessus, plus une preuve d'origine ed25519

Matrice des capacités all 57, as registered

Mesures prises déclencheurs webhook journey_events contexte guest_lookup identité sales sales_reconciliation facturation payments commerce 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 locaux ceci site_intelligence Analyse comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

généré 30 déclaratif 20 extension 7

Deux signatures, deux questions.

hmac-sha256 sur une charge utile déterministe de SHA par dossier256 Réponses a été modifié depuis la signature. Une ed25519 réponses à la signature a-t-elle été signée par Nabtech, contrôlable avec la clé publique groupée et aucun secret partagé. Edit un octet et le premier arrête de correspondre.

marketplace.json est en dehors de la signature par définition: l'installateur l'écrit après la signature, donc l'éditeur n'aurait jamais pu la signer.

02 · outils/mutation_proof. php

Un garde qui n'a jamais échoué n'est pas prouvé.

Les tests verts vous disent que rien ne s'est cassé aujourd'hui. Ils ne vous disent pas que le gardien que vous avez écrit arrêterait la chose qu'il a été écrit pour arrêter, parce qu'un garde qui n'est jamais exercé passe exactement comme un gardien qui ne fait rien.

garde · lecture rôle doit refuser une opération destructrice CH1 verify_commerce_contracts

src/Connectors/CommerceRoleMapVerifier.php MUTÉS

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    }

Exactement. une Il faut une correspondance textuelle. Zéro correspond, ou deux, et la preuve s'arrête avant qu'elle ne puisse mentir.

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

Une preuve ratée est jamais La preuve qu'un chèque a mal tourné n'est pas une preuve qu 'un gardien fonctionne.

La mutation n'a jamais été appliquée.

Le texte de recherche ne correspond pas, le fichier est intact, la suite passe, et la preuve enregistrée vert sous l'ancien code sur le code qui n'a jamais été vieux. Pris en exigeant exactement une correspondance textuelle et en comparant les hashes de fichier de chaque côté.

La mutation a cassé autre chose.

La suite est devenue rouge parce que le dossier a cessé d'analyser ou que le bootstrap est mort, et la preuve a enregistré un rouge qui n'avait rien à voir avec le garde. nommé test parmi les échecs.

Il ne peut pas laisser un mutant sur le disque.

Chaque mutation copie l'original à un sidecar en dehors de l'arbre Web-servit, écrit un marqueur qui nomme le changement exceptionnel, et est défait par un gestionnaire d'arrêt sur chaque chemin de sortie. Un marqueur d'un parcours écrasé est honoré avant la prochaine mutation de ce fichier.

03 · Conformité

La certification est une commande avec un code de sortie.

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/ couvrir les paramètres, actions, spécifications du constructeur, cartes d'événements de voyage et de commerce, recettes de workflow, contrats de connecteurs et manifestes de publication.

manifests parse et d'accord l'un avec l'autre
capacités existe sur la classe d'exécution
interfaces mise en œuvre lorsque déclarée
files chaque fichier requis présent
Mesures prises correspondre au manifeste des actions
destructive déclarer confirmation
identité une clé externe stable, pas un courriel
rejouer une mise à jour répétée, jamais dupliquée
entreprise les déclarations correspondent à l'extension
docs LIRE, DÉVELOPPER, CHANGEMENT
schémas tous les JSON valide

sortie 0 acme: conformant against contract 2.4 Une suite défaillante donne le nom du chèque et du fichier.

$ 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

Pointez le premier sur un compte réel non-production avec --live-settings=/secure/test-acme.json. Pendant que vous êtes toujours itératif, échangez le dernier pour --unsigned-ok: il traite une signature manquante comme un avertissement attendu plutôt que de prétendre qu'elle est bonne.

04 · commerce.json

Déclarer ce que vous pouvez vendre est un fichier, pas une inscription.

Un connecteur qui peut vendre déclare lequel de ses propres operations reply OpsIQ_'s canonical commerce role. La présence du fichier est la revendication. Il apparaît dans les paramètres de vente le moment où il déclare et disparaît quand il s'arrête. Il n'y a pas de liste à rejoindre et personne à demander.

rôle canonique commerce_roles.json votre opération

REFUS

Un canonique écrire Le rôle est maped à un enregistrement générique écrire. La correspondance est structurelle: un nom de stockage à côté d'un verbe mutant, quelle que soit votre convention de nommage. recovery soit, donc un délai de non-recoverable.

commerce_roles.jsonVALEUR

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

Son propre dossier a été conçu pour : connector_contract.json est généré et ses ensembles de schémas additionalProperties:false, donc un bloc d'auteurs à la main là échouerait validation et ensuite être écrasé sur le prochain générateur.

Vocabulaire fermé

Un rôle qui ne se joue pas dans CommerceRole n'existe pas. OpsIQ ne l'inférera jamais à partir d'un nom d'opération, car un nom n'est pas une promesse.

Votre propre action

L'opération doit apparaître dans votre actions.json. Déclarer celui qui n'existe pas promet au client quelque chose qui ne produit alors rien.

Écrit déclarer la récupération

Le temps d'absence le plus dangereux est celui après la plate-forme peut déjà avoir fait le travail. Sans un idémpotent "a fait ma terre d'écriture" recherche, les seules options sont de reessayer aveugle ou perdre l'ordre.

Rôles de paiement certifier

Tout rôle de classe paiement déclare également payment_profile avec environnement, webhook_verify utiliser le propre régime du prestataire, et event_map. Un environnement non déclaré est la façon dont un fournisseur de mode test prend un paiement en direct.

Le Constructeur valide ces fonctions lorsque vous tapez et le vérificateur valide le paquet expédié. Les deux appellent les mêmes fonctions, de sorte qu'ils ne peuvent pas être en désaccord.

⚖️ Comment cela se compare

OpsIQ vs un Intégration DIY.

Ce qu'une plateforme liée par contrat, signée et auditée vous offre que la création de vos propres webhooks et l'intégration des actions IA ne pourront jamais fournir.

Capacité	Créez le vôtre	OpsIQ
Porte-filtre à portée API + HMAC signé webhooks	laminés à la main	✓
Dry-run écrit + 24 heure replay réussi	Bricolage	✓
1m → 5m → 30m →2h → 12h pour les comptes rendus	DIRECTION DU DIY	✓
Registre des contrats d'action (AI ne peut pas inventer les appels)	—	✓
Politique de confirmation avant effets secondaires	—	✓
Erreur stable enveloppe + ID de demande	Enregistrement manuel	✓
Options client directement HTTP + générées	Écris-toi.	✓
OpenAPI 3.0.3 contrat lisible par machine	Peut-être	✓
Constructeur en six étapes + porte de sortie du paquet	Construire une chaîne d'outils	✓
Clés de l'espace de travail et limites horaires	Varie	✓
Profil de connecteur: le code de la plate-forme reste isolé	—	✓

FAQ

Questions des développeurs, répondu.

Authentification, contrats, relevés, génération de clients, tests sûrs et modèle de connecteur, avant la première demande de production.

Général API appels envoyés Authorization: Bearer opq_…. Les clés peuvent être illimitées, restreintes ou en lecture seule, porter des champs de moindre privilège, obéir à une limite horaire et peuvent être épinglées sur un espace de travail. X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event et X-OpsIQ-Delivery.

Non. L'IA ne peut proposer que des opérations nommées dans le registre d'action. Chaque contrat généré déclare la portée, les champs de demande, la politique de risque et de confirmation; les opérations dont la politique nécessite une confirmation font surface un aperçu humain avant l'exécution.

Recalculer hash_hmac('sha256', $rawBody, $secret) et de comparer son digesteur hexadécimal avec X-OpsIQ-Signature utilisant hash_equals. Valider X-OpsIQ-Timestamp dans votre fenêtre de replay et utiliser X-OpsIQ-Delivery comme l'identificateur de livraison traçable.

Une tentative non réussie entre dans la file d'attente. OpsIQ les comptes rendus des1- minute, 5- minute, 30- minute,2- heures et 12- échelle horaire tout en conservant l'identificateur de livraison et l'historique des tentatives de diagnostic.

Appelez le JSON surface d'action directement, importer la collection Postman générée, ou générer un client depuis OpenAPI 3.0.3. Les expéditeurs de référence PHP et les clients d'intégration Node/Python supportent les flux d'événements et de webhook; ils sont des aides plutôt que séparésAPI les contrats.

Utilisation dry_run sur les actions dont le contrat généré le supporte, exécutez le test de connexion limité du Constructeur de connecteurs, inspectez ses fichiers générés et passez les portes de conformité et de libération du paquet avant de traiter le connecteur comme prêt.

La version installée génère son API et les contrats de connecteur de ses propres registres d'exécution. Votre déploiement possède son public URL, secrets, stockage et cron/travailleurs, donc le comportement doit être vérifié contre la libération installée plutôt que supposé d'un environnement nuageux.

Un connecteur est un paquet régi contenant l'adaptateur, settings.json, facultative actions.json, un contrat de capacité généré, documentation et extensions d'entreprise optionnelles. Le constructeur à six étapes l'assemble; le registre le découvre; les portes de conformité et de libération valident.