Gnuboard7/plugins/_bundled/sirsoft-marketing/docs/api/settings.md

Settings API 레퍼런스

소유: plugin sirsoft-marketing · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.

---

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Settings 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

---

GET /api/plugins/sirsoft-marketing/settings

• 라우트명: api.plugins.sirsoft-marketing.settings
• 컨트롤러: Plugins\Sirsoft\Marketing\Http\Controllers\MarketingSettingsController@settings
• 인증/권한: 공개 (인증 불필요)

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/plugins/sirsoft-marketing/settings HTTP/1.1
Host: api.example.com
Accept: application/json

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드	타입	실측 예시값	용도/설명
marketing_consent_enabled	boolean	true	광고성 정보 수신 전체 동의 축의 노출 여부. false 면 회원가입/마이페이지에서 해당 동의 UI 를 렌더하지 않는다(미설정 시 기본 true).
marketing_consent_terms_slug	string	marketing-terms	광고성 정보 수신 약관 페이지 라우팅에 쓰는 slug. 미설정 시 null. 프론트는 값 자체를 링크 대상에만 사용한다.
marketing_consent_terms_slug_set	boolean	true	광고성 정보 수신 약관 slug 존재 여부. 프론트는 이 플래그로 약관 링크 표시 여부를 판정한다.
third_party_consent_enabled	boolean	true	제3자 제공 동의 축의 노출 여부. false 면 해당 동의 UI 를 렌더하지 않는다(미설정 시 기본 false).
third_party_consent_terms_slug	null	null	제3자 제공 약관 페이지 라우팅에 쓰는 slug. 미설정 시 null.
third_party_consent_terms_slug_set	boolean	false	제3자 제공 약관 slug 존재 여부. 프론트의 약관 링크 표시 판정에 쓴다.
info_disclosure_enabled	boolean	true	정보 이용 안내 동의 축의 노출 여부. false 면 해당 안내 UI 를 렌더하지 않는다(미설정 시 기본 false).
info_disclosure_terms_slug	null	null	정보 이용 안내 약관 페이지 라우팅에 쓰는 slug. 미설정 시 null.
info_disclosure_terms_slug_set	boolean	false	정보 이용 안내 약관 slug 존재 여부. 프론트의 약관 링크 표시 판정에 쓴다.
channels	array	[{"key":"email_subscription","label":"광고성 이메일 수신","label_…	MarketingConsentService::getRegisteredChannels() 가 반환하는 활성 채널 목록. 각 원소는 key·현재 로케일 해석 label·로케일 맵 원본 label_i18n·enabled·terms_slug·terms_slug_set 를 갖는다. 폼의 반복 렌더링에 그대로 쓰인다.

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "성공적으로 처리되었습니다.",
    "data": {
        "marketing_consent_enabled": true,
        "marketing_consent_terms_slug": "marketing-terms",
        "marketing_consent_terms_slug_set": true,
        "third_party_consent_enabled": true,
        "third_party_consent_terms_slug": null,
        "third_party_consent_terms_slug_set": false,
        "info_disclosure_enabled": true,
        "info_disclosure_terms_slug": null,
        "info_disclosure_terms_slug_set": false,
        "channels": [
            {
                "key": "email_subscription",
                "label": "광고성 이메일 수신",
                "label_i18n": {
                    "ko": "광고성 이메일 수신",
                    "en": "Email Marketing"
                },
                "enabled": true,
                "terms_slug": null,
                "terms_slug_set": false
            }
        ]
    }
}

에러 응답

에러 없음 (공개 조회 — 인증·검증·도메인 예외 경로가 없다. 요청 파라미터가 없어 422 가 발생하지 않고, PublicBaseController 라 401/403 도 없으며, 설정 미존재 시에도 기본값으로 200 을 반환한다).

설명

비로그인 상태에서도 조회 가능한 공개 설정 엔드포인트다(PublicBaseController). 회원가입 폼과 마이페이지의 마케팅 동의 UI 가, 어떤 동의 항목을 노출할지·약관 링크가 존재하는지·어떤 채널을 반복 렌더링할지 결정하기 위해 소비한다. plugin_settings 저장값과 channels JSON 을 조합해 반환하며 별도 DB 모델을 두지 않는다.

• 약관 slug 은 값을 노출하지 않는다. 각 동의 항목마다 실제 slug(*_terms_slug)와 존재 플래그(*_terms_slug_set)를 함께 반환하되, slug 미설정 시 값은 null 이고 플래그는 false 다. 프론트는 링크 표시 여부를 *_terms_slug_set 으로 판정하고, slug 값 자체는 약관 페이지 라우팅에만 쓴다.
• 세 가지 법적 동의 축: marketing_consent_*(광고성 정보 수신 전체 동의), third_party_consent_*(제3자 제공), info_disclosure_*(정보 이용 안내). 각 축의 *_enabled 가 false 면 해당 동의 UI 를 렌더하지 않는다. marketing_consent_enabled 는 미설정 시 기본 true, 나머지 두 축은 기본 false.
• channels 배열은 MarketingConsentService::getRegisteredChannels() 가 반환하는 활성 채널만 담는다. 각 원소는 key, 현재 로케일로 해석된 label, 로케일 맵 원본 label_i18n, enabled, 그리고 slug 값(terms_slug)과 존재 플래그(terms_slug_set)를 갖는다. 회원가입/마이페이지 폼의 iteration 렌더링에 그대로 쓰인다.
• label 은 요청 시점의 app()->getLocale() 기준으로 해석되며, 해당 로케일 라벨이 없으면 fallback_locale(기본 ko) → key 순으로 폴백한다.

응답 예시 (실측)

{
  "success": true,
  "data": {
    "marketing_consent_enabled": true,
    "marketing_consent_terms_slug": "marketing-terms",
    "marketing_consent_terms_slug_set": true,
    "third_party_consent_enabled": true,
    "third_party_consent_terms_slug": null,
    "third_party_consent_terms_slug_set": false,
    "info_disclosure_enabled": true,
    "info_disclosure_terms_slug": null,
    "info_disclosure_terms_slug_set": false,
    "channels": [
      {
        "key": "email_subscription",
        "label": "광고성 이메일 수신",
        "label_i18n": { "ko": "광고성 이메일 수신", "en": "Marketing email" },
        "enabled": true,
        "terms_slug": null,
        "terms_slug_set": false
      }
    ]
  },
  "message": null,
  "error": null
}