정책 실행

Base URL

https://api.lexq.io/api/v1/execution

실행 API의 Base URL(/api/v1/execution)은 관리 API(/api/v1/partners)와 다릅니다. 각 API에 맞는 Base URL을 사용하세요.

인증

관리 API와 동일한 API Key를 사용합니다. 모든 요청에 포함하세요:

x-api-key: YOUR_API_KEY

실행 모드

모드	엔드포인트	용도
단일 그룹	`POST /groups/{groupId}`	일반적인 단건 주문 평가
특정 버전	`POST /groups/{groupId}/versions/{versionId}`	A/B 테스트, 롤백 테스트
배치	`POST /groups/{groupId}/batch`	장바구니 계산, 상품 목록 혜택 표기
복합	`POST /composite`	다중 그룹 동시 평가 (할인 + 쿠폰 + 배송비)

단일 그룹 실행

현재 배포된 버전의 모든 활성 규칙을 평가합니다.

POST /groups/{groupId}

요청

curl -X POST https://api.lexq.io/api/v1/execution/groups/{groupId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "facts": {
      "user_id": "user_abc",
      "payment_amount": 150000,
      "customer_tier": "VIP"
    },
    "context": {
      "channel": "mobile-app"
    }
  }'

필드	타입	필수	설명
`facts`	object	✅	규칙 평가를 위한 입력 변수
`context`	object		추가 메타데이터 (조건에 사용되지 않으며 액션에 전달)

응답

{
  "result": "SUCCESS",
  "data": {
    "outputVariables": {
      "discount_amount": 15000,
      "discount_applied": true
    },
    "executionTraces": [
      {
        "ruleName": "VIP 10% 할인",
        "ruleId": "...",
        "conditionMatched": true,
        "evaluatedExpression": "payment_amount >= 100000 AND customer_tier == VIP"
      }
    ],
    "decisionTraces": [
      {
        "ruleName": "VIP 10% 할인",
        "ruleId": "...",
        "selected": true,
        "reason": "CONDITION_MATCHED"
      }
    ]
  }
}

멱등성

Idempotency-Key 헤더를 포함하면 중복 실행을 방지합니다. 동일한 키로 이미 처리된 요청이 있으면, 정책을 재실행하지 않고 원래 응답을 반환합니다.

특정 버전 실행

트래픽 라우팅을 우회하여 정책 그룹의 특정 버전을 실행합니다. A/B 테스트 후보 버전 검증이나 롤백 전 이전 버전 테스트에 유용합니다.

POST /groups/{groupId}/versions/{versionId}

요청과 응답 형식은 단일 그룹 실행과 동일합니다. 현재 배포된 버전 대신 지정된 버전을 사용하는 것만 다릅니다.

버전은 ACTIVE (발행됨) 상태여야 합니다. DRAFT 버전은 Engine API로 실행할 수 없습니다 — DRAFT 테스트에는 드라이런을 사용하세요.

배치 실행

여러 팩트 세트를 동일한 정책 그룹에 대해 한 번의 호출로 실행합니다. 일관성을 위해 배치 내 모든 요청이 동일 버전으로 평가됩니다.

POST /groups/{groupId}/batch

요청

curl -X POST https://api.lexq.io/api/v1/execution/groups/{groupId}/batch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "facts": { "user_id": "user_1", "payment_amount": 50000 } },
      { "facts": { "user_id": "user_2", "payment_amount": 150000 } },
      { "facts": { "user_id": "user_3", "payment_amount": 300000 } }
    ],
    "sharedContext": {
      "channel": "batch-job"
    }
  }'

필드	타입	필수	설명
`requests`	array	✅	평가할 팩트 세트 목록
`sharedContext`	object		모든 요청에 병합되는 공유 컨텍스트

응답

{
  "result": "SUCCESS",
  "data": {
    "results": [
      { "outputVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "outputVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "outputVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] }
    ],
    "totalProcessingTimeMs": 45
  }
}

결과는 입력 요청과 동일한 순서로 반환됩니다. 각 요청의 context는 sharedContext와 병합됩니다 (개별 요청 컨텍스트가 충돌 시 우선).

배치 실행은 TPS 스로틀링에서 아이템 수와 관계없이 1회 API 호출로 계산됩니다. 단, 과금은 총 아이템 수 기준입니다.

복합 실행

동일한 팩트를 여러 정책 그룹에 대해 한 번의 호출로 평가합니다. 하나의 거래가 여러 정책 검사를 동시에 통과해야 할 때 사용합니다 (예: 상품할인 + 장바구니쿠폰 + 배송비 + 멤버십적립).

POST /composite

요청

curl -X POST https://api.lexq.io/api/v1/execution/composite \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-composite" \
  -d '{
    "targetGroupIds": ["group-discount-id", "group-coupon-id", "group-shipping-id"],
    "facts": {
      "user_id": "user_abc",
      "payment_amount": 250000
    },
    "context": {
      "channel": "checkout"
    }
  }'

