[Protocolo revelado 1] Desmontando o protocolo de comunicação principal do AI Ready: carga útil da API e verificação de segurança do Webhook

Resposta direta: O protocolo AI Ready deve elevar as tarefas de IA de "um prompt" para eventos de API geríveis. Cada solicitação deve conter intenção, origem, contexto, dados, restrições e chave de idempotência; O webhook deve ter carimbo de data/hora, nonce, assinatura e proteção de reprodução.

A quem se destina este artigo?#

• Engenheiro de desenvolvimento do núcleo do sistema de e-commerce.

• Backend e arquiteto necessários para projetar API de tarefas de IA.

• Equipe técnica responsável pela segurança do webhook, retentativas e auditoria.

Por que as tarefas de IA exigem protocolos de comunicação?#

Se cada plug-in emitir um prompt para o modelo, será difícil para o sistema responder às seguintes perguntas:

• Quem desencadeou esta missão?

• Que informações a IA pode ler?

• A IA pode responder?

• Qual idioma e armazenamento são usados para a tarefa?

• Qual é o orçamento simbólico?

• É possível tentar novamente após falhar?

• Webhooks duplicados causarão operações duplicadas?

O objetivo do protocolo AI Ready é colocar essas informações de gestão em cada tarefa, em vez de ficarem espalhadas no código e nos prompts do programa.

Estrutura básica da carga útil da solicitação#

{
  "event_id": "evt_20260415_001",
  "idempotency_key": "product-copy-1288-zhTW-v3",
  "intent": "generate_product_copy",
  "source": {
    "platform": "woocommerce",
    "store_id": "tw-store",
    "site_url": "https://example.com"
  },
  "context": {
    "locale": "zh-TW",
    "currency": "TWD",
    "actor": {
      "type": "admin",
      "id": "42"
    },
    "permissions": ["product:read", "draft:write"]
  },
  "data": {
    "product": {
      "sku": "BAG-18L-NAVY",
      "name": "18L 防潑水通勤背包",
      "attributes": {
        "capacity": "18L",
        "material": "recycled polyester"
      }
    }
  },
  "constraints": {
    "write_mode": "draft_only",
    "max_tokens": 1200,
    "do_not_change": ["sku", "price", "stock_quantity"]
  }
}

Cada campo deve ter um significado claro:

• event_id: identificação única do evento.

• idempotency_key: evita operações repetidas causadas por novas tentativas.

• intent: tipo de tarefa.

• source: plataforma de origem e armazenamento.

• contexto: idioma, moeda, operador e permissões.

• data: os dados necessários para a tarefa.

• restrições: restrições de modelo e writeback.

Estrutura básica da carga útil de resposta#

{
  "event_id": "evt_20260415_001",
  "status": "completed",
  "result": {
    "draft_short_description": "適合日常通勤的 18L 防潑水背包。",
    "meta_description": "18L 防潑水通勤背包，適合筆電收納與城市移動。"
  },
  "validation": {
    "schema_valid": true,
    "requires_review": true
  },
  "usage": {
    "model": "provider-model-name",
    "input_tokens": 680,
    "output_tokens": 220
  }
}

A resposta não deve conter apenas texto, mas também incluir status de verificação, requisitos de revisão e uso de token.

Design de assinatura do Webhook#

Cabeçalho sugerido:

X-AI-Ready-Timestamp: 1776268800
X-AI-Ready-Nonce: 4a8f7c...
X-AI-Ready-Signature: sha256=...
X-AI-Ready-Event-Id: evt_20260415_001
Idempotency-Key: product-copy-1288-zhTW-v3

O conteúdo da assinatura pode usar string canônica:

{timestamp}.{nonce}.{raw_body}

Então faça HMAC SHA-256 com a chave compartilhada. A extremidade receptora deve:

1. Verifique se o carimbo de data/hora está dentro da janela de tempo permitida.
2. Verifique se o nonce é usado.
3. Use o corpo bruto para recalcular a assinatura.
4. Verifique o ID do evento e a chave de idempotência.
5. Salve o status do processamento.

Códigos de status HTTP e novas tentativas#

• 200 / 204: Processado com sucesso ou já processado.

• 400: O formato da carga útil está incorreto e não deve ser tentado novamente.

• 401 / 403: Erro de assinatura ou permissão, não deve ser tentado novamente até que as configurações sejam corrigidas.

• 409: conflito de idempotência, é necessária inspeção manual.

• 422: a validação do esquema falhou e não deve ser escrita automaticamente.

• 429: Limitação de taxa, novas tentativas podem ser atrasadas.

• 500 / 503: Erro temporário, você pode tentar novamente.

Perguntas frequentes#

Uma assinatura HMAC é segura o suficiente?#

HMAC é uma base importante, mas também são necessários carimbo de data/hora, nonce, idempotência, rotação de chaves, TLS, privilégios mínimos e registro em log. Apenas assinar não pode impedir a repetição e a execução repetida.

O Webhook pode modificar produtos ou pedidos diretamente?#

Não é recomendado modificar diretamente dados de alto risco. Webhooks devem ser escritos primeiro em rascunho, fila de revisão ou campos de baixo risco. Operações como alterações de preços, reembolsos e emissão de cupons requerem aprovação adicional.

Por que preciso de uma chave de idempotência?#

O webhook ou a tarefa em segundo plano podem ser tentados novamente. Sem uma chave de idempotência, o sistema pode enviar e-mails repetidamente, criar códigos de desconto repetidamente ou escrever conteúdo repetidamente.

Referências#

• Diretrizes de segurança do Webhook OWASP, https://cheatsheetseries.owasp.org/
• Manual da API REST do WordPress, https://developer.wordpress.org/rest-api/
• APIs da Web do Adobe Commerce, https://developer.adobe.com/commerce/webapi/