sendgo-python 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

sendgo/__init__.py

@@ -19,11 +19,47 @@ Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
 """
 
 from .brand_message import BrandMessageService
+from .brand_template import BrandTemplateService
+from .kakao_image import (
+    MULTI_IMAGE_TYPES,
+    SINGLE_IMAGE_TYPES,
+    KakaoImageService,
+)
+from .kakao_sender import KakaoSenderService
+from .message_template import MessageTemplateService
+from .notice_template import NoticeTemplateService
+from .rejected_number import RejectedNumberService
+from .sender_registration import (
+    IDENTITY_DOCUMENT_TYPES,
+    REGISTRABLE_TYPES,
+    SenderRegistrationService,
+)
+from .webhook import WEBHOOK_EVENTS, WebhookService, verify_signature
 from .short_url import ShortUrlService
 from .client import Sendgo
 from .exceptions import SendgoError
 
-__all__ = ["Sendgo", "SendgoError", "BrandMessageService", "ShortUrlService"]
+__all__ = [
+    "Sendgo",
+    "SendgoError",
+    "BrandMessageService",
+    "ShortUrlService",
+    # 관리 API (v2 전용) — 등록 · 심사
+    "KakaoSenderService",
+    "NoticeTemplateService",
+    "BrandTemplateService",
+    "SenderRegistrationService",
+    "MessageTemplateService",
+    "KakaoImageService",
+    "RejectedNumberService",
+    "WebhookService",
+    "REGISTRABLE_TYPES",
+    "IDENTITY_DOCUMENT_TYPES",
+    "SINGLE_IMAGE_TYPES",
+    "MULTI_IMAGE_TYPES",
+    "WEBHOOK_EVENTS",
+    "verify_signature",
+]
 try:
     from importlib.metadata import PackageNotFoundError, version as _pkg_version
 

sendgo/_payload.py

@@ -0,0 +1,34 @@
+"""요청 페이로드 헬퍼.
+
+Python 쪽 인자는 snake_case, Sendgo API 는 camelCase 다. 서비스마다 매핑을
+손으로 적으면 필드가 늘 때마다 빠뜨리는 곳이 생기므로 한 곳에서 변환한다.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# 자동 변환이 틀리는 예외들. `additional_content` 는 서버가 그대로 받는다.
+_KEEP_AS_IS = {"additional_content"}
+
+
+def to_camel(key: str) -> str:
+    """`template_name` → `templateName`. 이미 camelCase 면 그대로 둔다."""
+    if key in _KEEP_AS_IS or "_" not in key:
+        return key
+
+    head, *rest = key.split("_")
+    return head + "".join(part[:1].upper() + part[1:] for part in rest)
+
+
+def camelize(payload: dict[str, Any], *, drop_none: bool = True) -> dict[str, Any]:
+    """키를 camelCase 로 바꾸고, 기본적으로 ``None`` 값을 걷어낸다.
+
+    ``None`` 을 남기면 서버가 "빈 값으로 덮어쓰기"로 읽어 기존 값을 지운다.
+    명시적으로 비우려면 빈 문자열을 넘긴다.
+    """
+    return {
+        to_camel(key): value
+        for key, value in payload.items()
+        if not (drop_none and value is None)
+    }

sendgo/brand_template.py

