정책 실행

Base URL

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

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

인증

어떤 API 키로도 이 API를 호출할 수 있습니다. 기본값인 실행 전용 범위로 만든 키도 됩니다. 모든 요청에 포함하세요:

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": {
      "userId": "user_abc",
      "paymentAmount": 150000,
      "customerTier": "VIP"
    },
    "context": {
      "channel": "mobile-app"
    }
  }'

필드	타입	필수	설명
`facts`	object	✅	규칙 평가를 위한 입력 변수
`context`	object		요청 메타데이터. A/B 라우팅을 정하고 원장에 기록됩니다

context가 하는 일은 둘입니다. 이름만 봐서는 드러나지 않습니다.

A/B 라우팅이 읽습니다. 정책 그룹에 A/B 테스트가 진행 중이면 context.trafficKey가 어느 버전이 요청을 처리할지 정합니다. 이 값이 없으면 테스트 버전 트래픽이 0%가 됩니다. 트래픽 식별 키를 참조하세요.
기록에 남습니다. 객체 전체가 요청과 함께 실행 원장에 저장되어 실행 이력과 감사 화면에 나타납니다. 개인정보는 담지 않습니다.

규칙이 평가할 값은 context가 아니라 facts로 보냅니다. fact 정의와 /requirements 응답, 실행 응답이 모두 합의하는 입력은 facts 하나입니다. context로 보낸 값은 그 계약 밖이라 fact 정의로 등록할 수 없고, /requirements에 나타나지 않으며, 응답으로 돌아오지도 않습니다.

응답

{
  "result": "SUCCESS",
  "data": {
    "traceId": "2e31f2b8-...",
    "inputFacts": {
      "userId": "user_abc",
      "paymentAmount": 150000,
      "customerTier": "VIP"
    },
    "mutatedFacts": {
      "paymentAmount": 135000
    },
    "generatedVariables": {
      "paymentAmount__delta": -15000
    },
    "executionTraces": [
      {
        "tenantId": "acme-corp",
        "policyGroupId": "01f2b274-...",
        "policyVersionId": "a6062090-...",
        "ruleId": "3b16ced1-...",
        "ruleName": "VIP 10% 할인",
        "executedAt": "2026-04-27T09:44:10Z",
        "matched": true,
        "matchExpression": "(customerTier == 'VIP') && (paymentAmount >= 100000)",
        "inputFacts": {
          "customerTier": "VIP",
          "paymentAmount": 150000
        },
        "generatedActions": [
          {
            "type": "MUTATE_FACT",
            "parameters": { "targetVar": "paymentAmount", "operator": "SUB", "method": "PERCENTAGE", "operand": 10 }
          }
        ]
      }
    ],
    "decisionTraces": [
      {
        "ruleId": "3b16ced1-...",
        "ruleName": "VIP 10% 할인",
        "policyGroupId": "01f2b274-...",
        "policyVersionId": "a6062090-...",
        "status": "SELECTED",
        "reasonCode": "FINAL_WINNER",
        "reasonDetail": null
      }
    ]
  }
}

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

inputFacts: 요청에서 받은 입력 fact (정규화 후).
mutatedFacts: 규칙 액션에 의해 값이 변경된 fact만.
generatedVariables: 규칙 액션이 새로 생성한 변수 (입력에 없었던 것). 액션별 변화 키도 포함됩니다. {targetVar}__delta는 MUTATE_FACT가 적용한 부호 포함 변화량입니다.

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

멱등성

