Plataforma de desarrollo · General API · webhooks · conectores

Haz que tu plataforma sea operable con IA.

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.

Obtén una clave API Lee la documentación Contrato de OpenAPI

Llaves de oso de escocia2,415 contract actionsOpenAPI 3.0.3+ PostmanEntrega de ganchos web HMAC

Solicitud de recogida en

Webhook firmado fuera → 200 OK

En vivo

2,415llamado General API

69alcances de la mayoría de los derechos

dry_runvalidar los contratos de escritura antes de la ejecución

24 héxito idempotent-write replay

El ciclo de vida de la solicitud

Solicitud de ayuda. Se ha firmado el evento.

PUEDE una acción para /api/v1.php con una llave de Bearer.OpsIQfija el espacio de trabajo, valida el contrato de acción y los permisos, luego lo ejecuta o seca. Suscritos eventos canónicos salen a través de un HMAC- la cola de entrega firmada con intentos rastreables y retretes encuadernados.

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.

Replay-safe escribe - exitoso idempotent escribe devolver la misma respuesta para 24 horas; duplicados simultáneos comparten una reclamación.

01 Solicitud de portador 02 pin workspace 03 validar el contrato 04 ejecutada o seca 05 evento firmado por la oficina

Inicio rápido

De la clave a la integración gobernada en tres pasos.

Ejecute una clave de mínimo privilegio, descubra el contrato generado, haga secar un escrito y luego suscriba un webhook cuando su aplicación necesite entrega de eventos de fondo.

Consola de contratoConectado

Ejecutardry_run → aprobado escribir, mismo contrato

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.

Descubre " validate

Leer meta.actions, meta.action y meta.scopes; uso dry_run para validar escribe antes de la ejecución.

Ejecutar " suscribirse

Agregue una clave de idempotencia para escribir, luego suscriba su punto final a los eventos canónicos que necesita su aplicación.

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.

Emitir eventos canónicos desde su plataforma, o definir un evento personalizado gobernado. Los suscriptores reciben el evento a través de la prioridad registrada y reglas de entrega.

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.

Cada operación llamada recibe un contrato generado: alcance, funcionalidad, lectura o escritura tipo, riesgo, política de confirmación, esquema de solicitud y respuesta, soporte de gestión seca, idempotencia y errores estables.

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 generado · 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. Cambios

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

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.

Protección de repeticiónID de entrega rastreable5-step back-off

Referencia de Webhook

verificar 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

Utilice HTTP directo o genere el cliente que prefiera.

El General completoAPI se publica como OpenAPI 3.0.3 y Postman. Envíos de referencia PHP más Node y Python integración clientes cubren los flujos firmados del evento y Webhook; cualquier pila puede llamar la misma JSON superficie de acción directamente.

ejemplos de clientes

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

Directo JSON HTTPOpenAPI3.0.3Colección de cartelesAyudantes de integración

05 / El patrón de conector

Construye una vez. Conéctate a cualquier cosa.

Un conector es un paquete gobernado generado o importado a través de la Identidad, Auth, Test, Actions, Triggers y Review. OpsIQ se permite exponer.

Abra el Constructor de seis etapas

Seis etapas guiadasIdentidad, Auth, Test, Acciones, Ataques y Revisión mantienen la generación de paquetes explicable. Contrato impulsado8 profiles and 57 capability types declare the surfaces a package implements. LiberadoControles de seguridad, procedencia y conformidad corren antes de que un paquete se trate como listo.

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

Solicitud de trazaactor + contrato + resultado

Referencia

Superficie de API De un vistazo.

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.

Referencia OpenAPI 3.0.3

AcciónAutenticaciónEscribir seguridadLímite

Acciones de escrituraPOST /api/v1.php · Contrato validado

ACTION tickets.replytickets.writeseca_run + idempotenciaConfigurado / hora

ACTION security.reportsecurity.writeseca_run + idempotenciaConfigurado / hora

ACTION platform.routes.writeadministradorconfirmación + claveConfigurado / hora

Leer " Acciones de descubrimiento &quotMismo superficie de POST · sobres estables

ACTION meta.actionsPublic discoverySolo lecturaConfigurado / hora

