Plataforma de desarrollador · REST · webhooks · SDKs

Haz que tu plataforma sea operable con IA.

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

Obtén una clave API Lee la documentación SDKs en GitHub

HMAC-SHA256 en ambas direccionesPHP · Node · SDKs de PythonContrato OpenAPI 3.0.3100% de cobertura de auditoría

Solicitud firmada en

Webhook firmado fuera → 200 OK

En vivo

3SDK oficiales: PHP, Node, Python

HMACFirmado con SHA-256 en cada solicitud

40+eventos universales para suscribirse

100%cobertura de registro de auditoría en acciones

El ciclo de vida de la solicitud

Solicitar en. Webhook firmado fuera.

Haces un POST a la API de OpsIQ con tu clave Bearer con alcance. OpsIQ verifica el alcance y el rol, ejecuta la acción contratada, escribe una fila de auditoría - luego envía un webhook firmado HMAC de vuelta a tu punto final. Cada salto está autenticado, es idempotente y se reintenta en caso de fallo.

webhooks HMAC-SHA256 - las cargas útiles de webhook entrantes y salientes están firmadas sobre el cuerpo en bruto; las llamadas API se autentican con una clave Bearer con alcance.

Reintentos automáticos - las entregas fallidas retroceden y reintentan, con un ID de entrega que puedes rastrear.

Claves de idempotencia - seguro de reproducción por diseño, por lo que una entrega reintentada nunca actúa dos veces.

01 solicitud firmada 02 verificar HMAC 03 Contrato de ejecución 04 Escribir fila de auditoría 05 webhook firmado

Inicio rápido

De cero a una integración en vivo en cuatro pasos.

Genera una clave, dispara tu primer evento, suscribe un webhook, registra una acción. Puedes ejecutar todo el ciclo contra el sandbox antes de tocar datos de producción.

Consola de SandboxConectado

PromocionarSandbox → producción, mismo código

Obtener una clave

Regístrate y genera una clave API Bearer con alcance (opq_…) en la configuración de desarrollador, y da a cada integración solo las superficies que necesita.

Activar y suscribirse

Enviar un mensaje firmado events/fire (o usar un SDK), luego apunta cualquier URL a cualquier evento, firmado, con un ID de entrega y reintentos de retroceso.

Registrar una acción

Declara un contrato de acción firmado para que la IA pueda ejecutar operaciones de manera segura, con verificaciones de rol, política de confirmación y un rastro de auditoría completo.

Cómo encaja todo

Un patrón de conector. Cinco primitivas limpias.

Cualquier cosa específica de la plataforma vive en un conector. El núcleo de OpsIQ se mantiene genérico, la IA se mantiene predecible y tu integración se mantiene auditable.

Activadores

Dile a OpsIQ qué acaba de suceder.

Dispara eventos universales desde tu plataforma - o tus propios nombres de eventos personalizados. Cada suscriptor reacciona en tiempo real, en orden de prioridad.

Referencia de evento

Eventos universales + personalizadosinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up o el suyo propio. Suscriptores de fan-outEl cerebro AI, reglas de automatización, conectores espejo y tus endpoints de webhook reaccionan todos. Orden de prioridadDespacho determinista para que los espejos escriban antes de que se activen las alertas.

02 / Contratos de acción

Dile a OpsIQ lo que la IA puede hacer.

Un contrato de acción es una declaración JSON firmada: lo que hace la acción, qué roles pueden ejecutarla, qué parámetros acepta, si se requiere confirmación, y el punto final a llamar.

Esquema de acción

La IA no puede inventar accionesSolo puede pedir ejecutar los que ha registrado. Política de confirmaciónLas acciones arriesgadas activan una tarjeta de vista previa antes de cualquier efecto secundario. Gating por rol + superficieCada acción declara los roles y superficies permitidos para ejecutarla.

contrato de acción - JSON

{
  "key": "saas.refund_invoice",
  "label": "Refund a paid invoice",
  "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
}

14. Cambios

Envía eventos a tu pila - con prueba criptográfica.

Suscribe cualquier URL a cualquier evento. OpsIQ POSTea la carga JSON firmada con HMAC-SHA256 sobre el cuerpo en bruto - verifícalo en unas pocas líneas.

Protección de repeticiónID de entrega rastreableReintentos de retroceso

Referencia de Webhook

verificar webhook - php

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

04 / SDKs

Clientes integrados para el idioma que ya usas.

Tres SDK oficiales manejan autenticación, firma, reintentos, claves de idempotencia y respuestas tipadas. O mantente libre de framework: cada SDK es un delgado envoltorio alrededor de la misma superficie REST.