@@ -0,0 +1,102 @@
+"""브랜드메시지(구 친구톡) 템플릿 관리."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from ._payload import camelize
+from .http_client import HttpClient
+
+
+class BrandTemplateService:
+    """브랜드메시지 템플릿 서비스. v2 전용이며 **기업(Team) 계정 전용**이다.
+
+    알림톡 템플릿과 달리 **검수 요청 단계가 없다.** 등록하면 카카오가 바로
+    상태를 돌려주고 그 값이 ``status`` 로 나온다.
+
+    ``template_type`` 은 친구톡 표기(``FT``/``FI``/``FW``/``FL``/``FC``/``FM``/
+    ``FP``/``FA``)를 그대로 쓴다 — 서버가 chatBubbleType 으로 변환한다.
+
+    Example::
+
+        created = client.brand_templates.create(
+            kakao_sender_key=kakao_sender_key,
+            template_name="여름 세일 안내",
+            template_type="FI",
+            template_content="여름 세일이 시작되었습니다.",
+            image_url="https://mud-kage.kakao.com/....jpg",
+        )
+
+        # 동보 발송(targeting="F")에는 변수가 없는 템플릿만 쓸 수 있다
+        created["data"]["template"]["containsVariables"]
+    """
+
+    _RESOURCE = "brand-templates"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        kakao_sender_key: str | None = None,
+        search: str | None = None,
+        count: int | None = None,
+    ) -> dict[str, Any]:
+        """목록 조회."""
+        return self._http.get(
+            self._RESOURCE,
+            {"kakaoSenderKey": kakao_sender_key, "search": search, "count": count},
+        )
+
+    def show(self, template_code: str) -> dict[str, Any]:
+        """상세 조회. sendgo 코드(``KFT-...``)와 카카오 브랜드 템플릿 코드 둘 다 받는다."""
+        return self._http.get(self._path(template_code))
+
+    def create(
+        self,
+        *,
+        kakao_sender_key: str,
+        template_name: str,
+        template_type: str,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        """템플릿 등록. 선택 필드는 ``extra`` 로 넘긴다 (snake_case 자동 변환)."""
+        return self._http.post(
+            self._RESOURCE,
+            camelize(
+                {
+                    "kakao_sender_key": kakao_sender_key,
+                    "template_name": template_name,
+                    "template_type": template_type,
+                    **extra,
+                }
+            ),
+        )
+
+    def update(self, template_code: str, **fields: Any) -> dict[str, Any]:
+        """템플릿 수정. 발신프로필은 바꿀 수 없다."""
+        return self._http.put(self._path(template_code), camelize(fields))
+
+    def delete(self, template_code: str) -> dict[str, Any]:
+        """템플릿 삭제. 알림톡과 달리 카카오 쪽에서도 실제로 삭제된다."""
+        return self._http.delete(self._path(template_code))
+
+    def sync(self, template_code: str) -> dict[str, Any]:
+        """동기화. 카카오 쪽에서 이미 삭제됐으면 로컬에서도 제거하고
+        ``data.deleted: True`` 를 반환한다."""
+        return self._http.post(f"{self._path(template_code)}/sync", {})
+
+    def import_from_sender(self, kakao_sender_key: str) -> dict[str, Any]:
+        """발신프로필 단위 가져오기 — 카카오 쪽에 이미 있는 템플릿을 들여온다.
+
+        (``import`` 는 예약어라 메서드 이름에 쓸 수 없다.)
+        """
+        return self._http.post(
+            f"{self._RESOURCE}/import",
+            {"kakaoSenderKey": kakao_sender_key},
+        )
+
+    def _path(self, template_code: str) -> str:
+        return f"{self._RESOURCE}/{quote(template_code, safe='')}"

sendgo/client.py

@@ -2,11 +2,19 @@ from __future__ import annotations
 
 from .alimtalk import AlimtalkService
 from .brand_message import BrandMessageService
+from .brand_template import BrandTemplateService
 from .friendtalk import FriendtalkService
 from .http_client import HttpClient
+from .kakao_image import KakaoImageService
+from .kakao_sender import KakaoSenderService
+from .message_template import MessageTemplateService
+from .notice_template import NoticeTemplateService
+from .rejected_number import RejectedNumberService
+from .sender_registration import SenderRegistrationService
 from .short_url import ShortUrlService
 from .sms import SmsService
 from .token_manager import TokenManager
+from .webhook import WebhookService
 
 
 class Sendgo:
@@ -55,3 +63,17 @@ class Sendgo:
         # 짧은 URL — 링크 단축과 클릭 반응 분석. v2 전용.
         self.short_url     = ShortUrlService(http)
         self.sms           = SmsService(http, sms_sender_key)
+
+        # ------------------------------------------------------ 관리 API (v2)
+        # 콘솔에서만 되던 등록·심사. 발송과 달리 대부분 즉시 완료되지 않는다 —
+        # 등록 성공은 "접수됨"이지 "사용 가능"이 아니다.
+        # 카카오 채널 등록의 인증번호와 휴대폰 발신번호의 본인인증은 사람이
+        # 개입해야 하므로 API 로 대체되지 않는다.
+        self.kakao_senders       = KakaoSenderService(http)
+        self.notice_templates    = NoticeTemplateService(http)
+        self.brand_templates     = BrandTemplateService(http)
+        self.sender_registration = SenderRegistrationService(http)
+        self.message_templates   = MessageTemplateService(http)
+        self.kakao_images        = KakaoImageService(http)
+        self.rejected_numbers    = RejectedNumberService(http)
+        self.webhook             = WebhookService(http)

sendgo/http_client.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import base64
+import json
+from typing import Any
 
 import requests
 
@@ -23,10 +25,35 @@ class HttpClient:
         """GET request, used by the campaign lookup endpoints."""
         return self._request("GET", path, params=params, is_retry=False)
 
+    def put(self, path: str, body: dict) -> dict:
+        return self._request("PUT", path, body=body, is_retry=False)
+
+    def patch(self, path: str, body: dict) -> dict:
+        return self._request("PATCH", path, body=body, is_retry=False)
+
     def delete(self, path: str) -> dict:
         """`_request()` drives the verb, so DELETE only needs to skip the body."""
         return self._request("DELETE", path, is_retry=False)
 
+    def post_multipart(
+        self,
+        path: str,
+        fields: dict | None = None,
+        files: dict | None = None,
+    ) -> dict:
+        """multipart/form-data POST — 서류·이미지 첨부가 있는 관리 API 전용.
+
+        발신번호 등록과 이미지 템플릿은 JSON 으로 보낼 수 없다. multipart 에는
+        배열도 불리언도 없으므로, 리스트/딕트는 JSON 문자열로 눌러 보낸다 —
+        서버가 그렇게 받아 읽는다.
+
+        ``files`` 값은 ``requests`` 가 받는 형태를 그대로 쓴다: 열린 파일
+        객체, ``(filename, fileobj)``, ``(filename, fileobj, content_type)``.
+        같은 필드에 여러 파일을 붙이려면 리스트로 넘긴다 — 서버가
+        ``attachments[0]`` 형태를 기대하므로 인덱스를 붙여 보낸다.
+        """
+        return self._multipart_request(path, fields or {}, files or {}, is_retry=False)
+
     def _request(
         self,
         method: str,
@@ -61,6 +88,67 @@ class HttpClient:
 
         return response_body
 
+    def _multipart_request(
+        self,
+        path: str,
+        fields: dict,
+        files: dict,
+        *,
+        is_retry: bool,
+    ) -> dict:
+        url = f"{self._base_url}/api/{self._api_version}/{path}"
+        token = self._token_manager.get_token()
+
+        data: dict[str, str] = {}
+        for key, value in fields.items():
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                data[key] = "1" if value else "0"
+            elif isinstance(value, (list, dict)):
+                data[key] = json.dumps(value, ensure_ascii=False)
+            else:
+                data[key] = str(value)
+
+        payload_files: list[tuple[str, Any]] = []
+        for key, value in files.items():
+            if value is None:
+                continue
+            if isinstance(value, list):
+                for index, entry in enumerate(value):
+                    payload_files.append((f"{key}[{index}]", entry))
+            else:
+                payload_files.append((key, value))
+
+        # 세션 기본 헤더의 Content-Type: application/json 을 반드시 비워야 한다.
+        # 남겨 두면 requests 가 붙이는 multipart boundary 를 덮어써서 서버가
+        # 본문을 통째로 파싱하지 못한다.
+        resp = self._session.request(
+            "POST",
+            url,
+            data=data or None,
+            files=payload_files or None,
+            headers={
+                "Authorization": self._make_bearer(token),
+                "Accept": "application/json",
+                "Content-Type": None,
+            },
+            # 파일 업로드는 JSON 요청보다 오래 걸린다.
+            timeout=60,
+        )
+
+        response_body = resp.json() if resp.content else {}
+
+        if not resp.ok:
+            error_code = response_body.get("code")
+            endpoint = path.split("/")[-1]
+            if not is_retry and self._token_manager.should_refresh(resp.status_code, error_code):
+                self._token_manager.invalidate()
+                return self._multipart_request(path, fields, files, is_retry=True)
+            raise SendgoError.from_response(resp.status_code, response_body, endpoint, self._api_version)
+
+        return response_body
+
     def _make_bearer(self, token: str) -> str:
         if self._api_version == "v2":
             return f"Bearer {token}"

sendgo/kakao_image.py

@@ -0,0 +1,67 @@
+"""카카오 이미지 업로드 — 브랜드메시지 템플릿에 넣을 URL 발급."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .http_client import HttpClient
+
+#: 파일 하나를 올리고 URL 하나를 받는 유형.
+SINGLE_IMAGE_TYPES = (
+    "alimtalk",
+    "alimtalk_highlight",
+    "default",
+    "wide",
+    "wide_item_list_first",
+)
+
+#: 파일 여러 개를 올리고 URL 목록을 받는 유형과 최대 개수.
+MULTI_IMAGE_TYPES = {
+    "wide_item_list": 4,
+    "carousel_feed": 10,
+    "carousel_commerce": 11,
+}
+
+
+class KakaoImageService:
+    """카카오 이미지 업로드. v2 전용이며 **기업(Team) 계정 전용**이다.
+
+    브랜드메시지 템플릿의 ``imageUrl`` 은 아무 URL 이나 되는 게 아니라
+    **카카오가 호스팅하는 URL** 이어야 한다. 그 URL 을 얻는 방법이 이
+    업로드뿐이다.
+
+    Example::
+
+        with open("banner.jpg", "rb") as f:
+            uploaded = client.kakao_images.upload(
+                "default", ("banner.jpg", f, "image/jpeg")
+            )
+
+        client.brand_templates.create(
+            kakao_sender_key=kakao_sender_key,
+            template_name="여름 세일 안내",
+            template_type="FI",
+            image_url=uploaded["data"]["imageUrl"],
+        )
+    """
+
+    _RESOURCE = "kakao-images"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def types(self) -> dict[str, Any]:
+        """업로드 가능한 유형과 제약."""
+        return self._http.get(f"{self._RESOURCE}/types")
+
+    def upload(self, image_type: str, image: Any) -> dict[str, Any]:
+        """단일 이미지 업로드. jpg/png, 2MB 이하. ``data.imageUrl`` 을 받는다."""
+        return self._http.post_multipart(self._path(image_type), files={"image": image})
+
+    def upload_many(self, image_type: str, images: list[Any]) -> dict[str, Any]:
+        """다중 이미지 업로드. 유형별 최대 개수가 다르다."""
+        return self._http.post_multipart(self._path(image_type), files={"images": images})
+
+    def _path(self, image_type: str) -> str:
+        return f"{self._RESOURCE}/{quote(image_type, safe='')}"

