digikey

DigiKey 零件搜索与分析

相关技能

技能	用途
kicad	原理图分析——提取 MPN 以同步数据手册
bom	BOM 管理——协调从各分销商采购
spice	使用 DigiKey 参数数据创建行为级 SPICE 模型

DigiKey 是原型订单的主要来源（Mouser 为次要来源）。其 API 会返回数据手册 PDF 的直接链接，因此是首选的数据手册来源。对于生产订单，请参阅 lcsc/jlcpcb。有关 BOM 管理和导出工作流，请参阅 bom。

API 凭据设置

DigiKey API 需要 OAuth 2.0 凭据。设置方法如下：

1. 如果你还没有 DigiKey 账户，请在 digikey.com 创建账户
2. 在 developer.digikey.com 注册 API 应用：
   • 使用 DigiKey 账户登录
   • 前往“My Apps” → “Create App”
   • 应用名称：任意（例如，“kicad-happy”）
   • 选择 “Product Information v4” API
   • OAuth 类型：Client Credentials（双向流程，无需用户登录）
   • 回调 URL：https://localhost（客户端凭据流程不会使用，但此项为必填）
   • 创建后，记下 Client ID 和 Client Secret
3. 运行脚本前设置环境变量：

   export DIGIKEY_CLIENT_ID=your_client_id_here
   export DIGIKEY_CLIENT_SECRET=your_client_secret_here
   

   如果凭据存储在集中式机密文件（例如 ~/.config/secrets.env）中，请先加载：

   export $(grep -v '^#' ~/.config/secrets.env | grep -v '^$' | xargs)
   

客户端凭据流程无需用户交互——配置完成后，API 调用会自动运行。

DigiKey Product Information API v4

API 是搜索 DigiKey 的首选方式。它会返回包含完整产品详情、价格、库存、数据手册和参数数据的结构化 JSON。

基础 URL： https://api.digikey.com

身份验证

所有 API 请求都需要 OAuth 2.0。使用客户端凭据流程（双向流程）。必须将凭据加载为环境变量（参见上文“API 凭据设置”）。

curl -s -X POST https://api.digikey.com/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${DIGIKEY_CLIENT_ID}&client_secret=${DIGIKEY_CLIENT_SECRET}&grant_type=client_credentials"

响应会返回一个有效期为 10 分钟的 access_token。将令牌缓存在 shell 变量中，以便在同一会话的后续调用中重复使用。如果会话中途收到 401 错误，说明令牌已过期——请重新进行身份验证以获取新令牌。

必需的标头

每次 API 调用都需要：

X-DIGIKEY-Client-Id: ${DIGIKEY_CLIENT_ID}
Authorization: Bearer <access_token>

可选的区域设置标头：

• X-DIGIKEY-Locale-Language：en（默认）、ja、de、fr、ko、zhs、zht、it、es
• X-DIGIKEY-Locale-Currency：USD（默认）、CAD、EUR、GBP、JPY 等
• X-DIGIKEY-Locale-Site：US（默认）、CA、UK、DE 等

KeywordSearch — 查找零件

POST /products/v4/search/keyword

这是主要的搜索端点。可按 MPN、DigiKey 零件编号、描述或关键词搜索。

请求正文：

{
  "Keywords": "GRM155R71C104KA88D",
  "Limit": 25,
  "Offset": 0,
  "FilterOptionsRequest": {
    "MinimumQuantityAvailable": 1,
    "SearchOptions": ["InStock", "HasDatasheet", "RoHSCompliant"],
    "ManufacturerFilter": [{"Id": "..."}],
    "CategoryFilter": [{"Id": "..."}],
    "StatusFilter": [{"Id": "..."}],
    "MarketPlaceFilter": "ExcludeMarketPlace"
  },
  "SortOptions": {
    "Field": "Price",
    "SortOrder": "Ascending"
  }
}

主要请求字段：

• Keywords（字符串，最多 250 个字符）——搜索词（MPN、DK PN、描述）
• Limit（整数，1–50）——每页结果数
• Offset（整数）——分页偏移量
• SearchOptions——以下选项的数组：InStock、HasDatasheet、RoHSCompliant、NormallyStocking、Has3DModel、HasCadModel、HasProductPhoto、NewProduct
• SortOptions.Field——Price、QuantityAvailable、Manufacturer、ManufacturerProductNumber、DigiKeyProductNumber、MinimumQuantity
• MarketPlaceFilter——NoFilter、ExcludeMarketPlace、MarketPlaceOnly

