sendgo-python 1.0.1__py3-none-any.whl

sendgo/__init__.py

@@ -0,0 +1,25 @@
+"""
+Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
+
+사용법:
+    from sendgo import Sendgo
+
+    client = Sendgo(
+        access_key="your_access_key",
+        secret_key="your_secret_key",
+        kakao_sender_key="your_kakao_key",
+        sms_sender_key="your_sms_key",
+        api_version="v2",
+    )
+
+    client.alimtalk.send(
+        template_code="ORDER_CONFIRM_001",
+        contacts=[{"contact": "01012345678", "var1": "ORD-001"}],
+    )
+"""
+
+from .client import Sendgo
+from .exceptions import SendgoError
+
+__all__ = ["Sendgo", "SendgoError"]
+__version__ = "1.0.0"

sendgo/alimtalk.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from .http_client import HttpClient
+
+
+class AlimtalkService:
+    """카카오 알림톡 전송 서비스.
+
+    Example::
+
+        client.alimtalk.send(
+            template_code="ORDER_CONFIRM_001",
+            contacts=[{"contact": "01012345678", "var1": "ORD-001"}],
+        )
+    """
+
+    def __init__(self, http: HttpClient, kakao_sender_key: str | None, sms_sender_key: str | None) -> None:
+        self._http = http
+        self._kakao_sender_key = kakao_sender_key
+        self._sms_sender_key = sms_sender_key
+
+    def send(
+        self,
+        *,
+        template_code: str,
+        contacts: list[dict],
+        schedule_type: Literal["DIRECTLY", "SCHEDULED"] = "DIRECTLY",
+        at: str | None = None,
+        replace_sms: Literal["Y", "N"] = "N",
+        sms_subject: str | None = None,
+        sms_content: str | None = None,
+    ) -> dict:
+        """알림톡을 전송합니다.
+
+        Args:
+            template_code: 승인된 알림톡 템플릿 코드 (필수)
+            contacts: 수신자 목록. 각 dict에 contact(필수), name, var1~var8 포함 가능
+            schedule_type: 발송 유형 (DIRECTLY | SCHEDULED)
+            at: 예약 발송 시각 (예: "2026-04-01 09:00:00")
+            replace_sms: 알림톡 실패 시 SMS 대체 발송 여부
+            sms_subject: 대체 SMS 제목
+            sms_content: 대체 SMS 내용
+        """
+        body: dict = {
+            "at": at,
+            "scheduleType": schedule_type,
+            "templateCode": template_code,
+            "replaceSms": replace_sms,
+            "smsSubject": sms_subject if replace_sms == "Y" else None,
+            "smsContent": sms_content if replace_sms == "Y" else None,
+            "contacts": contacts,
+            "kakaoSenderKey": self._kakao_sender_key,
+            "senderKey": self._sms_sender_key,
+        }
+        return self._http.post("notices/send", body)

sendgo/client.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from .alimtalk import AlimtalkService
+from .friendtalk import FriendtalkService
+from .http_client import HttpClient
+from .sms import SmsService
+from .token_manager import TokenManager
+
+
+class Sendgo:
+    """Sendgo Python SDK 메인 클라이언트.
+
+    Example::
+
+        from sendgo import Sendgo
+
+        client = Sendgo(
+            access_key="your_access_key",
+            secret_key="your_secret_key",
+            kakao_sender_key="your_kakao_key",
+            sms_sender_key="your_sms_key",
+            api_version="v2",
+        )
+
+        # 알림톡 전송
+        client.alimtalk.send(
+            template_code="ORDER_CONFIRM_001",
+            contacts=[{"contact": "01012345678", "var1": "ORD-001"}],
+        )
+
+        # SMS 전송
+        client.sms.send_sms(content="인증번호: 123456", contacts=[{"contact": "01012345678"}])
+    """
+
+    def __init__(
+        self,
+        *,
+        access_key: str,
+        secret_key: str,
+        kakao_sender_key: str | None = None,
+        sms_sender_key: str | None = None,
+        api_version: str = "v1",
+        base_url: str = "https://sendgo.io",
+    ) -> None:
+        token_manager = TokenManager(base_url, access_key, secret_key, api_version)
+        http = HttpClient(token_manager, base_url, api_version)
+
+        self.alimtalk   = AlimtalkService(http, kakao_sender_key, sms_sender_key)
+        self.friendtalk = FriendtalkService(http, kakao_sender_key, sms_sender_key)
+        self.sms        = SmsService(http, sms_sender_key)

