Plataforma de desenvolvimento · Geral API · Webhooks · conectores

Faça sua plataforma Al-operável.

Call 2,420 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 um API chave Leia os documentos. Contrato OpenAPI

Chaves de carregadores com escopo2,420 contract actionsOpenAPI 3.0.3 + CarteiroEntrega de hooks HMAC

Pedido de acesso.

"Teia desligada"→ 200Está bem.

Viva

2,420Chamado General. API Ações

69Esquadras de menor privilégio

dry_runValidar contratos de escrita antes da execução

24hReproduzir a escrita idempotente bem sucedida.

O ciclo de vida do pedido.

Pedido de acesso. Evento assinado.

PÓS-TACA DE UMA AÇÃO PARA /api/v1.php com uma chave de portador. OpsIQ Os eventos canônicos assinados saem através de uma fila de entrega assinada pelo HMAC com tentativas rastreáveis e repetições limitadas.

Webhooks de HMAC-SHA256 - entrada e saída de carga de ganchos são assinados sobre o corpo cru; API Chama autenticar com uma chave de portador.

Retornos automáticos - entregas com falha voltam e tentam novamente, com um ID de entrega que você pode rastrear.

Replay-safe escreve O sucesso dos textos de idempotent retorna a mesma resposta para 24 Horas, duplicatas simultâneas compartilham uma reivindicação.

01 Pedido de portador. 02 Pino espaço de trabalho 03 Validar contrato 04 executar ou correr a seco 05 evento assinado na fila

-Rápido!

Da chave para a integração governada em Três passos.

Emitindo uma chave de menos privilégio, descobrindo o contrato gerado, rodando um roteiro e depois assinando um webhook quando sua aplicação precisar de entrega de eventos.

Consola de contratoConectado.

ExecutarDry_run → Escrita aprovada, mesmo contrato

Pegue uma chave.

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

Descubra e valide

Leia meta.actions, meta.action e meta.scopes; use dry_run para validar as escritas antes da execução.

Executar e assinar

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

Como se encaixam

Um padrão de conector. Cinco primitivos limpos.

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

Gatilhos

Diga. OpsIQ O que aconteceu.

Emita eventos canônicos de sua plataforma, ou defina um evento personalizado governado.

Referência do evento

Eventos universais + personalizadosinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up Ou o seu próprio. Assinantes de fãs.O cérebro da IA, regras de automação, conectores de espelho e seus terminais de webhook todos reagem. Ordem PrioritáriaEnvio determinístico para que os espelhos escrevam antes de alertar o fogo.

02 / Contratos de ação

Diga. OpsIQ O que a IA está autorizada a fazer.

Cada operação nomeada recebe um contrato gerado: escopo, característica, leitura ou escrita tipo, risco, política de confirmação, pedido e esquema de resposta, suporte a seco, indemnidade e erros estáveis.

Esquema de ação.

A IA não pode inventar ações.Só pode pedir para executar os que você registrou. Política de confirmaçãoAções arriscadas desencadeiam um cartão antes de qualquer efeito colateral. Papel + revestimento superficialCada 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 / Anzóis assinados

Empurre os eventos para sua pilha com provas criptográficas.

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.

Reproduzir proteçãoID de entrega rastreável5-step back-off

Referência Webhook

Verifique o 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 completo.API é publicado como OpenAPI 3.0.3 E os clientes de integração do PHP, além de Node e Python, cobrem eventos assinados e fluxos webhook. 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.",
    },
)

Direto JSON HTTPOpenAPI3.0.3Colecção de carteirosAjudantes de integração

05 / O padrão do conector

Conectar qualquer coisa.

Um conector é um pacote governado gerado ou importado através de Identidade, Auth, Teste, Ações, Gatilhos e Revisão. OpsIQ É permitido expor.

Abra o construtor de seis estágios.

