정책 실행

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": {
    "traceId": "2e31f2b8-...",
    "inputFacts": {
      "user_id": "user_abc",
      "payment_amount": 150000,
      "customer_tier": "VIP"
    },
    "mutatedFacts": {
      "payment_amount": 135000
    },
    "generatedVariables": {
      "payment_amount__delta": -15000
    },
    "executionTraces": [
      {
        "tenantId": "acme-corp",
        "policyGroupId": "01f2b274-...",
        "policyVersionId": "a6062090-...",
        "ruleId": "3b16ced1-...",
        "ruleName": "VIP 10% 할인",
        "executedAt": "2026-04-27T09:44:10Z",
        "matched": true,
        "matchExpression": "(customer_tier == 'VIP') && (payment_amount >= 100000)",
        "inputFacts": {
          "customer_tier": "VIP",
          "payment_amount": 150000
        },
        "generatedActions": [
          {
            "type": "MUTATE_FACT",
            "parameters": { "refVar": "payment_amount", "operator": "SUB", "method": "PERCENTAGE", "rate": 10 }
          }
        ]
      }
    ],
    "decisionTraces": [
      {
        "ruleId": "3b16ced1-...",
        "ruleName": "VIP 10% 할인",
        "policyGroupId": "01f2b274-...",
        "policyVersionId": "a6062090-...",
        "status": "SELECTED",
        "reasonCode": "FINAL_WINNER",
        "reasonDetail": null
      }
    ]
  }
}

data.traceId는 이 실행의 감사 핸들입니다 — 나중에 이 실행을 추적하려면 자체 레코드와 함께 저장하세요. 응답의 data 객체는 상태를 세 층위로 분리합니다:

inputFacts — 요청에서 받은 입력 팩트 (정규화 후).
mutatedFacts — 규칙 액션에 의해 값이 변경된 팩트만.
generatedVariables — 규칙 액션이 새로 생성한 변수 (입력에 없었던 것). 액션별 변화 키도 포함됩니다 — {refVar}__delta(MUTATE_FACT의 부호 포함 변화량)와 {targetVar}__delta(INCREMENT_FACT의 0 이상 증분량).

이렇게 분리하면 감사·재현·디버그가 결정적입니다 — 어떤 값이 어디서 왔는지가 항상 명확합니다. 합본이 필요하면 { ...inputFacts, ...mutatedFacts, ...generatedVariables }로 재구성하세요.

멱등성

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": [
      { "inputFacts": { ... }, "mutatedFacts": { ... }, "generatedVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "inputFacts": { ... }, "mutatedFacts": { ... }, "generatedVariables": { ... }, "executionTraces": [ ... ], "decisionTraces": [ ... ] },
      { "inputFacts": { ... }, "mutatedFacts": { ... }, "generatedVariables": { ... }, "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		모든 그룹에 공유되는 컨텍스트

응답에는 평가된 모든 그룹의 inputFacts, mutatedFacts, generatedVariables, 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": "01f2b274-...",
    "versionId": "a6062090-...",
    "versionNo": 5,
    "requiredFacts": [
      {
        "key": "payment_amount",
        "type": "NUMBER",
        "displayName": "결제 금액",
        "usedBy": [
          "조건 [GREATER_THAN_OR_EQUAL] (규칙: VIP 10% 할인)",
          "MUTATE_FACT 액션 (규칙: VIP 10% 할인)"
        ]
      },
      {
        "key": "customer_tier",
        "type": "STRING",
        "displayName": "고객 등급",
        "usedBy": [
          "조건 [EQUALS] (규칙: VIP 10% 할인)"
        ]
      }
    ],
    "exampleRequest": {
      "facts": { "payment_amount": 50000, "customer_tier": "" },
      "context": { "reqTime": "2025-01-01T00:00:00Z" }
    }
  }
}

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

시스템 팩트

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

키	타입	설명
`user_id`	STRING	사용자 ID
`email`	STRING	이메일 주소
`user_tags`	LIST_STRING	사용자 태그

각 팩트가 실제 실행에서 필수인지는 배포된 버전의 어떤 규칙이 그 팩트를 참조하느냐에 달려 있습니다. 정확히 어떤 팩트가 필요한지는 GET /groups/{groupId}/requirements를 호출해 확인하세요. 그 외 모든 팩트(예: payment_amount, customer_tier, order_region)는 사용자가 정의하며, 사용 전에 팩트 정의에서 등록해야 합니다.

오류 처리

모든 오류는 동일한 envelope 형태를 따릅니다:

{ "result": "ERROR", "code": "P-001", "message": "정책 그룹을 찾을 수 없습니다." }

실행 엔드포인트에서 가장 자주 마주치는 오류:

HTTP	코드	발생 조건
401	`A-003`	`x-api-key` 헤더가 누락되거나 변조·폐기됨
404	`P-001`	`groupId`가 존재하지 않거나 다른 tenant 소속
403	`P-009`	그룹은 존재하지만 `DISABLED` 상태
400	`P-019`	그룹에 배포된 버전이 없음 — 먼저 버전을 배포해야 함
404	`P-002`	(특정 버전 모드) `versionId`가 존재하지 않음
400	`P-016`	(특정 버전 모드) 버전이 대상 그룹에 속하지 않음
400	`P-015`	필수 입력 팩트 누락 — `/requirements`로 확인
400	`C-001`	요청 본문 형식 오류 또는 검증 실패
400	`P-003`	평가 도중 액션 실행에서 오류 발생
409	`I-001`	`Idempotency-Key`로 이미 처리됨 (원본 응답 반환)
409	`I-002`	동일 키 요청이 처리 중 — 잠시 후 재시도
403	`B-008`	현재 플랜의 월 실행 한도 도달
429	`C-007`	플랜의 최대 TPS 초과

전체 도메인(인증·빌링·시뮬레이션 등)에 걸친 코드 레지스트리는 에러 레퍼런스를 참조하세요.

개요

정책 실행

Base URL

인증

실행 모드

단일 그룹 실행

요청

응답

멱등성

특정 버전 실행

배치 실행

요청

응답

복합 실행

요청

필수 팩트 조회

응답

시스템 팩트

오류 처리

다음 단계

드라이런

팩트 정의

​Base URL

​인증

​실행 모드

​단일 그룹 실행

​요청

​응답

​멱등성

​특정 버전 실행

​배치 실행

​요청

​응답

​복합 실행

​요청

​필수 팩트 조회

​응답

​시스템 팩트

​오류 처리

​다음 단계

드라이런

팩트 정의

Base URL

인증

실행 모드

단일 그룹 실행

요청

응답

멱등성

특정 버전 실행

배치 실행

요청

응답

복합 실행

요청

필수 팩트 조회

응답

시스템 팩트

오류 처리

다음 단계