# 电路设计服务企业 API

## 1. 开通与认证

企业账号由管理员审核开通。登录网页后，在“账户与额度”中创建 API 密钥。密钥只显示一次，请存入企业的密钥管理系统，不要写入浏览器代码或公开仓库。

所有请求使用：

```http
Authorization: Bearer api_xxxxxxxxxx
Content-Type: application/json
```

创建类请求还必须提供唯一幂等键：

```http
Idempotency-Key: your-order-id-20260819-001
```

同一个幂等键重复提交相同内容只会创建一次任务；同一个键提交不同内容会被拒绝。默认限速为每个密钥每分钟 60 次。

## 2. 查询账户

```sh
curl https://c.yuantuo.com/api/v1/account \
  -H 'Authorization: Bearer api_xxxxxxxxxx'
```

返回 Token 可用余额、冻结额度、充值订单和账本记录。

## 3. 创建电路设计

```sh
curl -X POST https://c.yuantuo.com/api/v1/designs \
  -H 'Authorization: Bearer api_xxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: project-001' \
  -d '{
    "instruction": "设计一块 5-24V 供电的控制板，包含一路 RS485 和一路继电器",
    "complexity": {
      "layers": 2,
      "pinCount": 80,
      "connectionCount": 45,
      "highSpeedNets": 0,
      "boardAreaMm2": 3500
    },
    "engineeringDecisionsConfirmed": true
  }'
```

成功返回 HTTP 202、任务 ID、预计 Token 和预计人民币金额。系统会先冻结预计 Token；任务失败会释放，任务成功才正式扣除。

`engineeringDecisionsConfirmed=true` 表示常规器件、保护、阻容、封装和布局细节由设计服务按成熟工程规则决定。产品功能、安全边界或机械条件发生实质冲突时，任务仍会暂停并说明需要的让步。

## 4. 查询任务和成果

```sh
curl https://c.yuantuo.com/api/v1/designs/DESIGN_ID \
  -H 'Authorization: Bearer api_xxxxxxxxxx'

curl https://c.yuantuo.com/api/v1/designs/DESIGN_ID/artifacts \
  -H 'Authorization: Bearer api_xxxxxxxxxx'
```

任务状态包括排队、方案生成、构建、等待确认、完成和失败。成果接口仅在任务完成后返回 PCB 预览、原理图、Gerber、BOM/CPL、STEP、交互式三维模型和发布清单地址。

## 5. 购买生产下单协助

生产下单协助与电路设计分开计费。当前标准项目为 1000 Token（人民币 15 元）。

```sh
curl -X POST https://c.yuantuo.com/api/v1/orders \
  -H 'Authorization: Bearer api_xxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"your-project-id"}'
```

同一账号、同一项目重复调用不会重复收费。登录、验证码、器件审核异常、客户寄料和付款必须由人工确认，系统不会自动付款。

## 6. 错误码

| HTTP | 含义 |
| --- | --- |
| 400 | 参数或幂等键缺失 |
| 401 | 未登录或密钥无效 |
| 402 | Token 不足或尚未购买对应服务 |
| 403 | 账号无企业 API 权限 |
| 404 | 任务或项目不存在，或不属于当前账号 |
| 409 | 当前状态不允许操作 |
| 422 | 需求或复杂度参数无法处理 |
| 429 | 超过每分钟请求上限 |

机器可读接口定义：`https://c.yuantuo.com/api/openapi.yaml`。