Idempotency-Key 헤더를 포함하면 중복 실행을 방지합니다. 동일한 키로 이미 처리된 요청이 있으면, 정책을 재실행하지 않고 원래 응답을 반환합니다. 재생된 응답은 에러가 아니라 정상 200입니다. 첫 호출과 traceId와 executedAt이 같아서 재생인지 새 실행인지 구분할 수 있습니다. 아래 I-001은 다른 상황입니다. 키가 이미 소진되어 이 요청을 그 키로 처리할 수 없다는 뜻입니다. 키 형식. 최대 255자입니다. 키를 어떻게 만들지는 자유이나 V4 UUID 나 충돌하지 않을 만큼 엔트로피가 있는 난수 문자열을 권합니다. 상한을 넘으면 잘라내지 않고 I-003으로 거부합니다. 자르면 서로 다른 두 키가 하나로 접혀 한 요청이 다른 요청의 재생으로 처리되기 때문입니다. 키는 실행 원장에 평문으로 저장되어 보관 기간 동안 남습니다. 개인정보를 키에 넣지 마세요. 이메일, 전화번호, 이름 모두 해당합니다.

특정 버전 실행

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

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

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

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

배치 실행

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

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": { "userId": "user_1", "paymentAmount": 50000 } },
      { "facts": { "userId": "user_2", "paymentAmount": 150000 } },
      { "facts": { "userId": "user_3", "paymentAmount": 300000 } }
    ],
    "sharedContext": {
      "channel": "batch-job"
    }
  }'

필드	타입	필수	설명
`requests`	array	✅	평가할 fact 세트 목록
`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 호출로 계산됩니다. 단, 과금은 총 아이템 수 기준입니다.

복합 실행

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

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": {
      "userId": "user_abc",
      "paymentAmount": 250000
    },
    "context": {
      "channel": "checkout"
    }
  }'

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

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

필수 fact 조회

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

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": "paymentAmount",
        "type": "NUMBER",
        "displayName": "결제 금액",
        "usedBy": [
          "조건 [GREATER_THAN_OR_EQUAL] (규칙: VIP 10% 할인)",
          "MUTATE_FACT 액션 (규칙: VIP 10% 할인)"
        ]
      },
      {
        "key": "customerTier",
        "type": "STRING",
        "displayName": "고객 등급",
        "usedBy": [
          "조건 [EQUALS] (규칙: VIP 10% 할인)"
        ]
      }
    ],
    "exampleRequest": {
      "facts": { "paymentAmount": 50000, "customerTier": "" },
      "context": { "reqTime": "2025-01-01T00:00:00Z" }
    }
  }
}

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

시스템 fact

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

키	타입	설명
`userId`	STRING	사용자 ID
`userTags`	LIST_STRING	사용자 태그

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

오류 처리

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

{ "result": "ERROR", "errorCode": "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`	필수 입력 fact 누락. `/requirements`로 확인
400	`C-001`	요청 본문 형식 오류 또는 검증 실패
400	`P-003`	평가 도중 액션 실행에서 오류 발생
409	`I-001`	`Idempotency-Key`가 이미 소진됨. 재시도해도 풀리지 않으니 새 키를 씁니다. 동일 요청 재생은 여기까지 오지 않고 `200`으로 원래 응답을 받습니다
409	`I-002`	동일 키 요청이 처리 중. 잠시 후 재시도
400	`I-003`	`Idempotency-Key`가 255자를 넘음. 자르지 않고 거부하므로 줄여서 재시도
403	`B-008`	현재 플랜의 월 실행 한도 도달
429	`C-007`	플랜의 최대 TPS 초과

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

개요

정책 실행

Base URL

인증

실행 모드

단일 그룹 실행

요청

응답

멱등성

특정 버전 실행

배치 실행

요청

응답

복합 실행

요청

필수 fact 조회

응답

시스템 fact

오류 처리

다음 단계

드라이런

fact 정의

​Base URL

​인증

​실행 모드

​단일 그룹 실행

​요청

​응답

​멱등성

​특정 버전 실행

​배치 실행

​요청

​응답

​복합 실행

​요청

​필수 fact 조회

​응답

​시스템 fact

​오류 처리

​다음 단계

드라이런

fact 정의

Base URL

인증

실행 모드

단일 그룹 실행

요청

응답

멱등성

특정 버전 실행

배치 실행

요청

응답

복합 실행

요청

필수 fact 조회

응답

시스템 fact

오류 처리

다음 단계