ASTRALINK

沙箱能判断什么，不能判断什么？

这一页只回答一个问题：这些接口能不能接。

本页读数时点：2026-11-02。接口与阈值会变，以本页日期为准。

一、沙箱是什么／不是什么

这一栏内容
是一个独立的演示环境，用来判断"这些接口能不能接"。
是一个能真打的业务闭环：设备注册、心跳、档案、型号目录、计费事件、用量汇总、主动采集，这些路径在沙箱上都能打通（逐条见第二节）。
不是不是生产环境；数据是 mock；不构成 SLA。沙箱可随时重置，重置后旧钥匙立即失效。
不是不是真设备、不是真证书：采集是演示数据归集，"证书引用"只是一个引用串，不签发真证书。
不是不是全接口：审计查询、审计校验、设备证书三条在沙箱上没有放行（见第二节）。

打个比方：沙箱不是对外开放的展厅，是前台登记后递给你一张临时门卡的实验室——门卡上有你的名字与到期时间，只开你申请的那几扇门，里面的货物是样品。

二、主机与端点清单

主机：sandbox.neutralorbit.com（HTTPS）。接口主机与网站主机是两个站——把接口路径打到 neutralorbit.org 上会是 404，那是"站不同"，不是接口坏了。

"期望码"这一列写的是不带凭证时你第一次打就该看到的码。它不是错误，是"门在那儿、钥匙还没给你"。

方法路径期望码这条是干什么的
GET/healthz200公开探针：只答"服务活着吗"。不要凭证、不含业务数据。
GET/readyz200公开探针：就绪状态。回 503 的意思是"现在别打进来"，不是故障。
GET/meta200公开探针：服务标识（服务名、版本、法务主体、边界声明）。
POST/v1/devices401设备注册与激活。
POST/v1/devices/{device_id}/heartbeat401设备心跳。
POST/v1/billing/events401计费事件上报。
GET/v1/device-models401型号目录（只读）。
POST/v1/device-models401新增型号。需 admin；沙箱不签发 admin，所以带钥匙也是 403。
GET/v1/devices/{device_id}401设备档案（只读）。
PATCH/v1/devices/{device_id}401改设备档案（换型号／停用／启用）。
GET/v1/usage401用量汇总（since／until／group_by=day|device|metric）。
POST/v1/usage/collect401触发一次采集（演示数据归集，不连真设备）。
GET/v1/usage/collect/{job_id}401采集任务状态（只读）。
GET/v1/audit404审计查询。沙箱没放行；主站不带凭证是 401。
GET/v1/audit/verify404审计校验。沙箱没放行；主站不带凭证是 401。
GET｜POST/v1/devices/{device_id}/certificate404设备证书引用。沙箱没放行；主站不带凭证是 401。
GET/proof/verify404证明包离线校验。主站与沙箱都不放行。

沙箱放行的路径于主站不同：沙箱不开放审计查询、审计校验与设备证书三条 —— 在主站它们是 401，在沙箱是 404。以本表为准：打过去是 404，不是你打错了，是这条没放行。

三、怎么领钥匙

领钥匙需书面申请：写明机构名、联系人、要用的接口、需要的期限，发至 partners@neutralorbit.com。我方人工审核后签发，限期不超过 7 天。

不提供在线申请页，不提供即时开通。

确认信里会写明发给你的 scope、到期时刻、调用上限。收不到确认信就是没批——不要拿别人的钥匙试，也不要反复投递。

四、钥匙的四条限制

#限制具体是什么
1一次性一把钥匙只发给一个机构的一个 POC；不续用、不继承、不转让。要再做一轮，重新申请。
2限期 ≤7 天默认 7 天，最短按小时给；到期即失效，不自动续期。
3一条 scope，永不给 admin一把钥匙只带一条 scope（devices:read／devices:write／usage:read／usage:collect／billing:write 之一）。
4限次确认信里会写明你这把钥匙的调用上限；撞到上限就等，不要换钥匙绕。

新增型号接口（POST /v1/device-models）需要 admin，沙箱永远不签发 admin —— 所以这条在沙箱一定 403。

这是设计如此，不是故障，也不是钥匙发错了。

五、失败码怎么读

码意思怎么办
401没报身份带上凭证（Authorization: Bearer … 或 X-Api-Key: …）。
403身份对，权限不够这条 scope 不够，换接口或申请别的 scope。
404这条路径没放行不是服务坏了；见上面的端点清单。
429同一把凭证连续失败 5 次会锁 15 分钟等一下（Retry-After 会告诉你多少秒），别继续试。

锁是按"你那串凭证"算的，不是按 IP：换 IP、换客户端、换头都没用；换一把错钥匙继续猛试，只会把另一串也锁上。

六、三个自测动作（不需要钥匙就能做）

  1. 打 /healthz 看 200 —— 站活着。
  2. 打任一写接口不带凭证，看 401 —— 鉴权真的在拦。
  3. 打一条不存在的路径，看 404 —— 白名单真的在拦。

curl -sS -i https://sandbox.neutralorbit.com/healthz

curl -sS -i -X POST https://sandbox.neutralorbit.com/v1/devices -H "Content-Type: application/json" -d '{}'

curl -sS -i https://sandbox.neutralorbit.com/nope

这三条能回答"站是不是活的、鉴权是不是真在拦、404 是什么意思"；不能回答"审计链、证书、证明包能不能接"（沙箱没放行），也不能回答"真实设备与真实计费对不对"（沙箱是演示数据）。

七、免责

沙箱是演示环境，数据为 mock，不构成 SLA；我方不对沙箱可用性作承诺。