# 开发文档

在 Raise 上开发业务系统：用 [Go 或 TypeScript SDK](/developers/sdk/) 写应用，按 k3 协议声明对象、操作和权限点，平台负责身份、权限、审计、助手和多端；也可以让自己的后台系统通过开放接口读写一个组织的数据。这里是开发指南、接口参考、SDK 和变更日志。

## 你可以做什么

| 你要做的 | 用哪个接口 | 说明 |
|---|---|---|
| 让自己的后台读写一个组织的数据 | 开放接口 `/open/v1` | 组织授权的集成，或代表组织的应用调用。可以读多维表和组织通讯录，读写客户档案，也可以代表一位终端客户（小程序用户）调用 |
| 做一个装进工作台的应用 | 应用接口 `/app/v1` | 已安装的应用调用平台能力：客户中心、站点访客、经营记账、审计链、成员、事件、记录链接 |
| 在事情发生时收到通知 | 事件（Webhooks） | 平台把事件推到你的 https 地址，同一个信封、同一种签名 |

两个接口的约定完全一致：错误信封、`Idempotency-Key`、限流响应头、`Raise-Environment`。

应用有两种分发方式，由你的开发者组织决定：

- **商店应用**：独立的开发者组织建的应用，发布到应用市场，供多个企业安装。版本要经平台审核。
- **自建应用**：属于某个企业的开发者组织建的，只在这个企业里用。版本提交后自动通过，不审核。

## 从这里开始

1. 在开发者门户[注册开发者账号](https://dev.kwork.cloud/signup)，或请平台运营为你开通。
2. [建一个应用](https://dev.kwork.cloud/apps/)，再建一个测试企业。测试企业的数据独立、不计费，可以带示例客户、多维表和测试员工。
3. 拿一把测试密钥，换访问令牌，调用第一个接口。

每一步怎么做，见 [5 分钟第一次调用](/developers/guide/quickstart)。

## 开发指南

- [5 分钟第一次调用](/developers/guide/quickstart)：注册、建应用、拿测试密钥、换令牌、调用 whoami，用 Go 或 TypeScript SDK 调用。
- [本地开发与测试企业](/developers/guide/local-dev)：安装命令行 `k3`，建测试企业，让本机的进程接到测试企业，收发事件，查日志。
- [认证与令牌](/developers/guide/auth)：三种凭证、测试与正式环境、客户令牌，密钥的轮换与吊销。
- [错误、分页与幂等](/developers/guide/conventions)：错误信封、游标分页、幂等键、限流和数据格式。
- [错误码与请求 ID](/developers/guide/errors)：每个错误码的含义与处理方式，用请求 ID 查一次调用。
- [事件与验签](/developers/guide/webhooks)：事件信封、签名校验、重试，以及应用生命周期事件。
- [应用接口（/app/v1）](/developers/guide/app-api)：已安装的应用怎样调用平台能力，要在清单里声明哪些范围。

## 接口参考

- [开放接口（/open/v1）](/developers/api/open-v1)：每个操作的参数、正文、响应和错误。
- [应用接口（/app/v1）](/developers/api/app-v1)：每个操作需要的范围、参数、正文和响应。

两份参考都由接口描述文件生成。你可以下载原始文件，导入自己的工具：

- [open-v1.openapi.yaml](/openapi/open-v1.yaml)
- [app-v1.openapi.yaml](/openapi/app-v1.yaml)

## SDK

服务端用 Go 模块 `github.com/21stware/raise-go` 或 npm 包 `@21stware/raise-sdk`。SDK 自动换令牌、在到期前 60 秒刷新，处理重试和分页，不要自己拼签名和重试。应用的页面用应用 SDK `@21stware/raise-app-sdk` 与套件包 `@21stware/raise-app-kit`。

安装和用法见 [SDK](/developers/sdk/)。

## 变更日志

接口、事件、SDK、命令行和清单的每一次变化，见 [变更日志](/developers/changelog)。