세그먼트 관리

세그먼트 저장

post

기능설명

세그먼트를 등록 · 수정하거나 상태를 바꿉니다. sgmtNo 가 비어 있으면 신규입니다.

상세설명

siteNo 는 화면이 입력한 값입니다 — 로그인 사이트에서 자동으로 뽑지 않습니다.
멱등합니다. 현재 값과 비교해 차이가 있을 때만 쓰므로 같은 요청을 다시 보내도 결과가 같습니다.
현재 상태 = 요청 상태 → 내용 저장
- 신규 → 임시저장(10)만 가능
- 임시저장 → 모든 항목 저장. 조건(사이트 · 포함 · 제외)이 바뀌면 최근 계산을 비움
- 사용 → 세그먼트명 · 담당부서 · 설명만 저장. 사이트 · 조건이 다르면 거부
- 종료 → 아무것도 하지 않음
현재 상태 ≠ 요청 상태 → 상태만 변경, 요청의 다른 값은 무시
- 임시저장 → 사용: 최신 스냅샷일로 완료된 계산이 있어야 함
- 임시저장 · 사용 → 종료: 대상자 명단 삭제
- 그 외 전환은 거부
응답: sgmtNo · 저장 후 sgmtStatCd

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

세그먼트 저장 요청

siteNostring · min: 1Required

사이트번호 — 화면이 입력한 값. 세그먼트가 속할 사이트를 정한다

Example: 1

sgmtNostringOptional

세그먼트번호 — 없거나 빈 문자열이면 신규

Example: SG00000001

sgmtNmstring · min: 1Required

세그먼트명

sgmtDescstringOptional

세그먼트설명

deptCdstringOptional

부서코드

sgmtStatCdstring · min: 1Required

저장 목표 상태코드(MK023) 10 임시저장 / 20 사용 / 30 종료

Example: 10

condJsonstring · min: 1Required

조건 JSON(화면이 보낸 원본 — 저장 전에 정규화한다)

Responses

200

성공

*/*

세그먼트 저장 결과

sgmtNostringOptional

세그먼트번호

Example: SG00000001

sgmtStatCdstringOptional

저장 후 세그먼트상태코드(MK023)

Example: 10

900

업무처리 오류 내용

*/*

post/v1/marketing/segmentMgmt/saveSegment

POST /api/bo/v1/marketing/segmentMgmt/saveSegment HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "siteNo": 1,
  "sgmtNo": "SG00000001",
  "sgmtNm": "text",
  "sgmtDesc": "text",
  "deptCd": "text",
  "sgmtStatCd": 10,
  "condJson": "text"
}

{
  "sgmtNo": "SG00000001",
  "sgmtStatCd": 10
}

세그먼트 조건 초안 생성

post

기능설명

자연어 문장을 조건 빌더가 바로 쓸 수 있는 조건 카드 초안으로 변환합니다.

상세설명

AI 기능이 꺼져 있으면(가용성 false) 요청 자체를 오류로 거부합니다 — 화면이 이 경우 입력창 자체를 그리지 않아야 합니다.
그 외 실패는 예외를 던지지 않고 reason 으로 알립니다 — 초안이 없어도 수동 등록을 계속할 수 있어야 합니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

세그먼트 조건 초안 생성 요청

textstring · max: 500Required

사용자가 입력한 자연어 조건 문장

Example: 골드 등급 회원

Responses

200

성공

*/*

세그먼트 조건 초안 생성 응답

unsupportedstring[]Optional

조건으로 표현하지 못했거나 검증·상한 초과로 버려진 사유 목록

reasonstring · enumOptional

실패 사유. 성공이면 null

Possible values:

900

업무처리 오류 내용

*/*

post/v1/marketing/segmentMgmt/getSegmentCondDraft

POST /api/bo/v1/marketing/segmentMgmt/getSegmentCondDraft HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "text": "골드 등급 회원"
}

{
  "drafts": [
    {
      "label": "text",
      "condJson": "text",
      "resolutions": [
        {
          "nodeId": "text",
          "gb": "text",
          "q": "text",
          "status": "text",
          "candidates": [
            {
              "id": "text",
              "nm": "text"
            }
          ]
        }
      ]
    }
  ],
  "unsupported": [
    "text"
  ],
  "reason": "NO_CONDITION"
}

세그먼트 조건 초안 생성 (스트리밍)

post

기능설명

세그먼트 조건 초안 생성을 수행하며 진행 단계를 SSE 로 전달합니다.

이벤트

stage : {step, label, seq, total} — 진행 단계. 0회 이상 발생
result : 초안 결과(JSON 엔드포인트와 동일한 payload). 성공 종료
error : {code, message} — 실패 종료. AI 기능이 꺼져 있으면(가용성 false) 이 이벤트로 거부합니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

세그먼트 조건 초안 생성 요청

textstring · max: 500Required

사용자가 입력한 자연어 조건 문장