响应——每个 Products[] 项中的主要字段：

{
  "ManufacturerProductNumber": "GRM155R71C104KA88D",
  "Manufacturer": {"Id": 563, "Name": "Murata Electronics"},
  "Description": {
    "ProductDescription": "CAP CER 100NF 16V X7R 0402",
    "DetailedDescription": "..."
  },
  "UnitPrice": 0.01,
  "QuantityAvailable": 248000,
  "ProductUrl": "https://www.digikey.com/...",
  "DatasheetUrl": "https://...",
  "PhotoUrl": "https://...",
  "ProductVariations": [
    {
      "DigiKeyProductNumber": "490-10698-1-ND",
      "PackageType": {"Name": "Cut Tape"},
      "StandardPricing": [
        {"BreakQuantity": 1, "UnitPrice": 0.01, "TotalPrice": 0.01},
        {"BreakQuantity": 10, "UnitPrice": 0.008, "TotalPrice": 0.08}
      ],
      "QuantityAvailableforPackageType": 248000,
      "MinimumOrderQuantity": 1,
      "StandardPackage": 10000
    }
  ],
  "Parameters": [
    {"ParameterText": "Capacitance", "ValueText": "100nF"},
    {"ParameterText": "Voltage Rated", "ValueText": "16V"},
    {"ParameterText": "Temperature Coefficient", "ValueText": "X7R"},
    {"ParameterText": "Package / Case", "ValueText": "0402 (1005 Metric)"}
  ],
  "ProductStatus": {"Status": "Active"},
  "Category": {"Name": "Ceramic Capacitors"},
  "Classifications": {"RohsStatus": "ROHS3 Compliant"},
  "Discontinued": false,
  "EndOfLife": false,
  "NormallyStocking": true
}

ProductDetails — 获取单个零件的完整详情

GET /products/v4/search/{productNumber}/productdetails

使用此端点获取特定零件的详细信息。{productNumber} 可以是 DigiKey 零件编号或制造商零件编号。

查询参数：

• manufacturerId（可选）——区分与多个制造商匹配的 MPN（例如，“CR2032”）

返回完整的 Product 对象，其中包含所有参数、价格（使用账户身份验证时还包括 MyPricing）、媒体链接和相关产品。

其他实用端点

端点	方法	描述
/products/v4/search/{pn}/productdetails	GET	单个料号的完整产品信息
/products/v4/search/productpricing/{pn}	GET	料号的 MyPricing 价格信息
/products/v4/search/{pn}/media	GET	料号的所有媒体（图片、数据手册）
/products/v4/search/manufacturers	GET	所有制造商（在 KeywordSearch 筛选器中使用 ID）
/products/v4/search/categories	GET	所有类别（在 KeywordSearch 筛选器中使用 ID）
/products/v4/search/{pn}/alternatepackaging	GET	可选包装方式
/products/v4/search/{pn}/substitutions	GET	替代料号
/products/v4/search/{pn}/recommendedproducts	GET	推荐/相关料号

速率限制

适用每分钟和每日配额。超出限制时返回带有 Retry-After 标头的 HTTP 429。

错误响应

所有错误均返回 DKProblemDetails：

{"type": "...", "title": "...", "status": 401, "detail": "Invalid token", "correlationId": "..."}

备用方案：抓取 DigiKey 网站

如果没有 API 凭据或身份验证失败，可直接抓取产品页面来搜索 DigiKey：

https://www.digikey.com/en/products/result?keywords=<url-encoded-query>

示例：

• https://www.digikey.com/en/products/result?keywords=GRM155R71C104KA88D（按 MPN 搜索）
• https://www.digikey.com/en/products/result?keywords=100nF+0402+X7R+16V（按规格搜索）

DigiKey 的搜索结果可能比较杂乱（页面大量依赖 JS）。请查找包含以下信息的产品表格行：DigiKey 料号、MPN、描述、单价、库存数量和数据手册链接。如果结果被截断或为空，请尝试按确切 MPN 而非关键词搜索。

下载和分析数据手册

DigiKey 的 API 会提供直接 PDF URL，这是下载数据手册的首选方式，因为它可以避免网页抓取，并提供可靠、稳定的链接。其他技能（kicad、bom）应优先使用 DigiKey API 获取数据手册。

数据手册目录同步（主要工作流）