Seis etapas guiadasIdentidade, Auth, Teste, Ações, Gatilhos e Revisão mantêm a geração de pacotes explicáveis. -Tratado por contrato.8 profiles and 57 capability types declare the surfaces a package implements. Liberado.Segurança, proveniência e conformidade são feitas antes de um pacote ser tratado como pronto.

Da intenção à ação segura.

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

OpsIQ 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 Atue. Nunca se torna uma IA em que não se pode confiar.

Contrato-ligado. A IA só propõe ações que você registrou.

Confirme antes dos efeitos colaterais. Ações arriscadas surgem primeiro.

Relembrar totalmente. Cada resposta rápida e ação, resultado capturado na história da IA.

Veja o esquema de ação.

4 PassosIntenção → auditoria

HMACassinado antes de executar

Nenhuma chamada inventada.Apenas registro de contrato

Confirmado.Previsão antes dos efeitos colaterais

- Requisito de rastreamento.ator + contrato + resultado

Referência

API superfície em um olhar.

One JSON POST surface exposes 2,420 named actions. Each generated contract declares auth scopes, read/write kind, risk, confirmation, request schema, dry-run, idempotency and stable errors.

OpenAPI 3.0.3 Referência

Ação.Auth.Escreva segurança.Limite

Escreva ações.POST /api/v1.php · Contrato validado

ACTION tickets.replytickets.writeDryrun + IdempotênciaConfigurado / hora

ACTION security.reportsecurity.writeDryrun + IdempotênciaConfigurado / hora

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

Leia e descubra ações.Mesmo POST superfície · envelopes estáveis

ACTION meta.actionsDescoberta públicaLeia somenteConfigurado / hora

ACTION tickets.listtickets.readLeia somenteConfigurado / hora

ACTION connectors.listconnectors.readLeia somenteConfigurado / hora

Ações do PovoS HRCurado hr.* Contratos · hr.read / hr.write escopos

ACTION hr.people.listhr.readLeia somenteConfigurado / hora

ACTION hr.people.createhr.writeDryrun + IdempotênciaConfigurado / hora

ACTION hr.org.treehr.readLeia somenteConfigurado / hora

O PeopleOS HR não envia eventos de RH para fora, alcança-os pela mesma superfície do POST ou assina os eventos que outros módulos publicam. Povos.APIe conectores. e o A seção PeopleOS da referência de desenvolvedorO módulo tem direitos, então uma chave sem hr Obtém uma recusa, não uma lista vazia. O que o PeopleOS HR é.

Limites de taxa são configurados por chave em uma janela horária. X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; um pedido rejeitado retorna 429 com Retry-AfterUse o OpenAPI 3.0.3 contrato Ou Colecção de carteiros Gerados dos mesmos registros de tempo.

Construa um conector.

Construir, testar e liberar Seis estágios.

Comecem de um perfil governado ou definam o contrato, o construtor valida cada etapa antes que ele gere um pacote de conectores auto-suficiente.

1Identidade. Nome, bala, perfil e superfície declarada de capacidade.

2Auth. API Chave, Bearer, Básico, OAuth 2.0, HMAC ou um cliente personalizado.

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

4Ações. Mapa chamado operações, parâmetros, escopos e risco.

5Ativadores. Declare eventos, webhooks, pesquisas e sincronia.

6Revisão. Inspecione o contrato gerado e passe pelo portão de liberação.

Teste antes de embarcar.

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

Uso dry_run O programa de validação do pacote verifica os nomes, configurações, procedência e arquivos necessários; os trabalhadores de segundo plano lidam com pesquisas reativas e entrega de saída.

"Dry-run escreve" Teste de conexão limitado. Conformidade do contrato Entrega com o Cron

Abra o Conector Builder Referência Webhook

Connector. php · php