필드	타입	필수	설명
`targetGroupIds`	array	✅	평가할 정책 그룹 ID 목록
`facts`	object	✅	모든 그룹에 공유되는 입력 팩트
`context`	object		모든 그룹에 공유되는 컨텍스트

응답에는 평가된 모든 그룹의 outputVariables, executionTraces, decisionTraces가 병합되어 포함됩니다. 모든 대상 그룹이 ACTIVE 상태여야 합니다.

필수 팩트 조회

실행 엔드포인트를 호출하기 전에 배포된 버전이 어떤 입력 팩트를 필요로 하는지 확인합니다.

GET /groups/{groupId}/requirements

curl https://api.lexq.io/api/v1/execution/groups/{groupId}/requirements \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept-Language: ko"

Accept-Language 헤더로 usedBy 설명의 언어를 제어합니다 (en 또는 ko).

응답

{
  "result": "SUCCESS",
  "data": {
    "groupId": "...",
    "versionId": "...",
    "versionNo": 5,
    "requiredFacts": [
      {
        "key": "payment_amount",
        "type": "NUMBER",
        "displayName": "결제 금액",
        "required": true,
        "usedBy": [
          "조건 [GREATER_THAN] (규칙: VIP 10% 할인)",
          "DISCOUNT 액션 (규칙: VIP 10% 할인)"
        ]
      }
    ],
    "exampleRequest": {
      "facts": { "payment_amount": 50000 },
      "context": { "reqTime": "2025-01-01T00:00:00Z" }
    }
  }
}

첫 연동 전에 이 엔드포인트를 호출하여 필요한 팩트를 확인하세요. exampleRequest를 시작 템플릿으로 복사하고 실제 값을 채워 넣으면 됩니다.

시스템 팩트

모든 테넌트는 계정 생성 시 7개의 시스템 팩트가 자동 등록됩니다. 수동 생성이 필요 없습니다:

키	타입	필수	설명
`user_id`	STRING	✅	사용자 식별자
`payment_amount`	NUMBER	✅	결제 금액
`phone_number`	STRING		휴대전화 번호
`email`	STRING		이메일 주소
`device_token`	STRING		디바이스 토큰 (푸시 알림용)
`user_tags`	LIST_STRING		사용자 태그
`total_point`	NUMBER		현재 보유 포인트

커스텀 팩트 (예: customer_tier, order_region)는 사용 전에 팩트 정의에서 등록해야 합니다.

오류 처리

HTTP	코드	설명	조치
404	`POLICY_GROUP_NOT_FOUND`	그룹 ID가 존재하지 않음	그룹 ID 확인
400	`POLICY_GROUP_DISABLED`	그룹이 DISABLED 상태	그룹 재활성화
404	`POLICY_VERSION_NOT_FOUND`	배포된 버전이 없거나 버전 ID 유효하지 않음	버전 배포 필요
400	`INVALID_INPUT`	필수 팩트 누락	`/requirements` 호출하여 확인
429	—	TPS 한도 초과	플랜 업그레이드 또는 재시도

개요

정책 실행

Base URL

인증

실행 모드

단일 그룹 실행

요청

응답

멱등성

특정 버전 실행

배치 실행

요청

응답

복합 실행

요청

필수 팩트 조회

응답

시스템 팩트

오류 처리

다음 단계

드라이런

팩트 정의

개요

정책 실행

​Base URL

​인증

​실행 모드

​단일 그룹 실행

​요청

​응답

​멱등성

​특정 버전 실행

​배치 실행

​요청

​응답

​복합 실행

​요청

​필수 팩트 조회

​응답

​시스템 팩트

​오류 처리

​다음 단계

드라이런

팩트 정의

Base URL

인증

실행 모드

단일 그룹 실행

요청

응답

멱등성

특정 버전 실행

배치 실행

요청

응답

복합 실행

요청

필수 팩트 조회

응답

시스템 팩트

오류 처리

다음 단계