sendgo/kakao_sender.py

@@ -0,0 +1,127 @@
+"""카카오 발신프로필(채널) 관리 — 등록 · 동기화 · 브랜드메시지 타겟팅 신청."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .http_client import HttpClient
+
+
+class KakaoSenderService:
+    """카카오 채널 관리 서비스. v2 전용이며 **기업(Team) 계정 전용**이다.
+
+    채널 등록은 두 단계다. 카카오가 인증번호를 채널 관리자 **휴대폰으로 SMS
+    발송**하므로 완전 무인 자동화는 불가능하다 — 사람이 문자를 받아
+    :meth:`create` 에 넣어야 한다.
+
+    Example::
+
+        # 1단계 — 관리자 휴대폰으로 인증번호 발송 (응답에 번호는 없다)
+        client.kakao_senders.request_token("@my-channel", "01012345678")
+
+        # 2단계 — 사람이 받은 인증번호로 발신프로필 생성
+        created = client.kakao_senders.create(
+            token="123456",
+            yellow_id="@my-channel",
+            phone_number="01012345678",
+            category_code="001001",
+        )
+
+        kakao_sender_key = created["data"]["sender"]["kakaoSenderKey"]
+    """
+
+    _RESOURCE = "kakao-senders"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def request_token(self, yellow_id: str, phone_number: str) -> dict[str, Any]:
+        """1단계 — 채널 인증번호 발송.
+
+        응답에 인증번호는 들어있지 않다. 카카오가 ``phone_number`` 로 SMS 를 보낸다.
+        """
+        return self._http.post(
+            f"{self._RESOURCE}/token",
+            {"yellowId": yellow_id, "phoneNumber": phone_number},
+        )
+
+    def create(
+        self,
+        *,
+        token: str,
+        yellow_id: str,
+        phone_number: str,
+        category_code: str,
+    ) -> dict[str, Any]:
+        """2단계 — 발신프로필 등록.
+
+        이미 등록된 채널을 다시 등록해도 오류가 아니다. 카카오가 같은 senderKey 를
+        돌려주고 서버가 기존 행을 갱신한다.
+        """
+        return self._http.post(
+            self._RESOURCE,
+            {
+                "token": token,
+                "yellowId": yellow_id,
+                "phoneNumber": phone_number,
+                "categoryCode": category_code,
+            },
+        )
+
+    def list(self) -> dict[str, Any]:
+        """목록 조회."""
+        return self._http.get(self._RESOURCE)
+
+    def show(self, kakao_sender_key: str) -> dict[str, Any]:
+        """상세 조회."""
+        return self._http.get(f"{self._RESOURCE}/{quote(kakao_sender_key, safe='')}")
+
+    def categories(self, category_code: str | None = None) -> dict[str, Any]:
+        """카테고리 조회. 등록 시 ``category_code`` 로 넣을 값이다."""
+        return self._http.get(
+            f"{self._RESOURCE}/categories",
+            {"categoryCode": category_code} if category_code else None,
+        )
+
+    def sync(self, kakao_sender_key: str | None = None) -> dict[str, Any]:
+        """상태 동기화. 키를 주면 단건, 없으면 팀 전체.
+
+        채널이 카카오 쪽에서 차단·휴면되면 발송이 조용히 실패하기 시작한다.
+        그 사실을 먼저 알 방법은 이 호출뿐이므로 하루 한 번 정도 돌리는 게 좋다.
+        """
+        path = (
+            f"{self._RESOURCE}/{quote(kakao_sender_key, safe='')}/sync"
+            if kakao_sender_key
+            else f"{self._RESOURCE}/sync"
+        )
+        return self._http.post(path, {})
+
+    def upload_brand_message_evidence(
+        self,
+        kakao_sender_key: str,
+        evidence: Any,
+    ) -> dict[str, Any]:
+        """브랜드메시지 M 신청에 필요한 광고성 정보 수신동의 증적자료 업로드.
+
+        jpg/png, 5MB 이하. ``evidence`` 는 ``requests`` 가 받는 형태를 그대로 쓴다
+        — 열린 파일 객체나 ``(filename, fileobj)`` 튜플.
+        """
+        return self._http.post_multipart(
+            f"{self._RESOURCE}/{quote(kakao_sender_key, safe='')}/brand-message/evidence",
+            files={"evidence": evidence},
+        )
+
+    def apply_brand_message_targeting(
+        self,
+        kakao_sender_key: str,
+        target_type: str,
+    ) -> dict[str, Any]:
+        """브랜드메시지 ``M``(마케팅) / ``N``(정보성) 사용 신청.
+
+        결과는 즉시 확정되지 않는다. 발신프로필의 ``brandMessageStatus`` 로 확인한다.
+        """
+        return self._http.post(
+            f"{self._RESOURCE}/{quote(kakao_sender_key, safe='')}/brand-message/apply",
+            {"targetType": target_type},
+        )

sendgo/message_template.py

@@ -0,0 +1,79 @@
+"""문자(SMS/LMS/MMS) 상용구 템플릿."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from ._payload import camelize
+from .http_client import HttpClient
+
+
+class MessageTemplateService:
+    """문자 템플릿 서비스. v2 전용.
+
+    카카오 템플릿과 달리 **검수가 없어** 만들면 바로 쓸 수 있고, 기업 계정이
+    아니어도 된다.
+
+    Example::
+
+        client.message_templates.create(
+            message_tran_type="LMS",
+            message_tran_subject="주문 안내",
+            message_tran_msg="주문이 접수되었습니다.",
+        )
+    """
+
+    _RESOURCE = "message-templates"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        message_type: str | None = None,
+        search: str | None = None,
+        count: int | None = None,
+    ) -> dict[str, Any]:
+        """목록 조회."""
+        return self._http.get(
+            self._RESOURCE,
+            {"messageType": message_type, "search": search, "count": count},
+        )
+
+    def show(self, template_key: str) -> dict[str, Any]:
+        """상세 조회."""
+        return self._http.get(self._path(template_key))
+
+    def create(
+        self,
+        *,
+        message_tran_type: str,
+        message_tran_msg: str,
+        message_tran_subject: str | None = None,
+        is_favorite: bool = False,
+    ) -> dict[str, Any]:
+        """등록. LMS·MMS 는 ``message_tran_subject`` 가 필수다."""
+        return self._http.post(
+            self._RESOURCE,
+            camelize(
+                {
+                    "message_tran_type": message_tran_type,
+                    "message_tran_msg": message_tran_msg,
+                    "message_tran_subject": message_tran_subject,
+                    "is_favorite": is_favorite,
+                }
+            ),
+        )
+
+    def update(self, template_key: str, **fields: Any) -> dict[str, Any]:
+        """수정."""
+        return self._http.put(self._path(template_key), camelize(fields))
+
+    def delete(self, template_key: str) -> dict[str, Any]:
+        """삭제 (소프트 삭제 — 목록에서만 사라진다)."""
+        return self._http.delete(self._path(template_key))
+
+    def _path(self, template_key: str) -> str:
+        return f"{self._RESOURCE}/{quote(template_key, safe='')}"