Classe AcmeConnector Se estende AbstractConnector { Função pública Slush(): string { Volte. 'acme'; } Função pública Nome(): string { Volte. 'Acme'; } Função pública Description(): string { Volte. Ponte Acme.; } // Use nomes do ConnectorContrate Função pública - Não, não. Array { Volte. ['Ações', 'webhook']; } Função pública SettingsSchema(): Array { Volte. [['key' => 'Token', 'tipo' => 'Passeword']]; } Função pública TesteConexão(Array $settings): Array { Volte. ['Sucesso' => Verdade.]; } Função pública - Lidar com o Webhook. Array $payload, Array $headers, Array $settings ): Array { Volte. ['Sucesso' => Verdade.]; } }

01 · Connector contract 2.4

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

OpsIQ\Connectors\ConnectorContract Descobrir o tempo de execução, o Construtor, pacotes de primeira parte, conformidade, o General API Declare uma capacidade e três arquivos têm que concordar um com o outro antes OpsIQ Roteia uma única fileira até você.

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

01 connector.php A aula de corrida.
02 IdentityProvider.php Chave externa estável
03 SalesIngest.php -ConciliarSales ()
04 actions.json Nomeadas operações.
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 arquivo 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 faturando 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 Seo. 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 por arquivo...256 Hashes responde Isso foi modificado desde que assinouUm. ed25519 Respostas de assinatura Foi assinado por NabtechEditando um byte e o primeiro pára de combinar.

marketplace.json Está fora da assinatura por definição: o instalador escreve após assinar, então o editor nunca poderia ter assinado.

02 · Ferramentas/Mutation_proof.php

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

Testes verdes não te dizem que nada quebrou hoje, e não dizem que o guarda que escreveu impediria a coisa escrita para parar, porque um guarda que nunca é exercitado passa exatamente como um guarda sem fazer nada, então paramos seu coração de propósito, e exigimos que o monitor grite.

Guarda, o papel de leitura 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    }

Exatamente. Um. Zero ou dois, e a prova para 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 fracassada é Nunca. Provas de que um cheque deu errado não são evidências de que o guarda trabalha.

A mutação nunca se aplicava.

O texto de busca não bate, o arquivo estava intacto, a suíte passou, e a prova gravada Verde sob o velho código Pegado por exigir uma combinação textual e comparar arquivos de ambos os lados.

A mutação quebrou outra coisa.

A suíte ficou vermelha porque o arquivo parou de analisar ou a armadilha 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 pela web, escreve um marcador que nomeia a mudança notável, e é desfeito por um manipulador em cada saída.

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, mapas de eventos de viagem e comércio, receitas de fluxo de trabalho, contratos de conectores e manifestos de liberação.

manifests Analisar e concordar uns com os outros.
Capacidades existem na aula de corrida.
interfaces implementado onde declarado
files Todos os arquivos necessários presentes.
Ações Equilibrar o manifesto de ações.
destructive declarar confirmação
Identidade Uma chave externa estável, não um e-mail.
Replay uma atualização repetida, nunca duplica.
empresa declarações correspondem à extensão.
Doutores. LEIA-ME, DEVELOPER, MUDANÇA
Esquemas Cada JSON valida

Saída 0 acme: conformant against contract 2.4 Uma suíte falhando nomeia o cheque e o arquivo.

$ 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 em uma conta real de não-produção com --live-settings=/secure/test-acme.jsonEnquanto você ainda está iterante, troque o último por --unsigned-okTrata uma assinatura desaparecida como um aviso esperado em vez de fingir que está bem.

04 · Commerce_roles.json

Declarando o que pode vender é um arquivo, não um registro.

Um conector que pode vender declara qual dos É sua própria operações respondem OpsIQOs papéis canônicos do comércio, a presença do arquivo é o direito... ele aparece nos locais de venda no momento em que se declara e desaparece quando para, não há lista para entrar e ninguém para perguntar.

Papel canônico commerce_roles.json Sua operação.

RECUSA

Um canônico. escrever A correspondência é estrutural, um substantivo de armazenamento ao lado de um verbo mutante, qualquer que seja 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 comercial só acredita. recovery Ou, então um tempo 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" }
    }
  }
}

