# Sendgo SDK 与开发者指南

提供适用于 PHP、Node.js、Python、Go、Java、Ruby、.NET、Flutter 等语言与框架的 19 个官方 SDK 软件包，并单独提供 OpenAPI 规范。接入 Kakao 通知消息、品牌消息与 SMS/LMS/MMS。

Sendgo 为 Kakao 通知消息（알림톡）、品牌消息（브랜드메시지）以及 SMS/LMS/MMS 提供 **19 个官方语言与框架 SDK 软件包**。**OpenAPI 规范单独提供**，不计入 SDK 数量。
无论使用哪种语言，对接流程都相同：签发密钥 → 登记发送者 → 发送。

## 三分钟上手

1. **签发密钥** — 登录后打开 **API/SDK → API 对接**，创建访问密钥（access key）与私密密钥（secret key）。
2. **登记发送者** — 通知消息／品牌消息需在 **Kakao 渠道** 登记发送者资料；短信需在 **发送号码** 登记主叫号码。
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` |

核心是不依赖任何框架的纯客户端；扩展包在其之上适配各框架的配置、依赖注入与日志约定。
安装扩展包时会自动带入核心，因此无需分别安装。

## 各 SDK 通用的概念

- **认证** — 使用访问密钥与私密密钥换取令牌，随后以 Bearer 令牌调用。令牌的签发与续期由各 SDK 自动处理。
- **API 版本** — 建议使用 `v2`。v2 采用签名式令牌（`sgv2.{payload}.{signature}`），有效期 24 小时。
- **发送渠道** — 通知消息（`alimtalk`）、品牌消息（`brandMessage`）、短信（`sms`）、好友消息（`friendtalk`，**已于 2025-12-31 停止服务** —— 请求会自动以品牌消息（自由形式）发出）。
- **品牌消息** — 好友消息的后继渠道，可触达**非频道好友**的接收者，也可向已同意接收的全部频道好友群发。
- **短链接** — 缩短消息中的链接并统计点击反应（按日趋势、设备、来源、国家）。仅 v2 支持。
- **短信回退** — 使用 `replaceSms`，Kakao 消息发送失败时自动回退为短信。
- **预约发送** — 通过 `scheduleType: SCHEDULED` 与 `at` 指定时间。
- **错误处理** — 所有 SDK 都会抛出携带 HTTP 状态码与 Sendgo 错误代码的异常。完整代码列表见 REST API 文档。

## 仅限服务端使用的 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` — 各指南的 Markdown 原文
- `/openapi.yaml` — REST API 的 OpenAPI 3.0.3 规范

## 服务端核心 SDK

- [PHP (`sendgo/php`)](https://sendgo.io/zh/sdk/php.md) — `composer require sendgo/php`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 PHP SDK —— 不依赖任何框架的纯 PHP 核心包。
- [Node.js (`@sendgo/node`)](https://sendgo.io/zh/sdk/node.md) — `npm install @sendgo/node`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Node.js SDK —— 完整 TypeScript 类型，零运行时依赖。
- [Python (`sendgo-python`)](https://sendgo.io/zh/sdk/python.md) — `pip install sendgo-python`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Python SDK —— 不依赖任何框架的纯 Python 核心包。
- [Go (`github.com/send-go/go`)](https://sendgo.io/zh/sdk/go.md) — `go get github.com/send-go/go`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Go SDK —— 仅依赖标准库，零第三方依赖。
- [Java (`io.sendgo:sendgo-java`)](https://sendgo.io/zh/sdk/java.md) — `implementation "io.sendgo:sendgo-java:1.1.0"`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Java SDK —— 不依赖任何框架，构建器风格 API。
- [Ruby (`sendgo`)](https://sendgo.io/zh/sdk/ruby.md) — `gem install sendgo`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Ruby SDK —— 仅依赖标准库，关键字参数风格。
- [.NET (`Sendgo.SDK`)](https://sendgo.io/zh/sdk/dotnet.md) — `dotnet add package Sendgo.SDK`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 .NET SDK —— record 类型请求，全异步 API。

## 框架扩展

- [Laravel (`sendgo/laravel`)](https://sendgo.io/zh/sdk/laravel.md) — `composer require sendgo/laravel`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Laravel 扩展包 —— 门面、配置发布、队列友好。
- [Symfony (`sendgo/symfony`)](https://sendgo.io/zh/sdk/symfony.md) — `composer require sendgo/symfony`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Symfony 扩展包 —— 自动装配服务、配置校验、Messenger 友好。
- [WordPress (`sendgo/wordpress`)](https://sendgo.io/zh/sdk/wordpress.md) — `composer require sendgo/wordpress`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 WordPress 插件 —— 支持 WooCommerce 订单自动通知。
- [NestJS (`@sendgo/nestjs`)](https://sendgo.io/zh/sdk/nestjs.md) — `npm install @sendgo/nestjs`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 NestJS 扩展包 —— 可注入的模块与服务。
- [Django (`sendgo-django`)](https://sendgo.io/zh/sdk/django.md) — `pip install sendgo-django`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Django 扩展包 —— 从 settings 配置，延迟构建客户端。
- [FastAPI (`sendgo-fastapi`)](https://sendgo.io/zh/sdk/fastapi.md) — `pip install sendgo-fastapi`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 FastAPI 扩展包 —— 以依赖注入方式提供，从环境变量配置。
- [Spring Boot (`io.sendgo:sendgo-spring`)](https://sendgo.io/zh/sdk/spring.md) — `implementation "io.sendgo:sendgo-spring:1.0.1"`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Spring Boot Starter —— 由配置属性自动装配客户端 Bean。
- [Ruby on Rails (`sendgo-rails`)](https://sendgo.io/zh/sdk/rails.md) — `bundle add sendgo-rails`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Rails 集成包 —— 由 Railtie 配置，支持环境变量回退。
- [ASP.NET Core (`Sendgo.AspNetCore`)](https://sendgo.io/zh/sdk/aspnetcore.md) — `dotnet add package Sendgo.AspNetCore`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 ASP.NET Core 扩展包 —— 将客户端注册到依赖注入容器。

## 前端与移动端

- [React / Next.js (`@sendgo/react`)](https://sendgo.io/zh/sdk/react.md) — `npm install @sendgo/react`: 用于从 Next.js Server Action 与 Route Handler 发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 React SDK —— 仅限服务端。
- [Vue / Nuxt (`@sendgo/vue`)](https://sendgo.io/zh/sdk/vue.md) — `npm install @sendgo/vue`: 用于从 Nuxt server route 发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Vue SDK —— 仅限服务端。
- [Flutter / Dart (`sendgo_flutter`)](https://sendgo.io/zh/sdk/flutter.md) — `dart pub add sendgo_flutter`: 用于发送 Kakao 通知消息、好友消息、品牌消息与 SMS 的官方 Dart SDK —— 仅限服务端使用。

## 参考资料

- [OpenAPI (`send-go/openapi`)](https://sendgo.io/zh/sdk/openapi.md) — `curl -O https://sendgo.io/openapi.yaml`: Sendgo API 的机器可读 OpenAPI 3.0.3 契约 —— Kakao 通知消息、品牌消息与 SMS。可直接喂给代码生成器或 AI 编码工具。