Example: 골드 등급 회원

Responses

200

text/event-stream

timeoutinteger · int64Optional

post/v1/marketing/segmentMgmt/getSegmentCondDraft/stream

POST /api/bo/v1/marketing/segmentMgmt/getSegmentCondDraft/stream HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "text": "골드 등급 회원"
}

200

{
  "timeout": 1
}

대상자 계산

post

기능설명

현재 조건으로 대상자를 동기로 계산하고 결과를 적재합니다.

상세설명

**응답까지 수십 초가 걸릴 수 있습니다.
calcGbCd 를 비우면 10(수동)입니다 — 자동 갱신 배치만 20 을 싣습니다.
멱등합니다. 같은 스냅샷일로 완료된 계산이 있으면 다시 계산하지 않고 그 결과를 돌려줍니다.
종료된 세그먼트는 계산할 수 없습니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

세그먼트 대상자 계산 요청

sgmtNostring · min: 1Required

세그먼트번호

Example: SG00000001

calcGbCdstringOptional

계산구분코드(MK024) 10 수동 / 20 배치. 비면 수동 — 화면은 싣지 않는다

Example: 10

Responses

200

성공

*/*

세그먼트 대상자 계산 결과

calcNostringOptional

계산번호

Example: SC000000000001

trgtCntinteger · int64Optional

대상자수 — 0 은 실패가 아니라 정상 완료다

newCntinteger · int64Optional

신규진입수. null 이면 첫 계산

outCntinteger · int64Optional

이탈수. null 이면 첫 계산

calcStrtDtmstring · date-timeOptional

계산시작일시

sysModDtmstring · date-timeOptional

갱신된 세그먼트 수정일시(표시용)

900

업무처리 오류 내용

*/*

post/v1/marketing/segmentMgmt/calcSegmentTarget

POST /api/bo/v1/marketing/segmentMgmt/calcSegmentTarget HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "sgmtNo": "SG00000001",
  "calcGbCd": 10
}

{
  "calcNo": "SC000000000001",
  "trgtCnt": 1,
  "newCnt": 1,
  "outCnt": 1,
  "calcStrtDtm": "2026-01-01T00:00:00.000Z",
  "sysModDtm": "2026-01-01T00:00:00.000Z"
}

세그먼트 상세 조회

get

기능설명

세그먼트 정의, 조건(JSON), 계산상태 · 최근 실패일시를 함께 반환합니다.

상세설명

없거나 삭제된 세그먼트면 오류입니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

sgmtNostringRequired

세그먼트번호

Example: SG00000001

Responses

200

성공

*/*

세그먼트 상세

sgmtNostringOptional

세그먼트번호

Example: SG00000001

siteNostringOptional

사이트번호

Example: 1

sgmtNmstringOptional

세그먼트명

sgmtDescstringOptional

세그먼트설명

deptCdstringOptional

부서코드

deptNmstringOptional

부서명 — ST_DEPT_CD 조인 결과

sgmtStatCdstringOptional

세그먼트상태코드(MK023)

Example: 10

condJsonstringOptional

조건 JSON(정규화된 값)

sysModDtmstring · date-timeOptional

최종 수정일시(표시용)

lstCalcNostringOptional

최종 완료 계산번호. null 이면 계산한 적이 없다

lstTrgtCntinteger · int64Optional

최종 완료 계산의 대상자수

lstCalcStrtDtmstring · date-timeOptional

최종 완료 계산의 시작일시

lstNewCntinteger · int64Optional

최종 완료 계산의 신규진입수. null 이면 첫 계산

lstOutCntinteger · int64Optional

최종 완료 계산의 이탈수. null 이면 첫 계산

calcStatCdstringOptional

계산상태 FAIL 실패 / NONE 미계산 / DONE 완료, 종료는 null

Example: DONE

lstFailDtmstring · date-timeOptional

가장 최근 계산 시도가 실패면 그 시작일시, 아니면 null

900

업무처리 오류 내용

*/*

get/v1/marketing/segmentMgmt/getSegment

GET /api/bo/v1/marketing/segmentMgmt/getSegment?sgmtNo=SG00000001 HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "sgmtNo": "SG00000001",
  "siteNo": 1,
  "sgmtNm": "text",
  "sgmtDesc": "text",
  "deptCd": "text",
  "deptNm": "text",
  "sgmtStatCd": 10,
  "condJson": "text",
  "sysModDtm": "2026-01-01T00:00:00.000Z",
  "lstCalcNo": "text",
  "lstTrgtCnt": 1,
  "lstCalcStrtDtm": "2026-01-01T00:00:00.000Z",
  "lstNewCnt": 1,
  "lstOutCnt": 1,
  "calcStatCd": "DONE",
  "lstFailDtm": "2026-01-01T00:00:00.000Z"
}

세그먼트 사용처 조회

get

기능설명

세그먼트를 쓰는 곳(지금은 캠페인)을 최근 등록순으로 반환합니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