Seu próprio arquivo de propósito: connector_contract.json é gerado e seus esquemas se configuram additionalProperties:falseEntão, um bloco escrito à mão iria falhar na validação e depois seria substituído no próximo gerador.

Vocabulário fechado

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

Sua própria ação.

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

Escreve declara recuperação

O tempo de descanso mais perigoso é o que depois da plataforma já pode ter feito o trabalho, sem um olhar indemponente "escrevi minha terra", as únicas opções são tentar novamente cegar ou perder a ordem.

Funções de pagamento certificam

Qualquer papel de classe de pagamento também declara payment_profile com o Ambiente, webhook_verify usando o próprio esquema do provedor, e event_mapUm ambiente não declarado é como um provedor de modo teste recebe um pagamento ao vivo.

O Construtor valida isso enquanto você digita e o verificador valida o pacote enviado.

⚖️Como se compara

OpsIQ vs um Integração de DY.

Que plataforma de contrato, assinada e auditada, dá a você que enrolar seus próprios webhooks e encanamento de IA nunca vai funcionar.

Capacidade	Role o seu próprio	OpsIQ
Portador de Escopo API + HMAC-assinado webhooks	Enrolado à mão	✓
A corrida a seco escreve: 24-Hora de replay bem sucedido	DIY	✓
1m → 5m → 30m →2h → 12h Retrocede	Fila de DIY	✓
Registro de contrato de ação (AI não pode inventar chamadas)	—	✓
Política de confirmação antes dos efeitos colaterais	—	✓
Envelope de erro estável + identidades de solicitação	Registro manual	✓
HTTP direto + opções de cliente geradas	Escreva o seu próprio	✓
OpenAPI 3.0.3 contrato legível por máquina	Talvez.	✓
Construtor de seis estágios + pacote portão de liberação	Construa uma corrente de ferramentas	✓
Chaves de espaço de trabalho e limites horários	Varias	✓
Padrão do conector: código da plataforma permanece isolado.	—	✓

FAQ

Perguntas de desenvolvedor, -Respondeu.

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

Geral. API Chamadas enviar Authorization: Bearer opq_…Chaves podem ser irrestritas, restritas ou somente leitura, carregar escopos de menor privilégio, obedecer a um limite horário e pode ser preso a uma área de trabalho. X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event e X-OpsIQ-Delivery.

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

Recomponha hash_hmac('sha256', $rawBody, $secret) e comparar sua digest hexadecimal com X-OpsIQ-Signature usando hash_equalsValidar X-OpsIQ-Timestamp dentro da sua janela de repetição e use X-OpsIQ-Delivery como o identificador de entrega rastreável.

Uma tentativa sem sucesso entra na fila de entrega do fundo. OpsIQ Retrocedendo no1-minuto, 5-minuto, 30-minuto,2- hora e... 12- Escada de horas, mantendo o identificador da entrega e tentando o histórico para diagnósticos.

Chame o JSON Action Surface diretamente, importar a coleção gerada de Postman, ou gerar um cliente do OpenAPI 3.0.3 Enviadores de referência PHP e clientes de integração Node/Python suportam eventos e fluxos webhook; eles são ajudantes ao invés de separadosAPI Contratos.

Uso dry_run em ações cujo contrato gerado o apoia, execute o teste de conexão limitado do Conector Builder, inspecione seus arquivos gerados, e passe o pacote conformação e libere portões antes de tratar o conector como pronto.

A liberação instalada gera seu API Sua implantação é dona de seu público. URL, segredos, armazenamento e cron/trabalhadores, então o comportamento deve ser verificado contra a liberação instalada em vez de assumir de um ambiente de nuvem.

Um conector é um pacote governado contendo o adaptador, settings.json, opcional actions.jsonO construtor de seis estágios o monta, o registro descobre, a conformidade e as portas de liberação validam.