Documentation des développeurs 5 min de lecture

API de développement, Webhooks & SDK de connecteur — OpsIQ

Cet article a été traduit automatiquement.

API de développement, Webhooks & SDK de connecteur — OpsIQ

Créez des intégrations conscientes de l'IA avec l'API de développement OpsIQ, qui comprend des points de terminaison REST signés, des webhooks HMAC, des contrats d'action et des SDK pour PHP, Node et Python. Obtenez une clé gratuitement et rendez votre plateforme opérationnelle avec l'IA.

Vue d'ensemble

OpsIQ expose une API REST propre, des webhooks signés HMAC, un registre de contrats d'action et des SDK prêts à être expédiés. Vous pouvez définir quels événements se déclenchent depuis votre système, quelles actions l'IA est autorisée à exécuter et quelles données sont sûres à lire. OpsIQ gère les signatures, les nouvelles tentatives, les journaux d'audit et les flux de confirmation pour vous.

Commencer

Obtenez une clé API : Inscrivez-vous et générez une paire de clés publique/privée avec portée dans les paramètres de développement. Donnez à chaque intégration uniquement les surfaces dont elle a besoin.
Déclencher & s'abonner : POST un événement signé à l'endpoint events/fire (ou utilisez un SDK), puis pointez n'importe quelle URL vers n'importe quel événement — signé, avec un ID de livraison et des nouvelles tentatives.
Enregistrer une action : Déclarez un contrat d'action signé afin que l'IA puisse exécuter des opérations en toute sécurité, y compris des vérifications de rôle, une politique de confirmation et une traçabilité complète.

Gestion des événements

Informez OpsIQ de ce qui vient de se passer en déclenchant des événements universels depuis votre plateforme ou vos propres noms d'événements personnalisés. Chaque abonné réagit en temps réel, par ordre de priorité.

Référence des événements

Événements universels : invoice.paid, ticket.created, subscription.cancelled, customer.signed_up, ou vos propres événements personnalisés.

Contrats d'action

Dites à OpsIQ ce que l'IA est autorisée à faire. Un contrat d'action est une déclaration JSON signée qui spécifie ce que fait l'action, quels rôles peuvent l'exécuter, quels paramètres elle accepte, si une confirmation est requise et le point de terminaison à appeler.

Exemple de schéma d'action

{
    "key": "saas.refund_invoice",
    "label": "Rembourser une facture payée",
    "surface": ["admin"],
    "roles": ["owner", "billing_admin"],
    "requires_confirmation": true,
    "params": {
        "invoice_id": {
            "type": "int",
            "required": true
        },
        "reason": {
            "type": "string",
            "max": 500
        }
    },
    "endpoint": "https://api.you.com/refund",
    "audit": true
}

Webhooks

Poussez des événements vers votre pile avec une preuve cryptographique. Abonnez n'importe quelle URL à n'importe quel événement. OpsIQ envoie le payload JSON signé avec HMAC-SHA256 dans le corps brut, que vous pouvez vérifier en quelques lignes.

Référence Webhook

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_OPSIQ_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $sig)) http_response_code(401);
$event = json_decode($raw, true);

SDKs

Trois SDK officiels gèrent l'authentification, la signature, les tentatives, les clés d'idempotence et les réponses typées. Alternativement, vous pouvez rester sans framework, car chaque SDK est un mince wrapper autour de la même surface REST.

Exemples de client

import { OpsIQ } from "@opsiq/sdk";
const ops = new OpsIQ({ publicKey, secretKey });
await ops.events.fire("order.shipped", { customer_id: 421, order_ref: "NB-9182", carrier: "DHL" });
const result = await ops.actions.run("saas.send_kb_link", { ticket_id: 5519, article: "how-to-reset-password" });

Modèle de Connecteur

Un connecteur est un dossier avec une classe PHP. OpsIQ le découvre, le registre connecte les événements, et votre code spécifique à la plateforme reste proprement séparé du cœur.

Guide du Connecteur

Créez un dossier avec connector.php étendant AbstractConnector.
Déclarez les manifestes actions.json et settings.json.
Implémentez les fournisseurs d'identité, de contexte et de webhook.
Abonnez-vous aux événements qui vous intéressent.
Signez-le, déposez-le et activez-le dans l'administration.

Tests

Chaque espace de travail expose un bac à sable avec sa propre paire de clés qui touche la même surface API sans toucher aux données de production. Utilisez POST /v1/webhooks/test pour envoyer un échantillon de livraison signé à votre point de terminaison et confirmez votre vérification de signature avant de passer en production.

FAQ

Comment fonctionne l'authentification ?

Chaque requête porte votre clé publique plus un en-tête X-OpsIQ-Signature, qui est un HMAC-SHA256 du corps brut utilisant votre clé secrète, et un X-OpsIQ-Timestamp pour la protection contre la répétition. OpsIQ vérifie la signature, la fenêtre de timestamp, la portée de votre clé et le rôle de l'acteur avant que quoi que ce soit ne s'exécute.

L'IA peut-elle exécuter des actions que je n'ai pas approuvées ?

Non. L'IA ne peut proposer que des actions qui existent dans votre registre de contrats d'actions. Elle ne peut pas inventer un appel.

Comment vérifier qu'un webhook provient vraiment d'OpsIQ ?

Recalculez sha256=hash_hmac('sha256', $rawBody, $secret) et comparez-le à l'en-tête X-OpsIQ-Signature avec une vérification en temps constant (hash_equals).

Quels SDK sont disponibles ?

Les SDK officiels pour PHP 8.4+, Node.js 18+ et Python 3.10+ gèrent la signature, les tentatives, les clés d'idempotence et les réponses typées.

Puis-je tester sans toucher à la production ?

Oui. Chaque espace de travail expose un bac à sable avec sa propre paire de clés qui accède à la même surface API sans toucher aux données de production.

La version auto-hébergée se comporte-t-elle de la même manière que le cloud ?

Oui. Les installations auto-hébergées exécutent le même chemin de code, donc il n'y a pas de dérive comportementale entre le cloud et l'on-prem.

Qu'est-ce qu'un connecteur, exactement ?

Un connecteur est un dossier autonome avec une classe PHP étendant AbstractConnector, plus des manifestes actions.json et settings.json. Vous implémentez identityProviders(), contextProviders(), registerActions(), subscribers(), et handleWebhook.