브랜드 식별자 수정¶
POST /api/v1/account/change_brand_key
개요¶
계정의 브랜드 식별자를 일괄 수정합니다.
호출 전 준비 및 사용 단계¶
w 권한이 있는 External 자격 증명이 필요합니다. accountUUIDs는 계정 목록에서 가져오며, brandKey는 대상 사이트 관리자가 제공하고 해당 사이트의 허용 집합에 속해야 합니다. 계정의 brandKey와 업데이트 시간만 변경하고 계정 프로필 캐시를 정리하며, 워크스페이스, 구성원 역할 또는 이력 데이터를 마이그레이션하지 않고 워크스페이스 자체의 브랜드도 수정하지 않습니다. 전환하기 전에 대상 브랜드의 로그인 진입점과 연동 구성이 준비되었는지 확인합니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략하고 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417가져오기 또는 입력 방법: 이 페이지의 예제는 이 고정 버전을 사용하며 예제 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API에는 w 자격 증명이 필요합니다. 예: <external-access-key>가져오기 또는 입력 방법: 사이트 관리자가 External API AK를 할당하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다. 예: 97d275ee9f774315a7885ba7347acbd9가져오기 또는 입력 방법: 매 요청마다 uuid.uuid4().hex를 새로 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 뒤 HMAC-SHA256을 적용하고 hex 다이제스트를 구합니다. 예: <hmac-sha256-hex>가져오기 또는 입력 방법: External API 서명 인증에 따라 대응하는 SK로 계산하며, 전체 실행 가능한 템플릿은 아래와 같습니다. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예제 시간을 재사용할 수 없습니다. 예: 1785427200가져오기 또는 입력 방법: 전송 시 str(int(time.time()))으로 현재 Unix 초 문자열을 생성합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| accountUUIDs[*] | string | 단일 대상 계정 UUID 문자열이며 워크스페이스 UUID가 아닙니다. 예: acnt_example001가져오기 또는 입력 방법: 계정 목록의 content.data[].uuid에서 항목별로 가져옵니다. |
|
| accountUUIDs | array | Y | 대상 계정 UUID 배열입니다. 클라이언트는 먼저 범위를 확인하고 비어 있지 않은 문자열 목록을 전송해야 합니다. 빈 배열은 모든 계정에 일괄 영향을 주지 않으며, 알 수 없거나 삭제된 UUID는 무시됩니다. null 허용: False 예: ["acnt_example001"]가져오기 또는 입력 방법: 계정 목록의 content.data[].uuid에서 항목별로 가져오며, wksp_ 워크스페이스 UUID를 입력하지 마세요. |
| brandKey | string | Y | 필수 문자열이며 브랜드 웹사이트 URL이 아닙니다. null 허용: False 예: guance가져오기 또는 입력 방법: 사이트 관리자에게 대상 사이트에서 허용되는 브랜드 식별자를 확인합니다. |
파라미터 추가 설명¶
사이트 수준 External API 자격 증명을 사용하며, 인증 방식은 External API 서명 인증을 참조합니다. 아래 예제는 v20240417 서명 버전을 사용하며, 서명 경로, Query 인코딩 및 원본 요청 본문은 실제 전송 내용과 완전히 일치해야 합니다. 반환되는 계정 프로필에는 password 필드가 포함되지 않으며, mfaSecret은 고정 마스크일 뿐 로그인에 사용할 수 있는 키가 아닙니다. 동일한 대상 brandKey를 반복 제출해도 업데이트 시간이 변경될 수 있으며, 이 작업으로 기존 로그인 Token을 강제로 취소하지는 않습니다.
요청 예제¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/account/change_brand_key'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'brandKey': 'guance'}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, Content-Type은 application/json이며 통합 응답 래퍼를 사용합니다. 비즈니스 데이터는 content에 있습니다. External API는 declaration을 자동으로 추가하지 않으며, 목록 페이지네이션은 content.pageInfo에 유지됩니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 성공 시 true입니다. 빈 배열, 알 수 없거나 삭제된 UUID는 어떤 계정도 수정하지 않으며 이 경우에도 true를 반환할 수 있습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조합니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않습니다. | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | 요청 본문 JSON의 최상위가 객체가 아닙니다. | 일부 json 파일 형식 오류 | JSON 객체를 사용하고 배열, 문자열 또는 null을 최상위로 전송하지 마세요. |
| 406 | ft.InvalidBrandKey | brandKey가 대상 사이트의 허용 집합에 없습니다. | 브랜드 식별자 {}가 유효하지 않습니다. |
사이트 관리자에게 해당 사이트에서 허용되는 브랜드 식별자를 확인한 후 원래 값을 입력합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 비동기 작업 전달 또는 명시적으로 처리되지 않은 필드 예외 | 내부 오류 | traceId를 저장하고 관리자에게 문의하세요. 쓰기 요청은 먼저 계정 현재 상태를 다시 조회하고 확인한 후 재시도 여부를 결정해야 하며, 500을 곧바로 미적용으로 간주해서는 안 됩니다. |