# 샌드고 SDK 및 개발자 가이드

PHP, Node.js, Python, Go, Java, Ruby, .NET, Flutter 등 언어·프레임워크를 위한 19종 공식 SDK와 별도 OpenAPI 명세를 제공합니다. 카카오 알림톡·브랜드메시지와 SMS/LMS/MMS를 연동하세요.

샌드고는 카카오 알림톡·브랜드메시지와 SMS/LMS/MMS 발송을 위한 **언어·프레임워크용 공식 SDK 19종**을 제공합니다. **OpenAPI 명세는 별도**로 제공하며 SDK 개수에 포함하지 않습니다.
어떤 언어를 쓰더라도 동일한 개념(액세스 키 발급 → 발신프로필 등록 → 발송)으로 연동할 수 있습니다.

## 3분 만에 시작하기

1. **키 발급** — 샌드고에 로그인해 **API/SDK → API 연동** 메뉴에서 액세스 키와 시크릿 키를 발급합니다.
2. **발신 정보 등록** — 알림톡·브랜드메시지는 **카카오 채널** 메뉴에서 발신프로필을, 문자는 **발신번호** 메뉴에서 발신번호를 등록합니다.
3. **SDK 설치** — 사용하는 언어의 가이드를 열어 설치 명령 한 줄을 실행합니다.
4. **발송** — 템플릿 코드와 수신자 목록을 넘기면 끝입니다.

## SDK 설계 방식

모든 SDK는 **코어 + 프레임워크 확장** 구조를 따릅니다.

| 코어 | 프레임워크 확장 |
|------|----------------|
| `sendgo/php` | `sendgo/laravel`, `sendgo/symfony`, `sendgo/wordpress` |
| `@sendgo/node` | `@sendgo/react`, `@sendgo/vue`, `@sendgo/nestjs` |
| `sendgo-python` | `sendgo-django`, `sendgo-fastapi` |
| `io.sendgo:sendgo-java` | `io.sendgo:sendgo-spring` |
| `sendgo` (Ruby) | `sendgo-rails` |
| `Sendgo.SDK` | `Sendgo.AspNetCore` |

코어는 프레임워크에 의존하지 않는 순수 클라이언트이고, 확장 패키지는 해당 프레임워크의 설정·의존성 주입·로깅 규칙에 맞춰 코어를 감쌉니다.
프레임워크 확장을 설치하면 코어는 의존성으로 함께 설치되므로 따로 설치할 필요가 없습니다.

## 공통 개념

- **인증** — 액세스 키와 시크릿 키로 토큰을 발급받고, 이후 요청은 Bearer 토큰으로 인증합니다. 모든 SDK가 토큰 발급·갱신을 자동으로 처리합니다.
- **API 버전** — `v2`를 권장합니다. v2는 서명 기반 토큰(`sgv2.{payload}.{signature}`)을 사용하며 유효기간은 24시간입니다.
- **발송 채널** — 알림톡(`alimtalk`), 브랜드메시지(`brandMessage`), 문자(`sms` / `lms` / `mms`), 친구톡(`friendtalk`, **2025-12-31 종료** — 요청은 브랜드메시지(자유형)로 자동 대체 발송됩니다).
- **브랜드메시지** — 친구톡의 후속 채널로, 채널 친구가 아닌 수신자에게도 보낼 수 있고 수신 동의한 전체 채널 친구에게 동보 발송할 수 있습니다. v2 전용.
- **짧은 URL** — 메시지의 링크를 줄이고 클릭 반응(일별 추이·디바이스·유입경로·국가)을 집계합니다. v2 전용.
- **알림톡 실패 시 문자 대체** — `replaceSms` 옵션으로 알림톡 실패 시 문자로 자동 대체 발송할 수 있습니다.
- **예약 발송** — `scheduleType: SCHEDULED` 와 `at` 값으로 예약할 수 있습니다.
- **오류 처리** — 모든 SDK가 HTTP 상태 코드와 샌드고 오류 코드를 담은 예외를 던집니다.

## 서버 전용 SDK 주의사항

`@sendgo/react`, `@sendgo/vue`, `sendgo_flutter`는 **서버사이드 전용**입니다.
액세스 키와 시크릿 키는 브라우저나 모바일 앱 번들에 포함되면 안 되므로, 반드시 Next.js Server Action / Route Handler, Nuxt Server Route, Dart 백엔드 등 서버 환경에서만 사용하세요.

## AI 코딩 에이전트용 리소스

바이브 코딩이나 AI 에이전트로 연동할 때 아래 리소스를 사용하면 정확한 코드를 얻을 수 있습니다.