ACTION tickets.listtickets.readSolo lecturaConfigurado / hora

ACTION connectors.listconnectors.readSolo lecturaConfigurado / hora

Medidas de recursos humanosCurado hr.* Contratos hr.read / hr.write alcances

ACTION hr.people.listhr.readSolo lecturaConfigurado / hora

ACTION hr.people.createhr.writeseca_run + idempotenciaConfigurado / hora

ACTION hr.org.treehr.readSolo lecturaConfigurado / hora

PeopleOS HR no envía eventos de rebote RRHHH. Alcanzarla a través de la misma superficie POST, o suscribirse a los eventos otros módulos publican. Referencia completa: PeopleOS API y conectores y el Sección de PeopleOS del programador referencia. El módulo es el derecho cerrado, por lo que una llave sin hr se niega, no una lista vacía. Lo que es Recursos Humanos de PeopleOS.

Los límites de tarifas se configuran por llave en una ventana horaria. X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; una solicitud rechazada devuelve 429 con Retry-After. Uso de Contrato OpenAPI 3.0.3 o Colección de carteles generados por los mismos registros de tiempo de ejecución.

Construir un conector

Construir, probar y soltar en seis etapas.

Comience desde un perfil gobernado o defina el contrato usted mismo. El Constructor valida cada etapa antes de generar un paquete de conector autocontenido.

1Identidad. Nombre, pergamino, perfil y superficies de capacidad declaradas.

2Auth. API llave, Bearer, Basic, OAuth 2.0, HMAC o un cliente personalizado.

3Prueba. Validar los ajustes de conexión atados antes del embalaje.

4Acciones. Mapa denominado operaciones, parámetros, alcances y riesgo.

5Los desencadenantes. Declarar eventos inbound, webhooks, encuestas y comportamiento de sincronización.

6Revisión. Inspeccione el contrato generado y pase la puerta de liberación.

Prueba antes de enviar

Validar con seguridad, luego pasar la puerta de liberación.

Uso dry_run sobre acciones de escritura soportadas, ejecutar la prueba de conexión atada del Builder e inspeccionar el manifiesto generado y contrato antes de la liberación. Verificación de paquetes nombres de capacidades, ajustes, procedencia y archivos requeridos; trabajadores de antecedentes manejan encuesta reactiva y entrega outbound.

Dry-run escribe Prueba de conexión contuida Conformidad contractual Entrega impulsada por el hierro

Open Connector Builder Referencia de Webhook

Conector de datos.

clase AcmeConnector extiende AbstractConnector { función pública slug(): cadena { devolver 'acme'; } función pública Nombre(): cadena { devolver 'Acme'; } función pública descripción(): cadena { devolver "Acme bridge"; } // Usar nombres de ConnectorContract función pública capacidades(): array { devolver ["acciones", 'webhook']; } función pública settingsSchema(): array { devolver [['key' => 'token', 'tipo' => 'palabra']]; } función pública testConnection(es)array $settings): array { devolver ['success' => verdadero]; } función pública handleWebhook( array $payload, array $headers, array $settings ): array { devolver ['success' => verdadero]; } }

01 · Connector contract 2.4

Un paquete no puede reclamar una capacidad su código no tiene.

OpsIQ\Connectors\ConnectorContract es la autoridad. El descubrimiento de tiempo de ejecución, el Constructor, paquetes de primera parte, conformidad, el General API y todas las referencias leen que un registro. Declarar una capacidad y tres archivos tienen que estar de acuerdo entre sí antes OpsIQ te lleva una sola fila.

FIG. 01paquete de conector, partes manifiestas scale 1:1 · contract 2.4

01 connector.php la clase de tiempo de ejecución
02 IdentityProvider.php llave externa estable
03 SalesIngest.php reconciliSales()
04 actions.json operaciones llamadas
05 settings.json Configuración del operador
06 connector_contract.json autoridad legible por máquina

07 signature.json uno HMAC sobre un SHA-256 de cada archivo arriba, más una prueba de origen ed25519

Matriz de capacidad all 57, as registered

acciones disparadores webhook journey_events context guest_lookup identidad sales sales_reconciliation facturación payments comercio 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 local esto site_intelligence analgésicos comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

generados 30 declarativo 20 extensión 7

Dos firmas, dos preguntas.

hmac-sha256 sobre una carga de pago determinista del fichero SHA-256 hahes respuestas ha sido modificado desde la firma. An ed25519 Respuestas de firma fue firmado por Nabtech, verificable con la llave pública enganchada y sin secretos compartidos. Editar un byte y las primeras paradas coincidentes.

marketplace.json está fuera de la firma por definición: el instalador lo escribe después de firmar, así que el editor nunca pudo haber firmado.

02 · herramientas/mutation_proof.php

Un guardia que nunca ha fallado no está probado.

Las pruebas verdes no te dicen nada quebrado hoy. Ellos no te cuentan que el guardia que escribiste pararía lo que estaba escrito para detener, porque un guardia que nunca se ejerce pasa exactamente como un guardia sin hacer nada. Así que detenemos su corazón a propósito, y exigimos que el monitor grita.

· El papel de lectura debe rechazar una operación destructiva 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    }