sendgo/exceptions.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+
+class SendgoError(Exception):
+    """Sendgo API 호출 실패 시 발생하는 예외."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 0,
+        error_code: str | None = None,
+        endpoint: str = "",
+        api_version: str = "",
+        response_body: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.endpoint = endpoint
+        self.api_version = api_version
+        self.response_body = response_body or {}
+
+    @classmethod
+    def from_response(
+        cls,
+        status: int,
+        body: dict,
+        endpoint: str,
+        api_version: str,
+    ) -> "SendgoError":
+        error_code = body.get("code")
+        error_message = body.get("message", "Unknown error")
+        msg = f"HTTP {status}"
+        if error_code:
+            msg += f" [{error_code}]"
+        msg += f" {error_message}"
+        return cls(
+            msg,
+            status_code=status,
+            error_code=error_code,
+            endpoint=endpoint,
+            api_version=api_version,
+            response_body=body,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"SendgoError(status={self.status_code}, "
+            f"error_code={self.error_code!r}, "
+            f"endpoint={self.endpoint!r})"
+        )

sendgo/friendtalk.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .http_client import HttpClient
+
+FriendtalkMessageType = Literal["FT", "FI", "FW", "FL", "FM", "FC", "FA", "FP"]
+
+
+class FriendtalkService:
+    """카카오 친구톡 전송 서비스.
+
+    Example::
+
+        client.friendtalk.send(
+            content="안녕하세요! 이번 주 특가 이벤트입니다.",
+            contacts=[{"contact": "01012345678"}],
+        )
+    """
+
+    def __init__(self, http: HttpClient, kakao_sender_key: str | None, sms_sender_key: str | None) -> None:
+        self._http = http
+        self._kakao_sender_key = kakao_sender_key
+        self._sms_sender_key = sms_sender_key
+
+    def send(
+        self,
+        *,
+        content: str,
+        contacts: list[dict],
+        message_type: FriendtalkMessageType = "FT",
+        schedule_type: Literal["DIRECTLY", "SCHEDULED"] = "DIRECTLY",
+        at: str | None = None,
+        buttons: list[dict] | None = None,
+        image_url: str | None = None,
+        image_link: str | None = None,
+        ad_flag: Literal["Y", "N"] = "Y",
+        wide: Literal["Y", "N"] = "N",
+        adult: Literal["Y", "N"] = "N",
+        header: str | None = None,
+        replace_sms: Literal["Y", "N"] = "N",
+        sms_subject: str | None = None,
+        sms_content: str | None = None,
+    ) -> dict:
+        """친구톡을 전송합니다."""
+        body: dict[str, Any] = {
+            "at": at,
+            "scheduleType": schedule_type,
+            "messageType": message_type,
+            "content": content,
+            "buttons": buttons or [],
+            "image": None,
+            "imageUrl": image_url,
+            "imageLink": image_link,
+            "adFlag": ad_flag,
+            "wide": wide,
+            "adult": adult,
+            "header": header,
+            "replaceSms": replace_sms,
+            "smsSubject": sms_subject if replace_sms == "Y" else None,
+            "smsContent": sms_content if replace_sms == "Y" else None,
+            "contacts": contacts,
+            "kakaoSenderKey": self._kakao_sender_key,
+            "senderKey": self._sms_sender_key,
+        }
+        return self._http.post("friends/send", body)

sendgo/http_client.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import base64
+
+import requests
+
+from .exceptions import SendgoError
+from .token_manager import TokenManager
+
+
+class HttpClient:
+    def __init__(self, token_manager: TokenManager, base_url: str, api_version: str) -> None:
+        self._token_manager = token_manager
+        self._base_url = base_url
+        self._api_version = api_version
+        self._session = requests.Session()
+        self._session.headers.update({"Content-Type": "application/json"})
+
+    def post(self, path: str, body: dict) -> dict:
+        return self._do_post(path, body, is_retry=False)
+
+    def _do_post(self, path: str, body: dict, *, is_retry: bool) -> dict:
+        url = f"{self._base_url}/api/{self._api_version}/{path}"
+        token = self._token_manager.get_token()
+
+        resp = self._session.post(
+            url,
+            json=body,
+            headers={"Authorization": self._make_bearer(token)},
+            timeout=15,
+        )
+
+        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._do_post(path, body, 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}"
+        return "Bearer " + base64.b64encode(token.encode()).decode()

sendgo/sms.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .http_client import HttpClient
+
+
+class SmsService:
+    """SMS / LMS / MMS 전송 서비스.
+
+    Example::
+
+        client.sms.send_sms(content="인증번호: 123456", contacts=[{"contact": "01012345678"}])
+        client.sms.send_lms(subject="[공지]", content="...", contacts=[...])
+    """
+
+    def __init__(self, http: HttpClient, sms_sender_key: str | None) -> None:
+        self._http = http
+        self._sms_sender_key = sms_sender_key
+
+    def send_sms(self, *, content: str, contacts: list[dict], **kwargs: Any) -> dict:
+        """SMS 전송 (90자 이하)."""
+        return self.send(content=content, contacts=contacts, message_type="SMS", **kwargs)
+
+    def send_lms(self, *, content: str, contacts: list[dict], **kwargs: Any) -> dict:
+        """LMS 전송 (장문, 2,000자 이하)."""
+        return self.send(content=content, contacts=contacts, message_type="LMS", **kwargs)
+
+    def send_mms(self, *, content: str, contacts: list[dict], **kwargs: Any) -> dict:
+        """MMS 전송 (멀티미디어)."""
+        return self.send(content=content, contacts=contacts, message_type="MMS", **kwargs)
+
+    def send(
+        self,
+        *,
+        content: str,
+        contacts: list[dict],
+        message_type: Literal["SMS", "LMS", "MMS"] = "SMS",
+        campaign_type: Literal["MESSAGE", "ADVERTISE", "ELECTION"] = "MESSAGE",
+        schedule_type: Literal["DIRECTLY", "SCHEDULED"] = "DIRECTLY",
+        at: str | None = None,
+        subject: str | None = None,
+        files: list | None = None,
+    ) -> dict:
+        """문자 메시지 전송."""
+        body: dict[str, Any] = {
+            "campaignType": campaign_type,
+            "messageType": message_type,
+            "scheduleType": schedule_type,
+            "at": at,
+            "subject": subject,
+            "content": content,
+            "files": files or [],
+            "contacts": contacts,
+            "senderKey": self._sms_sender_key,
+        }
+        return self._http.post("messages/send", body)

sendgo/token_manager.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import base64
+import threading
+import time
+from typing import TYPE_CHECKING
+
+import requests
+
+from .exceptions import SendgoError
+
+if TYPE_CHECKING:
+    pass
+
+_NO_REFRESH_CODES = frozenset({
+    "INVALID_AUTH_HEADER", "INVALID_BASIC_AUTH", "INVALID_BASIC_AUTH_PAYLOAD",
+    "INVALID_ACCESS_KEY", "INVALID_SECRET_KEY", "ACCESS_KEY_NOT_APPROVED",
+    "TEAM_REQUIRED_FOR_KAKAO", "IP_NOT_ALLOWED", "INVALID_SENDER_KEY", "INVALID_KAKAO_SENDER_KEY",
+})
+
+_TOKEN_TTL = 50 * 60  # 50분
+
+
+class TokenManager:
+    """토큰 발급 및 50분 캐시 관리."""
+
+    def __init__(self, base_url: str, access_key: str, secret_key: str, api_version: str) -> None:
+        self._base_url = base_url
+        self._access_key = access_key
+        self._secret_key = secret_key
+        self._api_version = api_version
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+        self._lock = threading.Lock()
+
+    def get_token(self) -> str:
+        with self._lock:
+            if self._token and time.monotonic() < self._expires_at:
+                return self._token
+            return self._fetch_token()
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._token = None
+            self._expires_at = 0.0
+
+    def should_refresh(self, status: int, error_code: str | None) -> bool:
+        if status not in (401, 403):
+            return False
+        if self._api_version == "v2" and error_code in _NO_REFRESH_CODES:
+            return False
+        return True
+
+    def _fetch_token(self) -> str:
+        url = f"{self._base_url}/api/{self._api_version}/token"
+        credentials = base64.b64encode(f"{self._access_key}:{self._secret_key}".encode()).decode()
+
+        resp = requests.post(url, headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Basic {credentials}",
+        }, timeout=10)
+
+        body = resp.json() if resp.content else {}
+
+        if not resp.ok or not body.get("data", {}).get("token"):
+            raise SendgoError.from_response(resp.status_code, body, "token", self._api_version)
+
+        self._token = body["data"]["token"]
+        self._expires_at = time.monotonic() + _TOKEN_TTL
+        return self._token

sendgo_python-1.0.1.dist-info/METADATA

@@ -0,0 +1,428 @@
+Metadata-Version: 2.4
+Name: sendgo-python
+Version: 1.0.1
+Summary: Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
+Author-email: Sendgo <dev@sendgo.io>
+License: MIT
+Project-URL: Homepage, https://sendgo.io
+Project-URL: Repository, https://github.com/sendgo-dev/sendgo-python
+Keywords: sendgo,kakao,alimtalk,sms,notification,korea
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == "async"
+
+# sendgo-python
+
+> **Python / Django / FastAPI에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 SDK**
+
+[![PyPI version](https://img.shields.io/pypi/v/sendgo-python?logo=pypi)](https://pypi.org/project/sendgo-python/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python)](https://python.org)
+[![Downloads](https://img.shields.io/pypi/dm/python)](https://pypi.org/project/sendgo-python/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+`sendgo-python`은 [Sendgo](https://sendgo.io) 알림 API를 위한 공식 Python SDK입니다.
+**`requests` 하나만 의존하며**, 완전한 타입 힌트(Type Hints)를 제공합니다.
+Django, FastAPI, Flask, Celery 등 모든 Python 환경에서 사용할 수 있습니다.
+
+---
+
+## 목차
+
+- [Sendgo란?](#sendgo란)
+- [주요 기능](#주요-기능)
+- [설치](#설치)
+- [빠른 시작](#빠른-시작)
+- [상세 사용법](#상세-사용법)
+  - [카카오 알림톡](#카카오-알림톡)
+  - [카카오 친구톡](#카카오-친구톡)
+  - [SMS / LMS / MMS](#sms--lms--mms)
+- [프레임워크 통합](#프레임워크-통합)
+  - [Django](#django)
+  - [FastAPI](#fastapi)
+  - [Celery 비동기 발송](#celery-비동기-발송)
+- [예외 처리](#예외-처리)
+- [설정 옵션](#설정-옵션)
+- [자주 묻는 질문](#자주-묻는-질문-faq)
+- [관련 패키지](#관련-패키지)
+
+---
+
+## Sendgo란?
+
+[Sendgo](https://sendgo.io)는 대한민국 기업과 개발자를 위한 **통합 알림 발송 플랫폼**입니다.
+
+- **카카오 알림톡**: 카카오톡 채널을 통한 정보성 메시지 (주문 확인, 배송 안내, 예약 확인 등)
+- **카카오 친구톡**: 마케팅/이벤트 메시지 (쿠폰, 프로모션 등)
+- **SMS / LMS / MMS**: 전통적인 문자 메시지
+- **자동 대체 발송**: 알림톡 실패 시 SMS로 자동 전환
+
+---
+
+## 주요 기능
+
+| 기능 | 설명 |
+|------|------|
+| **최소 의존성** | `requests` 하나만 필요 |
+| **완전한 타입 힌트** | 모든 파라미터와 반환값에 타입 정의 |
+| **스레드 안전 토큰 관리** | `threading.Lock` 기반, 멀티스레드 환경 안전 |
+| **토큰 자동 캐싱(50분)** | 매 요청마다 토큰을 발급하지 않음 |
+| **401/403 자동 재시도** | 토큰 만료 시 자동 갱신 후 재발송 |
+| **다건 동시 발송** | 수신자 리스트로 대량 발송 |
+| **예약 발송** | 원하는 시각에 발송 예약 |
+| **SMS 자동 대체 발송** | 알림톡 실패 시 SMS로 자동 전환 |
+| **v1 / v2 API 지원** | 설정 한 줄로 버전 전환 |
+
+---
+
+## 설치
+
+```bash
+pip install sendgo-python
+```
+
+또는 `pyproject.toml`:
+```toml
+[project]
+dependencies = ["sendgo-python>=1.0.0"]
+```
+
+---
+
+## 빠른 시작
+
+### 1단계 — 환경변수 설정
+
+```bash
+# .env
+SENDGO_ACCESS_KEY=your_access_key
+SENDGO_SECRET_KEY=your_secret_key
+SENDGO_KAKAO_SENDER_KEY=your_kakao_key
+SENDGO_SMS_SENDER_KEY=your_sms_key
+SENDGO_API_VERSION=v2
+```
+
+### 2단계 — 클라이언트 초기화
+
+```python
+import os
+from sendgo import Sendgo
+
+client = Sendgo(
+    access_key=os.environ["SENDGO_ACCESS_KEY"],
+    secret_key=os.environ["SENDGO_SECRET_KEY"],
+    kakao_sender_key=os.environ.get("SENDGO_KAKAO_SENDER_KEY"),
+    sms_sender_key=os.environ.get("SENDGO_SMS_SENDER_KEY"),
+    api_version="v2",
+)
+```
+
+### 3단계 — 알림톡 전송
+
+```python
+client.alimtalk.send(
+    template_code="ORDER_CONFIRM_001",
+    contacts=[
+        {
+            "contact": "01012345678",   # 수신자 전화번호 (필수)
+            "name":    "홍길동",         # 수신자 이름 (선택)
+            "var1":    "ORD-20260723-001",  # 템플릿 변수 #{var1}
+            "var2":    "스프링 부트 가이드",  # 템플릿 변수 #{var2}
+            "var3":    "29,000원",           # 템플릿 변수 #{var3}
+        }
+    ],
+)
+```
+
+---
+
+## 상세 사용법
+
+### 카카오 알림톡
+
+```python
+# 다건 발송
+client.alimtalk.send(
+    template_code="ORDER_CONFIRM_001",
+    contacts=[
+        {"contact": "01011111111", "name": "홍길동", "var1": "ORD-001"},
+        {"contact": "01022222222", "name": "김철수", "var1": "ORD-002"},
+        {"contact": "01033333333", "name": "이영희", "var1": "ORD-003"},
+    ],
+)
+
+# 예약 발송
+client.alimtalk.send(
+    template_code="PROMO_SUMMER_2026",
+    schedule_type="SCHEDULED",
+    at="2026-07-28 09:00:00",
+    contacts=[{"contact": "01012345678", "var1": "여름 한정 50% 할인"}],
+)
+
+# 알림톡 실패 시 SMS 자동 대체 발송
+client.alimtalk.send(
+    template_code="DELIVERY_START_001",
+    contacts=[{"contact": "01012345678", "var1": "ORD-001", "var2": "1234567890"}],
+    replace_sms="Y",
+    sms_subject="[배송 시작 안내]",
+    sms_content="주문하신 상품이 출고되었습니다.\n송장번호: #{var2}",
+)
+```
+
+### 카카오 친구톡
+
+```python
+# 텍스트형
+client.friendtalk.send(
+    content="안녕하세요! 7월 한정 특가 이벤트를 확인해보세요.",
+    contacts=[{"contact": "01012345678"}],
+)
+
+# 이미지형
+client.friendtalk.send(
+    message_type="FI",
+    content="이번 주 특가 상품을 확인하세요!",
+    image_url="https://cdn.example.com/banner.jpg",
+    image_link="https://example.com/event",
+    contacts=[{"contact": "01012345678"}],
+)
+```
+
+### SMS / LMS / MMS
+
+```python
+# SMS
+client.sms.send_sms(
+    content="[Sendgo] 인증번호: 123456 (5분 이내 입력)",
+    contacts=[{"contact": "01012345678"}],
+)
+
+# LMS — 장문 (2,000자 이하)
+client.sms.send_lms(
+    subject="[중요] 서비스 점검 안내",
+    content="""안녕하세요. 서비스 점검이 예정되어 있습니다.
+
+■ 점검 일시: 2026-07-25 02:00 ~ 06:00
+■ 영향 범위: 전체 서비스
+
+이용에 불편을 드려 죄송합니다.""",
+    contacts=[{"contact": "01012345678"}],
+)
+
+# MMS — 이미지 포함
+client.sms.send_mms(
+    subject="[이벤트] 7월 특가",
+    content="이번 달 특가 상품을 확인하세요!",
+    contacts=[{"contact": "01012345678"}],
+)
+```
+
+---
+
+## 프레임워크 통합
+
+### Django
+
+```python
+# settings.py
+SENDGO = {
+    "access_key":       env("SENDGO_ACCESS_KEY"),
+    "secret_key":       env("SENDGO_SECRET_KEY"),
+    "kakao_sender_key": env("SENDGO_KAKAO_SENDER_KEY", default=None),
+    "sms_sender_key":   env("SENDGO_SMS_SENDER_KEY",   default=None),
+    "api_version":      env("SENDGO_API_VERSION", default="v2"),
+}
+```
+
+```python
+# apps/notifications/services.py
+from django.conf import settings
+from sendgo import Sendgo
+
+_sendgo: Sendgo | None = None
+
+def get_sendgo() -> Sendgo:
+    global _sendgo
+    if _sendgo is None:
+        _sendgo = Sendgo(**settings.SENDGO)
+    return _sendgo
+
+def send_order_confirm(phone: str, order_number: str) -> None:
+    get_sendgo().alimtalk.send(
+        template_code="ORDER_CONFIRM_001",
+        contacts=[{"contact": phone, "var1": order_number}],
+    )
+```
+
+```python
+# apps/orders/signals.py
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+from .models import Order
+from apps.notifications.services import send_order_confirm
+
+@receiver(post_save, sender=Order)
+def on_order_created(sender, instance, created, **kwargs):
+    if created:
+        send_order_confirm(instance.user.phone, instance.number)
+```
+
+### FastAPI
+
+```python
+# core/sendgo.py
+from functools import lru_cache
+from sendgo import Sendgo
+from .config import settings
+
+@lru_cache
+def get_sendgo() -> Sendgo:
+    return Sendgo(
+        access_key=settings.SENDGO_ACCESS_KEY,
+        secret_key=settings.SENDGO_SECRET_KEY,
+        kakao_sender_key=settings.SENDGO_KAKAO_SENDER_KEY,
+        api_version="v2",
+    )
+```
+
+```python
+# routers/notify.py
+from fastapi import APIRouter, Depends
+from sendgo import Sendgo
+from core.sendgo import get_sendgo
+
+router = APIRouter(prefix="/api")
+
+@router.post("/notify/order")
+async def notify_order(
+    phone: str,
+    order_number: str,
+    sendgo: Sendgo = Depends(get_sendgo),
+):
+    sendgo.alimtalk.send(
+        template_code="ORDER_CONFIRM_001",
+        contacts=[{"contact": phone, "var1": order_number}],
+    )
+    return {"success": True}
+```
+
+### Celery 비동기 발송
+
+```python
+# tasks/notifications.py
+from celery import shared_task
+from sendgo import Sendgo, SendgoError
+import logging
+
+logger = logging.getLogger(__name__)
+
+@shared_task(bind=True, max_retries=3, default_retry_delay=10)
+def send_alimtalk_task(self, template_code: str, contacts: list[dict]) -> None:
+    """카카오 알림톡 비동기 발송 Celery 태스크"""
+    sendgo = Sendgo(
+        access_key=settings.SENDGO_ACCESS_KEY,
+        secret_key=settings.SENDGO_SECRET_KEY,
+        kakao_sender_key=settings.SENDGO_KAKAO_SENDER_KEY,
+    )
+    try:
+        sendgo.alimtalk.send(template_code=template_code, contacts=contacts)
+    except SendgoError as e:
+        logger.error("알림톡 발송 실패: %s [%s]", e, e.error_code)
+        if e.error_code not in ("INVALID_TEMPLATE_CODE", "PAYMENT_REQUIRED"):
+            raise self.retry(exc=e)
+```
+
+```python
+# 사용
+send_alimtalk_task.delay("ORDER_CONFIRM_001", [{"contact": "01012345678", "var1": "ORD-001"}])
+```
+
+---
+
+## 예외 처리
+
+```python
+from sendgo import SendgoError
+
+try:
+    client.alimtalk.send(
+        template_code="ORDER_CONFIRM_001",
+        contacts=[{"contact": "01012345678"}],
+    )
+except SendgoError as e:
+    print(f"발송 실패: HTTP {e.status_code} [{e.error_code}]")
+    print(f"엔드포인트: {e.endpoint}, API 버전: {e.api_version}")
+
+    match e.error_code:
+        case "INVALID_ACCESS_KEY" | "INVALID_SECRET_KEY":
+            alert_ops("Sendgo 인증키를 확인하세요.")
+        case "INVALID_TEMPLATE_CODE":
+            logger.warning("존재하지 않는 템플릿: %s", template_code)
+        case "PAYMENT_REQUIRED":
+            alert_ops("Sendgo 크레딧이 부족합니다.")
+        case "IP_NOT_ALLOWED":
+            alert_ops("허용되지 않은 IP에서 요청이 발생했습니다.")
+```
+
+---
+
+## 설정 옵션
+
+| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
+|---------|------|------|--------|------|
+| `access_key` | `str` | **필수** | — | Sendgo 액세스 키 |
+| `secret_key` | `str` | **필수** | — | Sendgo 시크릿 키 |
+| `kakao_sender_key` | `str \| None` | 선택 | `None` | 카카오 발신프로필 키 |
+| `sms_sender_key` | `str \| None` | 선택 | `None` | SMS 발신자 키 |
+| `api_version` | `str` | 선택 | `'v1'` | API 버전 (`v1` \| `v2`) |
+| `base_url` | `str` | 선택 | `'https://sendgo.io'` | API 기본 URL |
+
+---
+
+## 자주 묻는 질문 (FAQ)
+
+**Q. 비동기(async/await)를 지원하나요?**
+A. 현재 버전은 동기(`requests` 기반)만 지원합니다. FastAPI 등 비동기 환경에서는 `asyncio.get_event_loop().run_in_executor()`로 스레드풀에서 실행하거나, Celery 태스크로 위임하는 방법을 권장합니다. 비동기 버전(`httpx` 기반)은 향후 추가될 예정입니다.
+
+**Q. 멀티스레드 환경에서 안전한가요?**
+A. 토큰 관리에 `threading.Lock`을 사용하여 멀티스레드 환경에서도 안전합니다.
+
+**Q. 알림톡 템플릿은 어디서 등록하나요?**
+A. [Sendgo 콘솔](https://sendgo.io) → 알림톡 템플릿 → 템플릿 작성 → 카카오 심사 신청 (보통 1~3일 소요)
+
+**Q. 대량 발송 시 rate limit이 있나요?**
+A. Sendgo 플랜별로 TPS 제한이 있습니다. [요금 정책](https://sendgo.io/pricing) 참조.
+
+---
+
+## 관련 패키지
+
+| 언어/프레임워크 | 패키지 | GitHub |
+|----------------|--------|--------|
+| Spring Boot | `io.sendgo:sendgo-spring` | [sendgo-spring-boot-starter](https://github.com/send-go/spring) |
+| Node.js | `@sendgo/node` | [sendgo-node](https://github.com/send-go/node) |
+| Go | `github.com/send-go/go` | [sendgo-go](https://github.com/send-go/go) |
+| 전체 목록 | — | [send-go GitHub 조직](https://github.com/send-go) |
+
+---
+
+## 라이선스
+
+MIT License © 2026 [Sendgo](https://sendgo.io)
+
+---
+
+*키워드: 카카오 알림톡 Python, 카카오 친구톡 Django, SMS 발송 FastAPI, 알림톡 SDK pip, Python 카카오 API 연동, Django 문자 발송, FastAPI 알림톡, Celery 알림톡 비동기, Sendgo Python SDK*

sendgo_python-1.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+sendgo/__init__.py,sha256=1dUImXkaop7KOI-u8IkpoY3AtCUYs-OBrEnq1YujQDc,592
+sendgo/alimtalk.py,sha256=2dKctTPqn18Ev14PGoiSYtdHvoMvkwDWL0AulgIG3sU,1959
+sendgo/client.py,sha256=t0rpnY7qfLv0luP1ywhtvKRLP8eeauTTYMu-Mfph4Hc,1538
+sendgo/exceptions.py,sha256=EiBZJPp72pwwMA3lR6cSatvaxa4ooBTvf8bk9XL8g50,1423
+sendgo/friendtalk.py,sha256=XyWxaJD92TbXXdcrKwhruU7WtiUeFORmBhv8RrXwCdw,2192
+sendgo/http_client.py,sha256=KBwQMig59521ikQFR-ZEdO23Gr1xkPM4Dg_aU7CxNJE,1685
+sendgo/sms.py,sha256=546qRFafKLd5W4WAO1K4xRJj7PYtYfevPdN7qWWiZlc,2073
+sendgo/token_manager.py,sha256=xhiKimI_30nkSrdPfkQwT9ksu6jbZtjzmtaOjUX2hkc,2244
+sendgo_python-1.0.1.dist-info/METADATA,sha256=dP8EBrPqSDdnpgBDd7hHU6ccc6ZmM8mLxO3PeM5jGjE,13256
+sendgo_python-1.0.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sendgo_python-1.0.1.dist-info/top_level.txt,sha256=1_OCirphGoTnHC9W3nkzSzNMPLypnQOG9YQYqUZ4E2g,7
+sendgo_python-1.0.1.dist-info/RECORD,,

sendgo_python-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sendgo_python-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+sendgo