- `/llms.txt` — 전체 문서 지도 (llmstxt.org 규격)
- `/llms-full.txt` — 모든 SDK 가이드 전문을 하나로 합친 파일
- `/{언어}/sdk/{패키지}.md` — 각 가이드의 마크다운 원문
- `/openapi.yaml` — OpenAPI 3.0.3 스펙

## 서버 코어 SDK

- [PHP (`sendgo/php`)](https://sendgo.io/ko/sdk/php.md) — `composer require sendgo/php`: PHP에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 순수 PHP SDK
- [Node.js (`@sendgo/node`)](https://sendgo.io/ko/sdk/node.md) — `npm install @sendgo/node`: Node.js / TypeScript에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK
- [Python (`sendgo-python`)](https://sendgo.io/ko/sdk/python.md) — `pip install sendgo-python`: Python / Django / FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK
- [Go (`github.com/send-go/go`)](https://sendgo.io/ko/sdk/go.md) — `go get github.com/send-go/go`: Go에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Go SDK
- [Java (`io.sendgo:sendgo-java`)](https://sendgo.io/ko/sdk/java.md) — `implementation "io.sendgo:sendgo-java:1.1.0"`: Java에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 순수 Java SDK
- [Ruby (`sendgo`)](https://sendgo.io/ko/sdk/ruby.md) — `gem install sendgo`: Ruby에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Ruby SDK
- [.NET (`Sendgo.SDK`)](https://sendgo.io/ko/sdk/dotnet.md) — `dotnet add package Sendgo.SDK`: .NET / ASP.NET Core에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 .NET SDK

## 프레임워크 확장

- [Laravel (`sendgo/laravel`)](https://sendgo.io/ko/sdk/laravel.md) — `composer require sendgo/laravel`: Laravel에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Laravel 패키지
- [Symfony (`sendgo/symfony`)](https://sendgo.io/ko/sdk/symfony.md) — `composer require sendgo/symfony`: Symfony에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Symfony 번들
- [WordPress (`sendgo/wordpress`)](https://sendgo.io/ko/sdk/wordpress.md) — `composer require sendgo/wordpress`: 카카오 알림톡·브랜드메시지와 SMS/LMS/MMS 를 발송하고, WooCommerce 주문 상태에 따라 구매자에게 자동으로 알리는 공식 WordPress 플러그인
- [NestJS (`@sendgo/nestjs`)](https://sendgo.io/ko/sdk/nestjs.md) — `npm install @sendgo/nestjs`: NestJS에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 NestJS 모듈
- [Django (`sendgo-django`)](https://sendgo.io/ko/sdk/django.md) — `pip install sendgo-django`: Django에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Django 확장 패키지
- [FastAPI (`sendgo-fastapi`)](https://sendgo.io/ko/sdk/fastapi.md) — `pip install sendgo-fastapi`: FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 FastAPI 확장 패키지
- [Spring Boot (`io.sendgo:sendgo-spring`)](https://sendgo.io/ko/sdk/spring.md) — `implementation "io.sendgo:sendgo-spring:1.0.1"`: Spring Boot에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Spring Boot Starter
- [Ruby on Rails (`sendgo-rails`)](https://sendgo.io/ko/sdk/rails.md) — `bundle add sendgo-rails`: Rails에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Rails 확장 젬
- [ASP.NET Core (`Sendgo.AspNetCore`)](https://sendgo.io/ko/sdk/aspnetcore.md) — `dotnet add package Sendgo.AspNetCore`: ASP.NET Core에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 DI 확장 패키지

## 프론트엔드 · 모바일

- [React / Next.js (`@sendgo/react`)](https://sendgo.io/ko/sdk/react.md) — `npm install @sendgo/react`: React / Next.js에서 카카오 알림톡, 브랜드메시지, SMS를 발송하는 공식 React SDK
- [Vue / Nuxt (`@sendgo/vue`)](https://sendgo.io/ko/sdk/vue.md) — `npm install @sendgo/vue`: Vue.js / Nuxt 3에서 카카오 알림톡, 브랜드메시지, SMS를 발송하는 공식 Vue SDK
- [Flutter / Dart (`sendgo_flutter`)](https://sendgo.io/ko/sdk/flutter.md) — `dart pub add sendgo_flutter`: Flutter / Dart 서버에서 카카오 알림톡, 브랜드메시지, SMS를 발송하는 공식 Dart SDK

## 레퍼런스

- [OpenAPI (`send-go/openapi`)](https://sendgo.io/ko/sdk/openapi.md) — `curl -O https://sendgo.io/openapi.yaml`: Sendgo API의 OpenAPI 3.0.3 스펙입니다. 코드 생성기, API 클라이언트, AI 코딩 도구에