Exactamente. uno Se requiere un partido textual. Cero partidos, o dos, y la prueba se detiene antes de que pueda 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.

Una prueba fallida es nunca jamás La evidencia de que un cheque salió mal no es prueba de que funciona un guardia.

La mutación nunca se aplicó.

El texto de búsqueda no coincidió, el archivo fue sin tocar, la suite pasó, y la prueba grabada verde bajo el código antiguo sobre el código que nunca era viejo. Trajo por requerir exactamente un partido textual y comparar los hashes de archivo a ambos lados.

La mutación rompió algo más.

La suite se puso roja porque el archivo dejó de parir o la bota murió, y la prueba grabó un rojo que no tenía nada que ver con la guardia. Atrapado por forro del mutante y requerir el llamado prueba entre los fracasos.

No puede dejar un mutante en el disco.

Cada mutación copia el original a un sidecar fuera del árbol de la web, escribe un marcador que nombra el cambio pendiente, y es deshecho por un controlador de apagado en cada pista de salida. Un marcador de una carrera bloqueada se honra antes de la siguiente mutación de ese archivo.

03 · Conformance

La certificación es un comando con un código de salida.

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/ cubierta configuración, acciones, Especies de Constructor, mapeos de eventos de viaje y comercio, recetas de flujo de trabajo, contratos de conexión y manifiestos de liberación.

manifests parse y estar de acuerdo con el otro
capacidades existen en la clase de tiempo de ejecución
interfaces aplicadas cuando se declara
files cada archivo requerido presente
acciones coinciden con las acciones manifiestas
destructive Confirmación
identidad una llave externa estable, no email
Replay una actualización de repetición, nunca duplica
empresa declaraciones coinciden con la extensión
docs README, DEVELOPER, CHANGELOG
schemas cada uno JSON validados

Salida 0 acme: conformant against contract 2.4 Una suite fallando nombra el cheque y el archivo.

$ 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

Ponga el primero en una cuenta real de no producción con --live-settings=/secure/test-acme.jsonMientras todavía estás iterando, cambia el último para --unsigned-ok: trata a una firma desaparecida como una advertencia esperada en lugar de fingir que está bien.

04 · trade_roles.json

Declarando lo que puedes vender es un archivo, no una inscripción.

Un conector que puede vender declara cuál de su propia respuesta de operaciones OpsIQ_ los papeles del comercio canónico. La presencia del archivo es la reclamación. Se aparece en los ajustes de venta el momento que declara y desaparece cuando se para. No hay lista para unirse y nadie para preguntar.

función canónica commerce_roles.json su operación

REFUSADA

Un canónico escribir El partido es estructural: un sustantivo de almacenamiento junto a un verbo mutante, cualquiera que sea su convención de nombres. Escribir la fila de negocios directamente salta el precio de la plataforma, bloqueo de disponibilidad y correo de confirmación, y produce una orden en la que el propio sistema del comerciante sólo cree en la mitad. recovery o bien, un tiempo fuera sería incontable.

commerce_roles.jsonVALID

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

Su propio archivo a propósito: connector_contract.json se genera y sus conjuntos de esquema additionalProperties:false, por lo que un bloque autorizado a mano no sería validación y luego se sobrescribe en la siguiente carrera generador.