ejemplos de clientes

import { OpsIQ } from "@opsiq/sdk";
const ops = new OpsIQ({ apiKey: process.env.OPSIQ_KEY });

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

use OpsIQ\Client;

$ops = new Client([
  'api_key' => getenv('OPSIQ_KEY'),
]);

$ops->events->fire('order.shipped', [
  'customer_id' => 421,
  'order_ref' => 'NB-9182',
]);

$result = $ops->actions->run('saas.send_kb_link', [
  'ticket_id' => 5519,
  'article' => 'how-to-reset-password',
]);

from opsiq import OpsIQ

ops = OpsIQ(
    api_key=os.environ["OPSIQ_KEY"],
)

ops.events.fire("order.shipped", {
    "customer_id": 421,
    "order_ref": "NB-9182",
})

result = ops.actions.run("saas.send_kb_link", {
    "ticket_id": 5519,
    "article": "how-to-reset-password",
})

PHP 8.4+Node.js18+Python 3.10+REST · OpenAPI 3.0.3

05 / El patrón de conector

Construye una vez. Conéctate a cualquier cosa.

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

Cinco ganchosidentityProviders(), contextProviders(), registerActions(), subscribers(), handleWebhook(). Impulsado por manifiestoactions.json y settings.json declarar contratos y configuración. Descubierto automáticamenteSuelta la carpeta, fírmala, habilítala en el administrador.

De la intención a la acción segura

Inglés sencillo en. Operación auditada fuera.

OpsIQ nunca inventa la llamada correcta. Revisa los contratos registrados, prepara la carga útil, pide confirmación cuando la acción lo requiere y produce una fila de auditoría completa cuando se ejecuta, así que una IA que puede actuar nunca se convierte en una IA en la que no puedes confiar.

Vinculado por contrato. La IA solo propone acciones que has registrado.

Confirma antes de efectos secundarios. Las acciones arriesgadas muestran primero una tarjeta de vista previa.

Recuerdo total. Cada aviso, respuesta y resultado de acción capturados en el Historial de IA.

Ver el esquema de acción

4 pasosintención → auditoría

HMACfirmado antes de ejecutar

Sin llamadas inventadasregistro de contratos solamente

Confirmación con puertavista previa antes de efectos secundarios

100% auditadoindicación + respuesta + resultado

Referencia

Superficie de API De un vistazo.

Cada punto final central, su autenticación, idempotencia y límite de tasa por clave. El contrato completo legible por máquina vive en la referencia OpenAPI 3.0.3.

Referencia OpenAPI 3.0.3

Punto finalAutenticaciónIdempotenteLímite de tasa

EscribirSuperficies de efectos secundarios firmados

POST /v1/events/fireHMACSí1000 / min

POST /v1/actions/runHMACSí200 / min

POST /v1/webhooks/testHMACSí60 / min

LeerContexto, tickets e inventario de conectores

GET /v1/customers/{id}HMACSí2000 / min

GET /v1/ticketsHMACSí2000 / min

GET /v1/connectorsHMACSí2000 / min

Los límites de tasa son por clave y se devuelven en cada respuesta como X-OpsIQ-RateLimit-Remaining; exceder un límite devuelve 429 con un Retry-After encabezado. El contrato completo legible por máquina (cada punto final, esquema y error) vive en el Referencia OpenAPI 3.0.3.

Construir un conector

Envía un conector en cinco pasos.

Un conector es una carpeta autónoma. OpsIQ lo descubre, el registro conecta los eventos, y tu código específico de la plataforma nunca se filtra en el núcleo.

1Estructura una carpeta con connector.php extendiendo AbstractConnector.

2Declarar actions.json y settings.json manifiestos.

3Implementar proveedores de identidad, contexto y webhook.

4Suscríbete a los eventos que te importan.

5Fírmalo, colócalo, habilítalo en el administrador.

Prueba antes de enviar

Una clave de sandbox y un probador de webhook.

Cada espacio de trabajo expone un sandbox: una clave de alcance separado que accede a la misma superficie de API sin tocar datos de producción. Usa POST /v1/webhooks/test para disparar una entrega de muestra firmada en tu punto final y confirmar tu verificación de firma antes de ir en vivo. Las instalaciones autoalojadas ejecutan la misma ruta de código, sin desviaciones de comportamiento entre la nube y en local.

Claves de Sandbox Probador de webhook Trabajos impulsados por cron Paridad en la nube y autoalojada

Guía del conector Referencia de Webhook

