> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 值班日历订阅

> 生成一个 iCalendar 订阅地址，把一个排班或自己在各排班里的班次加到日历应用里。

订阅地址给日历应用（Google 日历、Outlook、Apple 日历等）读取，内容是 RFC 5545 的 iCalendar，包含过去 30 天到未来 90 天的班次，替班和换班都算在内。订阅分两种：一个排班的全部班次，或订阅人自己在各个排班里的班次。

| 方法与路径 | 作用 | 权限 |
| - | - | - |
| `GET /api/v1/schedules/calendar-feeds` | 当前用户的订阅。 | `schedules.read` |
| `POST /api/v1/schedules/calendar-feeds` | 生成订阅地址；同一排班（或个人订阅）已有订阅时重置它，旧地址马上失效。 | `schedules.calendar_feeds.manage`，订阅排班时还要对这个排班的 `schedules.calendar_feeds.manage` |
| `DELETE /api/v1/schedules/calendar-feeds/{id}` | 停止自己的一份订阅，地址马上失效。 | `schedules.calendar_feeds.manage` |
| `GET /api/v1/public/calendar/{token}.ics` | 日历应用读取的地址，不用登录。 | 地址里的 Token |

## 生成订阅地址

**请求体**

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `schedule_id` | string | 否 | 订阅这个排班；不填是个人订阅。 |

```bash cURL theme={null}
curl -X POST http://localhost:5080/api/v1/schedules/calendar-feeds \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"schedule_id": "<schedule-id>"}'
```

```json 200 theme={null}
{
  "feed": {
    "id": "3KHtq0dYc1fUe8WnP2xLbR7aZsM",
    "schedule_id": "<schedule-id>",
    "schedule_name": "Payments primary",
    "created_at": 1790000000000000,
    "last_used_at": null
  },
  "path": "/api/v1/public/calendar/<token>.ics",
  "url": "https://molesignal.example.com/api/v1/public/calendar/<token>.ics"
}
```

地址只在这时给出一次，库里只存 Token 的 SHA-256。`url` 用实例的外部地址拼成，没有设外部地址时为 `null`，用访问 MoleSignal 的地址拼上 `path`。列表里每份订阅有 `id`、`schedule_id`、`schedule_name`、`created_at` 和日历上次读取的时间 `last_used_at`，不含地址。

## 日历应用读取

```http theme={null}
GET /api/v1/public/calendar/{token}.ics
```

每次读取都按订阅人重新核对：账号仍然有效、仍在这个组织、仍有 `schedules.read`，排班订阅还要仍能看到这个排班。核对不过、Token 不对或订阅已停止时一律返回 `404`。班次的标题和说明用订阅人的界面语言。

拿到地址的人都能看到这些班次，地址泄露时重置或停止订阅。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.