조회

조회가 필요한 경우#

주문 상태, 기존 예약, 고객 계정 정보처럼 최신 데이터가 필요한 경우 조회를 사용하세요. 자주 바뀌지 않는 정책과 상품 설명은 지식에 저장하세요. 조회는 읽기 전용입니다. 결제, 취소, 예약 생성 등 데이터를 변경하는 작업에 사용하면 안 됩니다. 일반 선택·확인 카드는 방문자 메시지만 보냅니다. 확인 후 데이터를 변경하려면 변경 작업, 캘린더 예약은 Cal.com 예약을 사용하세요. 실행에 연결된 확인 카드만 해당 작업을 승인합니다.

작업 설정#

에이전트 → 작업을 여세요. 로그인한 고객에서 비밀 키를 만들고 서버에 저장한 뒤 고객 식별을 구현하세요. 조회에서 order_status 같은 이름, 사용할 상황 설명, 공개 HTTPS 엔드포인트를 추가하세요. order_id 문자열처럼 필요한 입력만 선언하세요. 모델에는 lookup_order_status 도구로 표시됩니다.

개인 기록에는 기본값인 로그인한 고객 필요를 유지하세요. 끄면 customer: null 요청을 받을 수 있으므로 익명 방문자에게 공개해도 되는 정보만 반환하세요. 채팅이나 사진에서 나온 ID는 입력일 뿐 인증된 신원이 아닙니다.

기존 필드는 자동 저장됩니다. 저장 표시를 기다린 뒤 테스트하세요. 조회를 수정하거나 켜고 끄거나 삭제할 수 있습니다. 비밀 키가 있어야 패널을 사용할 수 있습니다. 1차 구현의 조회 관리는 대시보드에서만 제공하며 공개 API에는 노출하지 않습니다.

수신하는 요청#

Make Agent Fast는 설정된 URL로 JSON POST를 보냅니다. 아래 서명 값은 자리표시자입니다:

POST /agent/order-status HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>

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

action은 lookup_ 접두사 없는 설정 이름입니다. requestId는 요청 시도, siteId는 사이트를 식별합니다. input에는 선언된 문자열 매개변수만 있습니다. customer는 null 또는 서버에서 검증한 { id, email?, name? }이며 모델이나 방문자 입력으로 바꿀 수 없습니다. 대시보드 테스트는 권한 있는 소유자가 입력한 샘플 고객을 사용합니다.

서명 검증#

서명은 에이전트 비밀 키를 사용한 HMAC-SHA256의 소문자 16진수 앞에 v1=을 붙인 값입니다. 정확히 "maf-webhook-v1:" + timestamp + "." + rawBody를 검증하세요. JSON을 파싱 후 다시 직렬화하지 말고 받은 바이트를 보존하세요. 아래 함수는 서버의 표준 Request를 받아 5분 시간 범위와 사이트를 확인합니다:

import { createHmac, timingSafeEqual } from "node:crypto";

export async function verifyLookupRequest(request, expectedSiteId) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const timestamp = request.headers.get("x-maf-timestamp");
  const signature = request.headers.get("x-maf-signature");
  const now = Math.floor(Date.now() / 1000);
  if (!timestamp || !/^\d+$/.test(timestamp) ||
      !Number.isSafeInteger(Number(timestamp)) ||
      Math.abs(now - Number(timestamp)) > 300) {
    throw new Error("Invalid timestamp");
  }
  if (!signature || !/^v1=[a-f0-9]{64}$/.test(signature)) {
    throw new Error("Invalid signature");
  }
  const rawBody = Buffer.from(await request.arrayBuffer());
  const expected = createHmac("sha256", secret)
    .update(`maf-webhook-v1:${timestamp}.`)
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), "hex");
  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
    throw new Error("Invalid signature");
  }
  const body = JSON.parse(rawBody.toString("utf8"));
  if (body?.version !== 1 || body.siteId !== expectedSiteId) {
    throw new Error("Invalid lookup scope");
  }
  return body;
}

