开发者快速入门

VISH有一个开放的HTTP API：应用程序本身使用它，您的脚本，机器人和网站也可以使用它。 时间表、小组、教师和教室都是在没有任何钥匙的情况下阅读的；你需要一把钥匙来代表你自己行事，“入境及过境VISH”是在征得他人同意的情况下阅读他人的数据。

这一页是开始的地方。 其余的页面在“开发人员”部分整理API的各个部分。 2026年10月23日与摊位d1及生产确认。

摊位地址

• d1 -testbed：新功能出现在这里早些时候，数据可能会发生变化。 从他开始。
• 生产 是学生使用的东西。 新的东西每两周在这里发布一次。
• 没有地址的地址www (https://vish-app.ru）以301重定向响应。 指定完整地址，否则某些库将在过渡期间丢失它们的标头。
• 所有方法的机器描述是/documentation/json在同一立场（OpenAPI3）。

在本节的所有示例中，地址都取自环境变量VISH_API（默认情况下为d1），并且密钥取自VISH_API_KEY. 不要在代码中输入密钥。

第一个请求

你不需要钥匙：研究所和团体的名单对所有人开放。

// List institutes and the first groups; no key needed.
const API = process.env.VISH_API ?? 'https://d1.vish-app.ru/api/v1'

const get = async (path) => {
	const response = await fetch(`${API}${path}`, { headers: { Accept: 'application/json' } })
	if (!response.ok) throw new Error(`${path}: HTTP ${response.status}`)
	return response.json()
}

const institutes = await get('/institutes')
if (!Array.isArray(institutes.list) || institutes.list.length === 0) throw new Error('no institutes')

const groups = await get('/groups?perPage=3')
if (groups.list.length === 0 || typeof groups.meta?.total !== 'number') throw new Error('unexpected /groups')

console.log(`${institutes.list.length} institutes, ${groups.meta.total} groups`)
for (const group of groups.list) console.log(group.name, '—', group.institute?.code)

就在这里试试:

答案是如何安排的？

• 一切都是UTF-8中的JSON。 日期是协调世界时的ISO8601(2026-10-19T13:45:00.000Z).
• 名单如下{ "list": [...], "meta": { "total", "page", "perPage", "pages" } }. 页面设置为page（带1）和perPage（默认情况下，20，不超过200）。 名单有all=1 -所有在一个页面上，但不超过2000个条目。
• 正在翻译的名称带有object { "ru": "…", "en": "…", "zh": "…" }. 总是有俄语，可能没有翻译。
• 新的领域出现在没有警告的答案—不要落在不熟悉的领域。

访问密钥

您不需要密钥来读取公共数据。 当脚本代表您行事时，您需要它：它上传您的角色有权访问的报告，或为类编写注释。 如何获得密钥写在API和访问密钥页;如何使用它以及它与OAuth的不同之处在于身份验证：API和OAuth密钥页。

错误格式

任何API错误都是同一个对象。:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Нужно войти: передайте заголовок Authorization с Bearer-токеном или заголовок X-Api-Key.",
    "requestId": "e47fc5d6-a210-49f2-b480-1384633d1d9f"
  }
}

• code 是机器代码，并依靠它。 它不会根据语言而改变。
• message -从标题的语言的人的解释Accept-Language (ru, en或zh;默认为俄语）。 文本可能会改变-不要拆卸它。
• requestId 是请求号;相同的数字出现在头中X-Request-Id. 当你写这个问题的时候给它命名。
• details -发生验证错误(VALIDATION_ERROR): details.issues -字段列表以及它们有什么问题。

最常见的代码:

有关403的更多信息，请参阅访问权限(RBAC)页。 OAuth协议地址（/oauth/token, /oauth/userinfo，和其他人）遵守OAuth:{ "error": "invalid_grant", "error_description": "…" }标准。

要查看整个错误，请请求没有需要登录的密钥的方法。:

// /auth/me needs a credential: without one the answer shows the error format.
const API = process.env.VISH_API ?? 'https://d1.vish-app.ru/api/v1'

const response = await fetch(`${API}/auth/me`, { headers: { 'Accept-Language': 'en' } })
const body = await response.json()

if (response.status !== 401 || body.error?.code !== 'AUTH_REQUIRED' || !body.error.requestId) {
	throw new Error(`unexpected answer: ${response.status} ${JSON.stringify(body)}`)
}
console.log(body.error.code, '-', body.error.message)
console.log('requestId:', body.error.requestId)

限制请求的频率

• 总限额为 每分钟300个请求 每个登录的人，或者在没有登录的情况下，到一个IP地址。
• 每把钥匙都有 自身的极限，默认情况下每分钟3000个请求。 虚拟密钥不会增加限制：此类请求被认为是在地址上。
• 重型方法有自己的限制，并且更严格：日历提要-每分钟60，期间摘要（工作量，报告）和令牌的OAuth代码交换-每分钟30，PDF-每分钟10。
• 超过是回应 429 与error.code RATE_LIMITED;消息说要重复多少秒。 对于生产，响应带有标题RateLimit-Limit, RateLimit-Remaining和RateLimit-Reset，并且可以提前放慢速度（2026年10月23日d1上没有）。

API版本

所有地址以/api/v1. 在v1内部，API仅在保持兼容性的情况下更改：方法，参数和响应字段被添加。 如果有些东西需要不兼容地改变，它将是一个新的地址的新版本，我们将在API更改页。

下一步是什么

• 身份验证：API和OAuth密钥
• 透过VISH对于开发人员
• 访问权限(RBAC)
• 附表空气污染指数和参考空气污染指数
• Notes API和通知及日历
• 集成安全, API更改, 开发人员问题

验证:2026-10,PWA aa337c45,平台bff65fce._