Plataforma de desenvolvimento · Geral API · Webhooks · conectores

Faça sua plataforma - Al-operável.

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.

Obter uma chave API Leia os documentos Contrato OpenAPI

Chaves de portador com escopo2,415 contract actionsOpenAPI 3.0.3 + PostmanEntrega do Webhook HMAC

Pedido ao abrigo do disposto no artigo 4. o, n. o 1, alínea b),

Webhook assinado para fora → 200 OK

Vivo

2,415nomeado General API ações

69Âmbitos de aplicação do princípio da não-privilégio

dry_runvalidar os contratos de escrita antes da execução

24hreplay de gravação idempotent- bem sucedido

O ciclo de vida do pedido

Pedido de acesso. O evento foi assinado.

POSTE uma ação para /api/v1.php com uma chave de portador escopo. OpsIQ fixa o espaço de trabalho, valida o contrato de ação e permissões, então executa ou roda a seco. Eventos canônicos assinados saem através de uma fila de entrega assinada pelo HMAC com tentativas rastreáveis e repetições limitadas.

HMAC-SHA256 - a entrada e saída das cargas de carga da rede são assinadas sobre o corpo bruto; API chamadas autenticar com uma chave de portador escopo.

Repetições automáticas - as entregas falharam e tenta novamente, com uma identificação de entrega que podes localizar.

Gravações de segurança para repetição - as escritas idempotent bem sucedidas retornam a mesma resposta para 24 horas; duplicatas simultâneas compartilham uma reivindicação.

01 Pedido do portador 02 espaço de trabalho do pino 03 validar contrato 04 executar ou correr a seco 05 evento assinado em fila

Início rápido

Da chave à integração governada em três passos.

Emitir uma chave de menos privilégio, descobrir o contrato gerado, executar seco uma escrita e, em seguida, assinar um webhook quando sua aplicação precisa de entrega de eventos de fundo.

Consola de contratoLigado

Executardry_run → escrita aprovada, mesmo contrato

Obter uma chave

Inscreva-se e gere um portador escopo API chave (opq_…) em configurações de desenvolvedor, e dar a cada integração apenas as superfícies que ele precisa.

Descobrir e validar

Ler meta.actions, meta.action e meta.scopes; utilização dry_run para validar as gravações antes da execução.

Executar & assinar

Adicione uma chave de indempotência para escrever, e então subscreva seu ponto final para os eventos canônicos que sua aplicação precisa.

Como se encaixa

Um padrão de conector. Cinco primitivos limpos.

Qualquer coisa específica de plataforma vive em um conector. O núcleo OpsIQ permanece genérico, a IA permanece previsível e sua integração permanece auditável.

Gatilhos

Diga a OpsIQ o que aconteceu.

Emita eventos canônicos de sua plataforma ou defina um evento personalizado governado. Os assinantes recebem o evento através das regras de prioridade e entrega registradas.

Referência do evento

Eventos Universal + personalizadosinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up Ou a tua própria. Assinantes de fan-outO cérebro IA, as regras de automação, os conectores de espelho e os seus terminais webhook todos reagem. Ordem de prioridadeEnvio determinístico para que os espelhos escrevam antes de alertar o fogo.

02 / Contratos de acção

Informe OpsIQ o que a IA pode fazer.

Cada operação nomeada recebe um contrato gerado: escopo, recurso, tipo de leitura ou escrita, risco, política de confirmação, esquema de solicitação e resposta, suporte a seco, indempotência e erros estáveis.

Esquema de ação

A IA não pode inventar acções.Só pode pedir para executar os que você registrou. Política de confirmaçãoAções arriscadas desencadeiam um cartão de pré-visualização antes de qualquer efeito colateral. Papel + revestimento de superfícieCada ação declara os papéis e superfícies permitidos para executá-lo.

contrato de ação gerado · 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"] }
}

03 / Webhooks assinados