使用 sync_datasheets_digikey.py 在 KiCad 项目旁维护 datasheets/ 目录。该脚本会从原理图中提取元器件，搜索 DigiKey 上的数据手册 URL，下载缺失的 PDF，并写入 manifest.json 清单。后续运行采用增量方式——仅获取新增或变更的料号。

# Sync datasheets for a KiCad project (creates datasheets/ next to the schematic)
python3 <skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch>

# Preview what would be downloaded
python3 <skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch> --dry-run

# Retry previously failed downloads
python3 <skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch> --force

# Custom output directory
python3 <skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch> -o ./my-datasheets

# Use pre-computed analyzer JSON instead of running the analyzer
python3 <skill-path>/scripts/sync_datasheets_digikey.py analyzer_output.json

# Parallel downloads (3 workers)
python3 <skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch> --parallel 3

# Batch mode — sync from a plain MPN list (no KiCad project required)
python3 <skill-path>/scripts/sync_datasheets_digikey.py --mpn-list mpns.txt --output ./datasheets

MPN 列表批处理模式（KH-312）——适用于已有 MPN 列表，但没有可供指定的 KiCad 项目（用于线束数据手册预置、批量预置新的元器件库）。文件格式为每行一个 MPN。空行和 # 注释（整行或行内）会被跳过。非 MPN 字符串（如 100nF 或 DNP 这样的通用值）会通过 is_real_mpn() 过滤，并去重。若未指定 --output，输出默认位于当前工作目录下的 ./datasheets/。

该脚本会：

• 自动运行 kicad 原理图分析器，提取元器件和 MPN
• 过滤通用无源元器件——跳过没有真实 MPN 的条目（例如“100nF”、“10K”）
• 优先尝试原理图 URL——先使用 KiCad 符号中嵌入的数据手册 URL，再调用 DigiKey API，从而减少 API 调用
• 写入 manifest.json 清单——将每个 MPN 映射到其 PDF 文件、制造商、描述、下载状态和 URL。kicad 技能会在设计审查期间读取该清单，以便将数据手册与原理图交叉核对。
• 跟踪失败情况——记录下载失败及其错误详情；后续运行不会重试，除非使用 --force
• 限制请求速率——每次 DigiKey API 调用之间间隔 1 秒（可通过 --delay 配置）
• 增量保存进度——如果进程中断，已下载的文件会保留

manifest.json 清单的结构：

{
  "schematic": "/path/to/file.kicad_sch",
  "last_sync": "2026-03-09T04:44:30+00:00",
  "parts": {
    "TPS61023DRLR": {
      "file": "TPS61023DRLR.pdf",
      "manufacturer": "Texas Instruments",
      "description": "Boost converter",
      "datasheet_url": "https://...",
      "status": "ok",
      "references": ["U3", "U2"],
      "size_bytes": 2392725
    }
  }
}

下载单个数据手册

使用 fetch_datasheet_digikey.py 下载单个数据手册。它会自动处理特定制造商的特殊情况。

# Search by MPN (uses DigiKey API, requires credentials)
python3 <skill-path>/scripts/fetch_datasheet_digikey.py --search "TPS61023" -o datasheet.pdf

# Direct URL download
python3 <skill-path>/scripts/fetch_datasheet_digikey.py "https://www.ti.com/lit/gpn/tps61023" -o datasheet.pdf

# JSON output for script integration
python3 <skill-path>/scripts/fetch_datasheet_digikey.py --search "ADP1706" --json

该脚本：

• 不受操作系统限制 — 使用 Python requests 库（不依赖 wget/curl）。如果未安装 requests，则回退到 urllib。
• 规范化重定向 URL — TI 器件的 DigiKey DatasheetUrl 指向一个 JS 重定向页面；该脚本会提取直接 PDF 链接。还会修复以 //mm.digikey.com/... 开头的 URL。
• 设置正确的 User-Agent — 许多制造商网站（Nexperia、Lite-On、STMicro、Molex）会拦截不带标识的 urllib 或 curl 请求，但使用浏览器 User-Agent 时可以正常提供 PDF
• 验证 PDF 标头 — 拒绝伪装成下载文件的 HTML 错误页面或 Cloudflare 验证页面
• 回退到其他来源 — 主 URL 失效时，会尝试 Microchip 的已知 URL 模式
• 无头浏览器回退 — 如果已安装 playwright，对于通过 JavaScript 提供 PDF 的网站（Broadcom 文档查看器、Espressif 下载重定向），脚本会自动在最后尝试使用无头 Chromium 浏览器。它会拦截下载事件并直接读取响应正文。
• 退出代码：0 = 成功，1 = 下载失败，2 = 搜索/API 错误
• 依赖项：
  • pip install requests（强烈建议安装；urllib 回退方式无法处理 analog.com 等 HTTP/2 网站）
  • pip install playwright && playwright install chromium（可选；启用无头浏览器回退，以处理大量使用 JS 的网站）