Conector de datos.

clase AcmeConnector extiende AbstractConnector { función pública clave(): cadena { devolver 'acme'; } // Resolver quién es el actor función pública IDENTIFICACIÓN DE LOS PROVEEDORES () array { devolver [nuevo AcmeIdentityProvider()]; } // Alimentar datos en vivo en el aviso de IA función pública Para usar contextProviders(): array { devolver [nuevo AcmeContextProvider()]; } // Reaccionar a eventos de OpsIQ función pública Número de suscriptores(): array { devolver ['invoice. paid' => [nuevo BillingMirror()]]; } // Recibir webhooks entrantes de Acme función pública handleWebhook(array $body): vacío { /* … */ } }

⚖️ Cómo se compara

OpsIQ vs un Integración de bricolaje.

Lo que una plataforma vinculada por contrato, firmada y auditada te ofrece que crear tus propios webhooks y la plomería de acciones de IA nunca podrá.

Capacidad	Crea el tuyo	OpsIQ
HMAC-signed requests & webhooks (both ways)	Hand-rolled	✓
Idempotency keys + replay protection	DIY	✓
Automatic back-off retries with delivery IDs	DIY queue	✓
Action-contract registry (AI can't invent calls)	—	✓
Confirmation policy before side-effects	—	✓
100% audit-log coverage on actions	Manual logging	✓
Official PHP / Node / Python SDKs	Write your own	✓
OpenAPI 3.0.3 machine-readable contract	Maybe	✓
Sandbox keys + webhook tester	Build a staging rig	✓
Cloud & self-hosted parity (same code path)	Varía	✓
Connector pattern: platform code stays isolated	—	✓

FAQ

Preguntas de desarrollador, respondido.

Autenticación, firmas, SDKs, sandboxing y el modelo de conector: todo lo que preguntarás antes de la primera solicitud.

Las llamadas a la API se autentican con una única clave Bearer con alcance: enviar Authorization: Bearer opq_…. OpsIQ verifica el alcance de la clave y el rol del actor antes de que se ejecute cualquier cosa. Los webhooks son separados: cada webhook que envía OpsIQ lleva un X-OpsIQ-Signature (un HMAC-SHA256 hexadecimal del cuerpo sin procesar) y un X-OpsIQ-Timestamp para protección contra reproducción, para que puedas verificarnos a cambio, y los webhooks entrantes que envías se verifican de la misma manera.

No. La AI solo puede proponer acciones que existen en tu registro de contratos de acción. No puede inventar una llamada. Cada contrato declara las superficies, roles y parámetros permitidos, y cualquier acción marcada requires_confirmation muestra una tarjeta de vista previa a un humano antes de que se ejecute el efecto secundario.

Recalcular hash_hmac('sha256', $rawBody, $secret) (un resumen hexadecimal sin prefijo) y compáralo con el X-OpsIQ-Signature encabezado con una verificación de tiempo constante (hash_equals). Cada entrega también lleva una marca de tiempo, una clave de idempotencia y un ID de entrega que puedes rastrear. El fragmento de PHP en esta página es toda la verificación.

Las entregas que no devuelven un 200 se reintentan con retroceso exponencial, cada una llevando la misma clave de idempotencia para que una entrega reintentada nunca actúe dos veces. Puedes rastrear cada intento por ID de entrega en el administrador o en tus registros.

SDK oficiales para PHP 8.4+, Node.js 18+ y Python 3.10+ manejan la firma, reintentos, claves de idempotencia y respuestas tipadas. Son envolturas delgadas alrededor de la superficie REST, por lo que también puedes generar tu propio cliente a partir del contrato publicado OpenAPI 3.0.3 o llamar a la API directamente.

Sí. Cada espacio de trabajo expone un sandbox con su propia clave restringida que accede a la misma superficie de API sin tocar datos de producción, además POST /v1/webhooks/test para enviar una entrega de muestra firmada a tu punto final y confirmar tu verificación antes de salir en vivo.

Sí. Las instalaciones autoalojadas ejecutan la misma ruta de código (la misma firma, el mismo registro de conectores, el mismo contrato de OpenAPI) por lo que no hay desviación de comportamiento entre la nube y en las instalaciones.

Un conector es una carpeta autónoma con una clase PHP que extiende AbstractConnector, más actions.json y settings.json se manifiestan. Tú implementas identityProviders(), contextProviders(), registerActions(), subscribers() y handleWebhook(). OpsIQ lo descubre automáticamente, conecta los eventos y mantiene tu código específico de la plataforma limpiamente separado del núcleo.