Empurre os eventos para sua pilha - com prova 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.

Protecção de repetiçãoID de entrega rastreável5-step back-off

Referência do 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 / Kits de desenvolvimento

Use HTTP direto ou gere o cliente que você preferir.

O General completoAPI é publicado como OpenAPI 3.0.3 e Postman. remetentes de referência PHP mais clientes de integração Node e Python cobrem eventos assinados e fluxos webhook; qualquer pilha pode chamar o mesmo JSON superfície de ação diretamente.

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

JSON HTTP diretoOpenAPI 3.0.3Colecção de correiosAjudantes de integração

05 / O padrão de conector

Conectar uma vez, ligar qualquer coisa.

Um conector é um pacote governado gerado ou importado através de Identidade, Auth, Test, Actions, Triggers and Review. Seu manifesto declara as superfícies de capacidade OpsIQ é permitido expor.

Abra o Construtor de seis estágios

Seis etapas guiadasIdentidade, Auth, Teste, Ações, Gatilhos e Revisão manter a geração de pacotes explicável. Com base em contratos8 profiles and 57 capability types declare the surfaces a package implements. Data de validadeOs controlos de segurança, proveniência e conformidade são efectuados antes de uma embalagem ser tratada como pronta.

Da intenção à ação segura

- Inglês puro. Operação auditada desligada.

OpsIQ nunca inventa a chamada certa. Ele percorre os contratos registrados, prepara a carga útil, pede confirmação quando a ação requer, e produz uma linha de auditoria completa quando executa, então uma IA que pode ato Nunca se torna uma IA em que não se possa confiar.

Condicionamento de contrato. A IA só propõe acções que registaste.

Confirmar antes dos efeitos secundários. As ações arriscadas surgem primeiro uma placa de pré-visualização.

Retirada total. Cada resultado de resposta, ação e pronto capturado em AI History.

Ver o esquema de ação

4 passosintention → auditoria

HMACassinado antes de executar

Nenhuma chamada inventadaApenas registo de contratos

Confirmar- expiradoantevisão antes dos efeitos secundários

Solicitar o seguimentoator + contrato + resultado

Referência

API superfície de relance.

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.

Referência do OpenAPI 3.0.3

AcçãoAuthEscreva segurançaLimite

Gravar acçõesPOST /api/v1.php · contrato validado

ACTION tickets.replytickets.writedry_run + idempotênciaConfigurado / hora

ACTION security.reportsecurity.writedry_run + idempotênciaConfigurado / hora

ACTION platform.routes.writeadministradorconfirmação + chaveConfigurado / hora

Ler as acções de & descobertaMesma superfície POST · envelopes estáveis

ACTION meta.actionsDescoberta públicaApenas leituraConfigurado / hora

ACTION tickets.listtickets.readApenas leituraConfigurado / hora

ACTION connectors.listconnectors.readApenas leituraConfigurado / hora

Acções do PeopleOS RHCurado hr.* Contratos · hr.read / hr.write âmbitos de aplicação

ACTION hr.people.listhr.readApenas leituraConfigurado / hora

ACTION hr.people.createhr.writedry_run + idempotênciaConfigurado / hora

ACTION hr.org.treehr.readApenas leituraConfigurado / hora

O PeopleOS HR não envia eventos de webhook RH para fora. Alcance-o através da mesma superfície POST, ou subscreva os eventos que outros módulos publicam. Referência completa: PeopleOS API e conectores e a Seção do PeopleOS da referência de desenvolvedor. O módulo é direito fechado, então uma chave sem hr recebe uma recusa, não uma lista vazia. O que é o PeopleOS HR.

Os limites de taxa são configurados por chave numa janela horária. Responses expone X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; um pedido rejeitado retorna 429 com Retry-After. Utilizar o Contrato OpenAPI 3.0.3 ou Colecção de correios gerado a partir dos mesmos registos em tempo de execução.