Vocabulario cerrado

Un papel que no se CommerceRole no existe. OpsIQ nunca infiere uno de un nombre de operación, porque un nombre no es una promesa.

Tu propia acción

La operación debe aparecer en su actions.json. Declarar uno que no existe promete al cliente algo que entonces no produce nada.

Escribe que la recuperación

El tiempo más peligroso es el que después de la plataforma ya pudo haber hecho el trabajo. Sin una búsqueda "did my write land" idempotent, las únicas opciones son retry ciega o perder el orden.

Funciones de pago certificar

Toda función de clase de pago también declara payment_profile con el medio ambiente, webhook_verify usando el propio esquema del proveedor, y event_mapUn entorno no declarado es cómo un proveedor de pruebas toma un pago en vivo.

El Constructor valida estos como usted escribe y el verificador valida el paquete enviado. Ambos llaman las mismas funciones, por lo que no pueden discrepar.

⚖️ 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
Bearer escocido API + HMAC-signed webhooks	Matrículas de mano	✓
Dry-run escribe + 24_h de reproducción exitosa	DIY	✓
1m → 5m → 30m →2h → 12h retries	DIY queue	✓
Registro de contrato de acción (AI no puede inventar llamadas)	—	✓
Política de confirmación antes de efectos secundarios	—	✓
Sobre de error estable + ID de solicitud	Registro manual	✓
HTTP directo + opciones de cliente generadas	Escribe tu propio	✓
OpenAPI 3.0.3 contrato legible por máquina	Tal vez	✓
Constructor de seis etapas + puerta de lanzamiento de paquete	Construir una cadena de herramientas	✓
teclas de trabajo y límites horales	Varía	✓
Patrón de conexión: código de plataforma permanece aislado	—	✓

FAQ

Preguntas de desarrollador, respondido.

Autenticación, contratos, retries, generación de clientes, pruebas seguras y modelo de conectores, antes de la primera solicitud de producción.

General API Authorization: Bearer opq_…Las claves pueden ser restringidas, restringida o sólo lectura, portar los alcances de la menor privilegio, obedecer un límite horaria y puede ser clavada a un espacio de trabajo. La firma Webhook es separada: las entregas en salida X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event y X-OpsIQ-Delivery.

No. La AI sólo puede proponer operaciones nombradas en el registro de acción. Cada contrato generado declara alcance, campos de solicitud, política de riesgo y confirmación; operaciones cuya política requiere superficie de confirmación una vista previa humana antes de la ejecución.

Recalcular hash_hmac('sha256', $rawBody, $secret) y comparar su hexadecimal digest con X-OpsIQ-Signature utilizando hash_equalsValidación X-OpsIQ-Timestamp dentro de su ventana de reproducción y uso X-OpsIQ-Delivery como el identificador de entrega rastreable.

Un intento no exitoso entra en la cola de entrega de antecedentes. OpsIQ de la historia1- minuto. 5- minuto. 30- minuto.2- Hora y hora 12- escalera de hora mientras retiene el identificador de entrega e intenta historia para diagnóstico.

Llama a la JSON superficie de acción directamente, importar la colección de Postman generada o generar un cliente de OpenAPI 3.0.3. PHP remitentes y Node/Python integracion clientes soportan flujos de evento y webhook; son ayudantes en lugar de separarAPI contratos.

Uso dry_run en acciones cuyo contrato generado lo soporta, ejecutar la prueba de conexión atada del Constructor Conectador, inspeccionar sus archivos generados y pasar el paquete conformance y las puertas de liberación antes de tratar el conector como listo.

La versión instalada genera su API y contratos de conectores de sus propios registros de tiempo de ejecución. Su implementación posee su público URL, secretos, almacenamiento y cron/workers, por lo que el comportamiento debe ser verificado contra la liberación instalada en lugar de asumirlo desde un entorno nublado.

Un conector es un paquete gobernado que contiene el adaptador, settings.json, opcional actions.json, un contrato de capacidad generado, documentación y extensiones opcionales de empresa. El constructor de seis etapas lo reúne; el registro lo descubre; la conformidad y las puertas de liberación validan.