본문 파서가 요청을 읽기 전에 호출하세요. 검증 오류를 거부하고 예상한 작업 이름과 입력 구조를 검사한 뒤, 개인 데이터를 반환하기 전에 body.customer.id로 소유권을 확인하세요. 예를 들어 주문 ID만 조회하지 말고 해당 고객의 주문 안에서 A128을 찾으세요. input.customer_id, 채팅 이메일, 사진은 권한 근거가 아닙니다. 개인 정보 엔드포인트는 null이 아닌 고객을 요구해야 합니다. 서버에서 요청 크기를 제한하세요. 재전송 거부가 필요하면 시간 범위 내 requestId도 기록하세요. 시간 검사만으로는 같은 범위 내 재전송을 막지 못합니다.

HTTPS를 사용하고 POST라도 읽기 전용으로 유지하세요. 키를 교체하면 신원 토큰 발급 서버와 조회 검증기의 키를 모두 갱신하세요.

응답 반환#

성공 2xx 상태와 아래 계약에 맞는 JSON을 반환하세요. 첫 번째는 찾은 기록, 두 번째는 정상적인 일치 항목 없음 응답입니다:

{
  "found": true,
  "card": {
    "title": "Order #A128",
    "status": { "label": "Shipped", "tone": "success" },
    "fields": [{ "label": "Carrier", "value": "DHL" }],
    "reference": "A128",
    "asOf": "2026-10-12T09:00:00Z",
    "link": { "label": "Track", "url": "https://shop.example.com/orders/A128" }
  },
  "facts": { "order_id": "A128", "status": "shipped", "carrier": "DHL" }
}

{ "found": false }

found는 필수입니다. found: true이면 card, facts 또는 둘 다 포함하세요. 카드에는 title과 fields가 필수이며 빈 배열도 가능합니다. status, reference, asOf, link는 선택입니다. 응답 카드에 kind를 넣지 마세요. 상태 색조는 neutral, success, warning, danger입니다. asOf는 ISO 시간, 링크는 자격 증명 없는 HTTPS URL을 사용하세요. 유효하지 않은 선택 링크는 생략됩니다.

facts는 문자열, 유한한 숫자, 불리언, null만 값으로 갖는 평면 객체입니다. 중첩 객체·배열과 응답/카드 스키마에 없는 필드는 거부됩니다. 답변에 필요한 데이터만 보내세요. 모델은 이스케이프되고 길이가 제한된 비신뢰 데이터를 받으며 이를 지침으로 취급하지 않습니다. 카드 내용은 HTML이 아닌 일반 텍스트입니다.

제한과 실패 처리#

고객 신원이 없으면 호출 없이 로그인 경고가 표시됩니다. 필수 입력이 없으면 방문자에게 묻습니다. found: false는 중립적인 일치 항목 없음 카드로 표시됩니다. 시간 초과, 비 2xx 상태, 잘못된 JSON/스키마, 초과 크기는 실패 상태로 표시되며 모델에 추측하지 말라고 지시합니다. 정상적인 미발견은 HTTP 404 대신 2xx와 found: false를 반환하세요. 긴 카드 문자열과 모델 데이터는 잘리므로 중요한 사실을 간결하게 작성하세요.

대시보드에서 테스트#

1. 조회를 저장하고 테스트를 여세요. 관리 가능한 테스트 고객 ID, 선택 이메일, 모든 필수 입력을 넣으세요.
2. 테스트를 실행하세요. 방문자용으로 꺼져 있어도 실제 서명 요청을 보냅니다. 일반 리허설 채팅은 엔드포인트를 호출하지 않습니다. 소유자별 테스트 빈도 제한이 있습니다.
3. 검증된 카드·요약 또는 오류, 요청 ID, 소요 시간, 가능한 경우 HTTP 상태를 확인하세요. 엔드포인트 로그에 비밀 키나 고객 토큰을 남기지 마세요.
4. 발견, 미발견, 다른 계정, 입력 누락, 시간 초과를 테스트하세요. 이후 실제 임베드에서 인증된 고객 두 명으로 확인하세요. 대시보드 샘플은 브라우저 신원 격리나 실제 모델의 도구 선택을 증명하지 않습니다.

위젯은 상태 카드를 표시하고 일반 선택·확인 탭을 메시지로 보냅니다. 실행에 연결된 변경·예약 확인 카드는 보호된 실행 흐름을 사용합니다. 커넥터는 채널별 텍스트/카드, 버튼, 빠른 답장, 목록으로 변환하며 텍스트 대체에도 채널 제한이 적용됩니다. 사용할 채널마다 전달을 확인하세요.