Construir um conector

Compilar, testar e libertar seis etapas.

Comece a partir de um perfil governado ou defina o contrato você mesmo. O Construtor valida cada etapa antes que ele gere um pacote de conectores auto-suficiente.

1Identidade. Nome, bala, perfil e superfícies de capacidade declaradas.

2Auth. API chave, Bearer, Basic, OAuth 2.0, HMAC ou um cliente personalizado.

3Teste. Validar as configurações de conexão delimitadas antes da embalagem.

4Acções. Mapa de operações, parâmetros, escopos e risco.

5Ativadores. Declare eventos de entrada, webhooks, votação e comportamento de sincronização.

6Revisão. Inspecione o contrato gerado e passe a porta de liberação.

Teste antes de enviar

Validar com segurança, e depois passar o portão de libertação.

Utilização dry_run em ações de escrita suportadas, execute o teste de conexão limitado do Construtor e inspecione o manifesto gerado e contrato antes da liberação. Os funcionários de fundo lidam com pesquisas reativas e entrega de saída.

Gravações de corrida a seco Ensaio de ligação delimitado Conformidade do contrato Entrega a Cron

Abrir o Construtor de Conectores Referência do Webhook

connector. php · php

classe AcmeConnector amplia AbstractConnector { função pública slush (): string { retorno 'acme'; } função pública nome (): string { retorno Acme.; } função pública description(): string { retorno Ponte Acme.; } // Use nomes do ConnectorContract função pública recursos (): array { retorno ['acções', 'webhook']; } função pública settingsSchema (): array { retorno [['key' => 'Token', «tipo» => 'senha']]; } função pública ensaioConexão(array $settings): array { retorno ['sucesso' => verdadeiro]; } função pública manusearWebhook ( array $payload, array $headers, array $settings ): array { retorno ['sucesso' => verdadeiro]; } }

01 · Connector contract 2.4

Um pacote não pode reclamar uma capacidade O seu código não tem.

OpsIQ\Connectors\ConnectorContract é a autoridade. A descoberta de tempo de execução, o Construtor, pacotes de primeira parte, conformidade, o Geral API e cada referência leram esse registro. Declare uma capacidade e três arquivos têm que concordar um com o outro antes de OpsIQ roteia uma única linha para você.

FIG. 01pacote de conectores, manifesto de peças scale 1:1 · contract 2.4

01 connector.php a classe de tempo de execução
02 IdentityProvider.php chave externa estável
03 SalesIngest.php conciliaSales ()
04 actions.json operações nomeadas
05 settings.json configuração do operador
06 connector_contract.json autoridade legível por máquina

07 signature.json uma HMAC sobre um SHA-256 de cada ficheiro acima, mais uma prova de origem ed25519

Matriz de capacidade all 57, as registered

ações gatilhos webhook journey_events contexto guest_lookup identidade sales sales_reconciliation faturamento payments comércio 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 isto site_intelligence análise comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

gerado 30 declarativo 20 extensão 7

Duas assinaturas, duas perguntas.

hmac-sha256 sobre uma carga determinística de SHA-256 respostas hashes foi modificado desde a assinatura. An ed25519 respostas de assinatura foi assinado por Nabtech, verificável com a chave pública empacotada e sem segredo compartilhado. Editar um byte e o primeiro pára de corresponder.

marketplace.json está fora da assinatura por definição: o instalador escreve-a após a assinatura, de modo que o editor nunca poderia ter assinado.

02 · tools/mutação_proof. php

Um guarda que nunca falhou não está provado.

Testes verdes não dizem nada quebrado hoje. Eles não dizem que o guarda que você escreveu iria parar a coisa que foi escrito para parar, porque um guarda que nunca é exercido passa exatamente como um guarda, que não faz nada. Então nós paramos seu coração de propósito, e exigir que o monitor grita.

guarda · papel lido deve recusar uma operação destrutiva CH1 verify_commerce_contracts

src/Connectors/CommerceRoleMapVerifier.php MUTADO

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. uma é necessária uma correspondência textual. Zero correspondências, ou duas, e a prova pára antes que possa 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.

Uma prova falhada é nunca Provas de que um cheque correu mal não são provas de que o guarda trabalha.

A mutação nunca se aplicava.

O texto da pesquisa não correspondeu, o arquivo foi intocado, a suíte passou, e a prova gravada verde sob o código antigo sobre o código que nunca foi antigo. Capturado por exigir exatamente uma correspondência textual e comparar hashes arquivo de ambos os lados.

A mutação quebrou outra coisa.

A suite ficou vermelha porque o arquivo parou de analisar ou a bootstrap morreu, e a prova registrou um vermelho que não tinha nada a ver com o guarda. nomeado teste entre as falhas.

Não pode deixar um mutante no disco.

Cada mutação copia o original para um sidecar fora da árvore servida na web, escreve um marcador que nomeia a alteração notável e é desfeito por um manipulador de desligamento em cada caminho de saída. Um marcador de uma execução falhada é honrado antes da próxima mutação desse arquivo.

03 · Conformidade

Certificação é um comando com um código de saída.

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/ cobrir configurações, ações, especificações do Construtor, mapeamentos de eventos de viagem e comércio, receitas de fluxo de trabalho, contratos de conectores e manifestos de lançamento.

manifests analisar e concordar entre si
capacidades existem na classe de execução
interfaces implementados quando declarados
files todos os ficheiros necessários presentes
ações corresponde ao manifesto de ações
destructive declarar confirmação
identidade uma chave externa estável, não um e- mail
repetir uma atualização repetida, nunca duplica
empresa as declarações correspondem à extensão
Documentos LEIA, DESENVOLVIMENTO, MUDANÇA
esquema cada JSON valida

sair 0 acme: conformant against contract 2.4 Uma suite falha, nomeia o cheque e o ficheiro.

$ 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

Aponte o primeiro numa conta real de não-produção com --live-settings=/secure/test-acme.json. Enquanto você ainda está iterando, troque o último por --unsigned-ok: trata uma assinatura perdida como um aviso esperado em vez de fingir que está bem.

04 · Commerce_roles.json

Declarar o que pode vender é um ficheiro, não um registo.

Um conector que pode vender declara qual de sua própria operações respondem às funções de comércio canónico OpsIQ. A presença do ficheiro é a reivindicação. Aparece nas configurações de venda no momento em que declara e desaparece quando pára. Não há lista para juntar e ninguém para perguntar.

papel canónico commerce_roles.json sua operação

RECUSA

Um canônico escrever role mapeou para uma gravação de registro genérica. A correspondência é estrutural: um substantivo de armazenamento ao lado de um verbo mutante, seja qual for a sua convenção de nomeação. Escrever a linha de negócios diretamente ignora os preços da plataforma, a disponibilidade do bloqueio e o correio de confirmação, e produz uma ordem em que o próprio sistema do comerciante só acredita metade. Não recovery Ou, então um intervalo seria irrecuperável.

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

O seu próprio ficheiro de propósito: connector_contract.json é gerado e seus conjuntos de esquema additionalProperties:false, então um bloco escrito à mão lá iria falhar validação e depois ser substituído na próxima execução do gerador.

Vocabulário fechado

Um papel que não está em CommerceRole não existe. OpsIQ nunca inferes um de um nome de operação, porque um nome não é uma promessa.

A tua própria acção

A operação deve aparecer no seu actions.jsonDeclarar um que não existe promete ao cliente algo que então produz nada.

Gravações declarar recuperação

O tempo de descanso mais perigoso é o depois que a plataforma já pode ter feito o trabalho. Sem um "fazer minha escrita terra" procura, as únicas opções são retry blind ou perder a ordem.

As funções de pagamento certificam

Qualquer função de classe de pagamento também declara payment_profile com a ambiente, webhook_verify Utilização do regime próprio do prestador, e event_map. Um ambiente não declarado é como um provedor de modo teste faz um pagamento ao vivo.

O Construtor valida estes à medida que você digita e o verificador valida o pacote enviado. Ambos chamam as mesmas funções, de modo que não podem discordar.

⚖️ Como se compara

OpsIQ vs a Integração de DY.

Que uma plataforma de contrato, assinada e auditada, dá-lhe que rolar os seus próprios webhooks e canalização IA-ação nunca irá.

Capacidade	Rola o teu próprio	OpsIQ
Carregador de alcance API + Webhooks assinados por HMAC	Laminados à mão	✓
Gravações de corrida a seco + 24- hora replay bem sucedido	DIY	✓
1m → 5m → 30m →2h → 12h retries	Fila DIY	✓
Registro de contrato de ação (AI não pode inventar chamadas)	—	✓
Política de confirmação antes dos efeitos secundários	—	✓
Envelope de erro estável + IDs de solicitação	Registo manual	✓
Opções diretas de HTTP + cliente gerado	Escreva o seu próprio	✓
Contrato legível por máquina OpenAPI 3.0.3	Talvez.	✓
Construtor de seis estágios + pacote portão de liberação	Compilar uma cadeia de ferramentas	✓
Teclas e limites horários com o espaço de trabalho	Variações	✓
Padrão do conector: o código da plataforma permanece isolado	—	✓

FAQ

Perguntas de desenvolvimento, - Não.

Autenticação, contratos, repetições, geração de clientes, testes seguros e o modelo de conectores, antes da primeira solicitação de produção.

Chamadas gerais API enviar Authorization: Bearer opq_…. Chaves podem ser irrestritas, restritas ou somente leitura, transportar escopos menos privilegiados, obedecer a um limite de hora e pode ser fixado a uma área de trabalho. Webhook assinatura é separada: entregas enviadas levar X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event e X-OpsIQ-Delivery.

Não. O IA só pode propor operações nomeadas no registro de ação. Cada contrato gerado declara escopo, campos de solicitação, política de risco e confirmação; operações cuja política requer confirmação emergem uma visualização humana antes da execução.

Recomputar hash_hmac('sha256', $rawBody, $secret) e comparar sua digest X-OpsIQ-Signature usando hash_equals. Validar X-OpsIQ-Timestamp dentro da sua janela de repetição e usar X-OpsIQ-Delivery como identificador de entrega rastreável.

Uma tentativa não- bem sucedida entra na fila de entrega do fundo. OpsIQ Reacções sobre a1- minuto, 5- minuto, 30- minuto,2- hora e 12- escada de horas enquanto retém o identificador de entrega e tentativa de histórico para diagnósticos.

Chamar o JSON superfície de ação diretamente, importar a coleção gerada Postman, ou gerar um cliente do OpenAPI 3.0.3. Senders de referência PHP e clientes de integração Node/Python suportam eventos e fluxos webhook; eles são ajudantes em vez de separadosAPI Contratos.

Utilização dry_run em ações cujo contrato gerado o suporta, execute o teste de conexão limitado do Connector Builder, inspecione seus arquivos gerados e passe as portas de conformidade e liberação do pacote antes de tratar o conector como pronto.

A versão instalada gera a sua API e contratos de conectores de seus próprios registros em tempo de execução. URL, segredos, armazenamento e cron/workers, então o comportamento deve ser verificado contra a versão instalada em vez de assumido a partir de um ambiente de nuvem.

Um conector é um pacote governado contendo o adaptador, settings.json, facultativo actions.json, um contrato de capacidade gerado, documentação e extensões empresariais opcionais. O Construtor de seis estágios monta-o; o registro descobre-o, a conformidade e as portas de liberação validam-no.