변경 작업

변경 작업 정의#

주문 취소처럼 자체 시스템의 기록을 변경할 때 사용하세요. 에이전트 → 작업에서 로그인한 고객의 비밀 키를 설정한 다음 변경 작업을 추가하세요. 고유한 이름, 사용 상황 설명, 공개 HTTPS 엔드포인트와 문자열 입력을 지정합니다. cancel_order는 모델에 change_cancel_order 도구로 표시됩니다. 기존 항목의 수정은 자동 저장되므로 저장 표시를 확인하세요.

비공개 기록에는 로그인한 고객 필요를 켜 두세요. 엔드포인트에서도 검증된 고객 ID로 해당 기록의 소유권을 확인해야 합니다. 채팅에 입력한 이름·이메일·주문 번호는 신원 증명이 아닙니다. 이 설정을 끄면 customer가 null일 수 있으므로 익명 방문자에게 허용할 변경만 제공하세요. 결제는 이 기능의 범위 밖입니다.

소유자 승인 선택#

모든 모드에서 고객의 확인이 먼저 필요합니다.

에이전트 → 작업 → 승인 요청에서 사이트 소유자가 승인하거나 거절할 수 있습니다. 비공개 Telegram 소유자 알림을 연결했다면 알림의 승인 / 거절 버튼도 사용할 수 있습니다. 연결된 소유자의 개인 채팅만 허용되며 만료되거나 반복된 탭은 다시 실행하지 않습니다. 승인은 고객 확인 후 24시간에 만료됩니다. 고객에게 거절·만료를 포함한 결과가 전달됩니다. 최근 실행 목록에는 상태, 시각, 참조 번호, 고객 ID가 표시됩니다.

엔드포인트가 받는 요청#

모델이 변경을 제안하는 시점에는 요청을 보내지 않습니다. 고객 확인과 필요한 소유자 승인이 끝나면 다음 요청을 보냅니다.

POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b

{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

action에는 change_ 접두사가 없습니다. 두 ID와 멱등성 헤더는 재시도에도 동일합니다. input에는 선언한 입력의 앞뒤 공백을 제거한 문자열만 들어갑니다. customer는 null 또는 검증된 id와 선택적 email/name 객체입니다.

조회 서명 검증기를 사용하세요. 에이전트 비밀 키로 "maf-webhook-v1:" + timestamp + "." + rawBody의 HMAC-SHA256을 계산하고 소문자 16진수 앞에 v1=을 붙입니다. 쓰기 전에 원본 바이트, 타임스탬프 유효 기간, 사이트·작업 및 고객 소유권을 검증하세요. x-maf-idempotency-key 중복 확인과 데이터 변경을 원자적으로 처리하고 결과를 보관하세요. 같은 요청이 다시 오면 데이터를 다시 변경하지 않고 저장된 결과를 반환해야 합니다. 플랫폼의 잠금이 엔드포인트의 중복 방지를 대신하지 않습니다.

처리 결과 반환#

2xx JSON으로 필수 status(done, pending, failed)와 선택적 message, reference, card를 반환하세요.

{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}

선택적 상태 카드에는 title과 fields가 필요하며 kind: "status"는 생략할 수 있습니다. 조회와 같이 status: { label, tone }, reference, asOf, link: { label, url }을 지원합니다. tone은 neutral, success, warning, danger 중 하나이며 링크는 안전한 HTTPS URL이어야 합니다. 스키마에 없는 필드는 거부됩니다. 짧은 일반 텍스트를 사용하세요. 실제 결과는 바깥쪽 status로 결정되며 카드 문구로 대기 상태를 성공으로 바꿀 수 없습니다.

완료 후에만 done, 처리 중이면 pending, 확실한 실패면 failed를 사용하세요. 시간 초과, 네트워크 오류, 5xx, 잘못된 응답은 unknown으로 처리됩니다. 같은 키로 1분 후, 다음에는 5분 후 재시도하며 총 실행 시도는 최대 3회입니다. 큐 처리 상황에 따라 늦어질 수 있습니다. HTTP 4xx는 재시도 없이 실패합니다. 불확실한 상태에서 재시도를 모두 소진하면 실패로 표시하고 소유자에게 알리지만, 원격 시스템에 변경이 없었다는 뜻은 아닙니다. 새 실행 전에 확인하세요. pending은 다시 실행하지 않습니다.

서명된 최종 콜백 보내기#

pending 또는 unknown 결과가 확정되면 https://makeagent.fast/api/agent/actions/RUN_ID/callback으로 POST하세요. 같은 응답 규약으로 status: "done" 또는 "failed"만 보냅니다. 콜백에는 pending을 사용할 수 없습니다.

2026-10-14 콜백 규약 변경: maf-callback-v1: + runId + : + timestamp + . + rawBody에 서명하세요. 본문에 runId가 있으면 경로의 실행 ID와 같아야 하며, 다르면 400을 반환합니다. 다른 실행의 서명이나 이전 형식의 서명은 403을 반환합니다.

import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);

서버에 보관한 에이전트 비밀 키와 원래 요청의 실행 ID를 사용하세요. 콜백의 서명 접두사는 요청용과 다른 **maf-callback-v1:**입니다. 시간 차이는 5분 이내여야 합니다. 잘못된 서명은 403, 잘못된 본문은 400, 이미 종료됐거나 호환되지 않는 상태는 409를 반환합니다. 반복 콜백은 최종 결과를 덮어쓰지 않습니다. 비밀 키를 교체할 때 신원 서명과 엔드포인트 설정도 함께 갱신하세요.

고객 확인과 결과 카드#

고객은 정확한 입력 내용을 검토하고 확인 또는 취소를 누릅니다. 제안은 15분 후 만료되며 같은 작업·대화의 새 제안이 이전 제안을 대체합니다. 확인 토큰은 해당 실행, 사이트, 방문자에 연결됩니다. “예”라고 입력하거나 일반 확인 카드를 누르는 것만으로는 변경을 승인할 수 없습니다. 리허설 버튼은 비활성 상태이며 엔드포인트를 호출하지 않습니다.

열려 있는 웹 위젯은 완료되지 않은 결과를 처음에는 5초마다, 이후 30초마다 최대 24시간 조회합니다. 요청됨, 소유자 대기, 실행 중, 처리 대기, 결과 확인 중, 완료, 실패, 거절, 취소, 만료 상태를 보여 줍니다. 완료를 확인하는 상태는 done뿐입니다.

채널에서는 개인 채팅에서만 제안할 수 있으며 그룹이나 채널에서는 불가능합니다. 지연 결과는 영속 큐로 보냅니다. 일반 Telegram 봇 개인 채팅은 지원하며 WhatsApp, Messenger, Instagram, Telegram Business는 최근 24시간 이내 수신 메시지 기록이 필요합니다. 전송 시에도 이 조건을 다시 확인합니다. Telegram 게스트 질의, Discord, KakaoTalk에는 지연 결과를 보낼 수 없습니다. 대화 가능 시간 종료나 연결 비활성화로 전송되지 않더라도 실행 기록에는 결과가 남습니다.

제한과 테스트#

통제 가능한 엔드포인트에서 확인, 취소, 승인, 시간 초과, 중복 키 처리 및 최종 콜백을 검증하세요. 카드 문구뿐 아니라 실제 기록도 확인하세요. 리허설은 외부 쓰기를 하지 않으므로 엔드포인트 실행 테스트가 아닙니다. 사용할 개인 채널마다 결과 전달을 시험하세요.