API de desarrollador, Webhooks y SDK de Conector — OpsIQ

API de desarrollador, Webhooks y SDK de Conector — OpsIQ

Crea integraciones conscientes de la IA con la API de desarrollador de OpsIQ, que incluye puntos finales REST firmados, webhooks HMAC, contratos de acción y SDK para PHP, Node y Python. Obtén una clave gratis y haz que tu plataforma sea operable por IA.

Descripción general

OpsIQ expone una API REST limpia, webhooks firmados por HMAC, un registro de contratos de acción y SDK listos para enviar. Puedes definir qué eventos se activan desde tu sistema, qué acciones puede ejecutar la IA y qué datos son seguros para leer. OpsIQ maneja las firmas, reintentos, registros de auditoría y flujos de confirmación por ti.

Comenzando

1. Obtén una clave API: Regístrate y genera un par de claves públicas/secretas con alcance en la configuración del desarrollador. Da a cada integración solo las superficies que necesita.
2. Dispara y suscríbete: Envía un evento firmado a la endpoint events/fire (o usa un SDK), luego apunta cualquier URL a cualquier evento — firmado, con un ID de entrega y reintentos de retroceso.
3. Registra una acción: Declara un contrato de acción firmado para que la IA pueda ejecutar operaciones de manera segura, incluyendo verificaciones de rol, políticas de confirmación y un registro de auditoría completo.

Manejo de eventos

Informa a OpsIQ lo que acaba de suceder disparando eventos universales desde tu plataforma o tus propios nombres de eventos personalizados. Cada suscriptor reacciona en tiempo real, en orden de prioridad.

Referencia de eventos

• Eventos universales: invoice.paid, ticket.created, subscription.cancelled, customer.signed_up, o tus propios eventos personalizados.

Contratos de acción

Informa a OpsIQ lo que la IA puede hacer. Un contrato de acción es una declaración JSON firmada que especifica lo que hace la acción, qué roles pueden ejecutarla, qué parámetros acepta, si se requiere confirmación y el endpoint a llamar.

Ejemplo de esquema de acción

{
    "key": "saas.refund_invoice",
    "label": "Reembolsar una factura pagada",
    "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

Envía eventos a tu stack con prueba criptográfica. Suscribe cualquier URL a cualquier evento. OpsIQ envía el payload JSON firmado con HMAC-SHA256 sobre el cuerpo en bruto, que puedes verificar en unas pocas líneas.

Referencia de 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

Tres SDK oficiales manejan autenticación, firma, reintentos, claves de idempotencia y respuestas tipadas. Alternativamente, puedes permanecer libre de frameworks, ya que cada SDK es un envoltorio delgado alrededor de la misma superficie REST.

Ejemplos de cliente

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" });

Patrón de conector

Un conector es una carpeta con una clase PHP. OpsIQ lo descubre, el registro conecta los eventos y tu código específico de la plataforma se mantiene limpiamente separado del núcleo.

Guía del conector

1. Esqueleto una carpeta con connector.php extendiendo AbstractConnector.