书摘等软件按来源和外部编号把笔记导入 Dinox，重复提交时更新同一篇笔记。

导入 API

这个接口按来源和外部编号找到原来的笔记再写入。书摘软件、剪藏工具和其他需要反复同步的应用都使用它。

普通的新建笔记请看开放接口。

书摘软件怎么对接

下面用一个书摘软件举例。软件里每本书、每条划线都有自己的编号。Dinox 用这个编号认出同一条内容。书名和简介写在笔记上，作者、章节和所属书籍使用微信读书同一套属性。

对接按这个顺序做。

1. 固定一个来源名

选一个短名字，之后一直用它，例如 reeden。只使用小写字母、数字、_、-，最长 32。这个名字要由 Dinox 开通。未开通时返回 source is not supported，笔记不会写入。

2. 让用户填入 API Token

用户在 Dinox App 打开 设置 → 同步设置 → API Token，复制后填到书摘软件里。之后每次请求都放在请求头：

Authorization: <用户的 Token>

3. 使用微信读书同一套属性

书摘请使用微信读书导入已经在用的属性，不要另起 书籍、章节 这类名字。用户在 App 里同步过微信读书后，账号里就有这些属性。导入前调用列出已有属性，确认下面的 key 都在。缺少时不要换名字，请让用户先在 App 里同步一次微信读书。

curl https://aisdk.chatgo.pro/api/openapi/knowledge/properties \
  -H "Authorization: <用户的 Token>"

key	名称	类型	写在哪里	怎么填
reading_kind	阅读类型	单选	书和划线都写	书传 `book` 或 `书`。划线传 `excerpt` 或 `书摘`
book	所属书籍	关联	只写在划线上	书的 `noteId` 数组，例如 `["0195b9ae-..."]`
author	作者	文本	只写在书上	作者名
publication_date	出版日期	日期	只写在书上	`2018-09-01`
isbn	ISBN	文本	只写在书上	13 位数字，不带横线
chapter	章节	文本	只写在划线上	章节名
page	页码	文本	只写在划线上	页码

划线上不要写 author。作者以书那一篇为准。没有的值就不要传这个 key，例如没有 ISBN 时不要传空字符串。

4. 先导入书

一本书对应一篇笔记。id 用这本书在书摘软件里的编号，以后不要换。title 放书名，content 放 Markdown 简介。一次最多 50 条。

curl -X POST https://aisdk.chatgo.pro/api/openapi/notes/import \
  -H "Authorization: <用户的 Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "reeden",
    "items": [
      {
        "id": "book-1",
        "title": "原则",
        "content": "这本书讲决策原则。",
        "properties": {
          "reading_kind": "book",
          "author": "瑞·达利欧",
          "publication_date": "2018-09-01",
          "isbn": "9787508684031"
        }
      }
    ]
  }'

{
  "code": "000000",
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "book-1",
        "noteId": "0195b9ae-6bf1-7c34-9b95-0c45d26c9a31",
        "status": "created"
      }
    ]
  }
}

记下这次返回的 noteId。它是这本书在 Dinox 里的笔记编号，下一步用来把划线挂到这本书上。

书和划线要分两次提交

同一次请求里还拿不到新笔记的 noteId。先提交书，等返回后，再提交划线。

5. 再导入划线

一条划线对应一篇笔记。id 用这条划线在书摘软件里的编号。content 放摘录正文。book 的值是上一步返回的 noteId，并且必须是数组。只有摘录、没有想法时，type 用 crawl。摘录后面还写了想法时，type 用 note，想法接在正文后面。

curl -X POST https://aisdk.chatgo.pro/api/openapi/notes/import \
  -H "Authorization: <用户的 Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "reeden",
    "items": [
      {
        "id": "hl-9",
        "title": "划线",
        "type": "crawl",
        "content": "痛苦加反思等于进步。",
        "properties": {
          "book": ["0195b9ae-6bf1-7c34-9b95-0c45d26c9a31"],
          "reading_kind": "excerpt",
          "chapter": "第一章",
          "page": "12"
        }
      }
    ]
  }'

返回里的 status 为 created 时，这条划线已经写入，并关联到《原则》。

同一批里只要有一条属性不合法，这一批都不会写入。提交前先确认 key 和值。

6. 以后只提交有变化的内容

书摘软件自己记住上次同步的时间，下次只提交这之后新增或改过的书和划线。时间只用来少传数据。认出同一篇笔记靠的是原来的 source 和 id。

下次同步仍然先传书，再用返回的 noteId 传划线。status 为 unchanged 或 protected 时也会带回原来的 noteId，可以继续挂新划线。

{
  "code": "000000",
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "book-1",
        "noteId": "0195b9ae-6bf1-7c34-9b95-0c45d26c9a31",
        "status": "unchanged"
      },
      {
        "id": "hl-9",
        "noteId": "0195c1d2-2a10-7b11-8c20-6e5f0a1b2c3d",
        "status": "protected"
      }
    ]
  }
}

status	软件应该怎么做
created	新笔记已写入。本次用返回的 `noteId` 去关联其他笔记
updated	用户没有改过这篇笔记，内容已按本次提交更新
unchanged	和上次导入相同，不用再处理
protected	用户在 Dinox 里改过或删除过。保留用户的版本，不要换一个新 `id` 再传

用户改过的笔记会保留

同一篇笔记只要在 Dinox 里被修改或删除，之后的导入不会覆盖它，也不会把它重新建出来。

更新时如果不传 title、type、properties，原来的值会保留。划线只改了正文时，可以不传 properties，所属书籍还在。要改关联或章节时，传入完整的 properties，因为传入后会替换整组属性。

基础信息

基础域名：https://aisdk.chatgo.pro
接口地址：POST /api/openapi/notes/import
认证方式与开放接口相同
使用 OAuth 时需要 dinox.notes.write 权限
限流：每个 Token 每小时 200 次。一次请求可以提交最多 50 条笔记

请求参数

Content-Type: application/json

参数名	类型	必填	说明
source	string	是	来源名。服务端会转成小写。不能使用 `api`
items	array	是	要导入的笔记，1 到 50 条
items[].id	string	是	这条内容在对方软件里的编号，最长 512。同一次请求里不能重复
items[].content	string	是	Markdown 正文
items[].title	string	否	标题，最长 500。更新时不传则保留原标题
items[].type	string	否	`note` 或 `crawl`。新建默认 `note`。更新时不传则保留原类型
items[].properties	object	否	笔记属性。更新时传入会替换整组属性；不传则保留原属性

属性规则与开放接口里的文本创建相同。单选、多选、状态可以填选项显示名。进度类数字用 0 到 1。评分是 0 到 5 的整数。关联属性的值是笔记 noteId 数组。

错误码

错误码	说明
000000	成功
000001	参数错误，或来源未开通
000005	服务器暂时无法导入
000008	认证失败

导入 API

On this page