制造商兼容性

在 8 个开源 KiCad 项目的 240 个元件上进行了测试（下载成功率为 96%，不使用 Playwright 时为 94%）：

制造商	状态	备注
TI	可用	URL 规范化会移除 JS 重定向封装
ADI / Analog	可用	requests 会透明处理 HTTP/2
STMicro	可用	需要 User-Agent 标头
Nexperia	可用	需要 User-Agent 标头
Lite-On	可用	需要 User-Agent 标头
Molex	可用	需要 User-Agent 标头
Renesas	可用	直接下载
ON Semi	可用	直接下载
NXP	可用	直接下载
Diodes Inc	可用	直接下载
Microchip	可用	通过 API URL 直接下载
YAGEO、Samsung、Murata	可用	DigiKey 托管的 PDF（mm.digikey.com）
Broadcom	可用*	需要 Playwright — docs.broadcom.com 通过 JS 下载提供 PDF
Espressif	可用*	需要 Playwright — 下载重定向需要执行 JS
Lattice	部分可用	某些 URL 需要 Cookie/身份验证

* 需要 playwright 包 — 如果未安装，则会回退到提示用户。

下载失败时

如果脚本或内联下载失败（退出代码为 1），请告知用户并提供 URL，以便他们在普通浏览器中打开。某些制造商网站（Lattice、TDK InvenSense）需要交互式登录、Cookie 或 CAPTCHA，即使无头浏览器也无法处理。安装 Playwright 后，Broadcom 和 Espressif 的数据手册现在可以自动下载。

给用户的示例消息：

我无法自动下载 ICE40UP5K-SG48I 的数据手册 — Lattice 网站需要浏览器身份验证。以下是直接链接： https://www.latticesemi.com/-/media/LatticeSemi/Documents/DataSheets/iCE/FPGA-DS-02008-1-9-iCE40-Ultra-Plus-Family-Data-Sheet.ashx

你可以在浏览器中打开链接并将文件保存到本地，然后我就可以读取并分析它。

即使下载失败，--json 输出也始终包含 datasheet_url 字段，因此你可以通过程序提取 URL。

手动下载工作流

如果脚本不可用，或你需要直接执行：

1. 搜索元件，使用 KeywordSearch 或 ProductDetails
2. 从 API 响应中提取 DatasheetUrl
3. 规范化 URL——如果以 // 开头，则在前面加上 https:。如果包含 ti.com/general/docs/suppproductinfo，则提取 gotoUrl 查询参数。
4. 使用 requests（Python）或带有浏览器 User-Agent 的 wget/curl 下载
5. 确认文件是 PDF：前 4 个字节应为 %PDF

如果 DatasheetUrl 字段为空，或所有下载方式都失败：

• 向用户提供 URL，供其手动通过浏览器下载
• 尝试 /products/v4/search/{pn}/media 端点，查找其他媒体链接
• 将网络搜索作为最后手段："<MPN> datasheet filetype:pdf"

从数据手册中提取的信息

分析用于 KiCad 设计审查的数据手册时（参见 kicad 技能）：

• 绝对最大额定值——电压、电流和温度限值
• 推荐工作条件——典型工作范围
• 引脚排列和引脚说明——对照 KiCad 符号进行核对
• 封装尺寸——对照 KiCad 封装进行核对
• 典型应用电路——与用户的原理图进行对比
• 热特性——用于功耗计算的 θJA、θJC
• 电气特性——关键参数（Vout、Iq、PSRR 等）

提示

• DigiKey PN 后缀：-ND 标准款，-1-ND 切带，-2-ND digi-reel，-6-ND 整卷
• 使用 ExcludeMarketPlace 筛选条件，避免第三方卖家的商品列表
• ProductVariations[].StandardPricing[] 中的价格阶梯——检查 BreakQuantity 阈值
• 选择元件前，检查 ProductStatus 和 Discontinued/EndOfLife