sgmtNostringRequired

세그먼트번호

Example: SG00000001

Responses

200

성공

*/*

세그먼트 사용처

usageTypCdstringOptional

사용처 유형 — 지금은 CMPGN(캠페인) 고정

Example: CMPGN

usageNostringOptional

사용처 번호(캠페인번호)

usageNmstringOptional

사용처 명(캠페인명)

aplyDtmstring · date-timeOptional

적용일시(캠페인 등록일시)

calcNostringOptional

계산번호

calcStrtDtmstring · date-timeOptional

계산시작일시

900

업무처리 오류 내용

*/*

get/v1/marketing/segmentMgmt/getSegmentUsageList

GET /api/bo/v1/marketing/segmentMgmt/getSegmentUsageList?sgmtNo=SG00000001 HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "usageTypCd": "CMPGN",
    "usageNo": "text",
    "usageNm": "text",
    "aplyDtm": "2026-01-01T00:00:00.000Z",
    "calcNo": "text",
    "calcStrtDtm": "2026-01-01T00:00:00.000Z"
  }
]

대상자 표본 조회

get

기능설명

계산 결과의 대상자를 페이징 조회합니다. 계산 응답으로 받은 calcNo 로 조회합니다.

상세설명

조건 매칭 근거는 저장하지 않으므로 응답에 없습니다.
회원명은 반환하지 않습니다 — 개인정보 마스킹 · 감사 대상입니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

calcNostringRequired

계산번호

Example: SC000000000001

Responses

200

성공

*/*

totalCountinteger · int32Optional

get/v1/marketing/segmentMgmt/getSegmentTargetList

GET /api/bo/v1/marketing/segmentMgmt/getSegmentTargetList?calcNo=SC000000000001 HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

성공

{
  "totalCount": 1,
  "payloads": [
    {
      "mbrNo": 1000001
    }
  ]
}

세그먼트 목록 조회

get

기능설명

세그먼트 목록을 조회합니다. 각 행에 최종 완료 계산의 대상자 수와 계산일시가 함께 나옵니다.

상세설명

대상자 수는 마지막 계산 기준입니다. 계산이 실패하면 마지막 성공 결과가 그대로 유지됩니다.
계산상태 calcStatCd: FAIL 계산 실패 · NONE 미계산 · DONE 계산 완료 · 종료는 null
cmpgnSelectYn=Y: 캠페인 선택용 — 사용 중이고 대상자 1명 이상인 세그먼트만(계산 실패 포함)

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

sgmtStatCdstringOptional

세그먼트상태코드(MK023)

Example: 10

deptCdstringOptional

부서코드

sgmtNostringOptional

세그먼트번호 LIKE 검색어

sgmtNmstringOptional

세그먼트명 LIKE 검색어

calcStatCdstringOptional

계산상태 FAIL 실패 / NONE 미계산 / DONE 완료

Example: DONE

cmpgnSelectYnstringOptional

캠페인 선택용 여부 — Y 면 사용 중 · 대상자 1명 이상만

Example: Y

Responses

200

성공

*/*

totalCountinteger · int32Optional

900

업무처리 오류 내용

*/*

get/v1/marketing/segmentMgmt/getSegmentList

GET /api/bo/v1/marketing/segmentMgmt/getSegmentList HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "totalCount": 1,
  "payloads": [
    {
      "sgmtNo": "SG00000001",
      "sgmtNm": "text",
      "sgmtStatCd": 10,
      "deptCd": "text",
      "deptNm": "text",
      "lstTrgtCnt": 1,
      "lstCalcStrtDtm": "2026-01-01T00:00:00.000Z",
      "calcStatCd": "DONE"
    }
  ]
}

조건 메타데이터 조회

get

기능설명

조건 빌더가 쓸 변수 18종의 문법 계약과 CODE_LIST 변수의 값 옵션을 반환합니다.

상세설명

정의는 자바 레지스트리, 값 옵션(회원등급 · 결제수단)만 런타임에 공통코드를 조회합니다.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

성공

*/*

세그먼트 조건 메타데이터

get/v1/marketing/segmentMgmt/getSegmentCondMeta

GET /api/bo/v1/marketing/segmentMgmt/getSegmentCondMeta HTTP/1.1
Host: api-bo.x2bee.com/
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

성공

{
  "variables": [
    {
      "varCd": "MBR_GRADE",
      "maxPeriodDays": 30,
      "allowedOps": [
        "GTE"
      ],
      "valType": "CODE_LIST",
      "periodPolicy": "NONE",
      "allowedScopes": [
        "ALL"
      ],
      "codeGroup": "ME008",
      "codeOptions": [
        {
          "cd": 10,
          "cdNm": "GREEN"
        }
      ],
      "devLabel": "회원 등급"
    }
  ]
}

이전프로모션 관리

다음마일리지 소멸 관리

마지막 업데이트 3일 전