Idealo 商品搜索与商家报价 API

每次提交一个关键词短语。在 body 字段填写序列化 JSON 文本，例如 {"country":"de","values":["iphone 16"]}。country 只能为 de 或 at，values 必须是仅含一个字符串的数组。直接调用网关时，应把这段 JSON 文本作为公开参数 body 的字符串值发送，不要将 country 和 values 拆成外层参数。德国查询已经实际验证；奥地利仅由请求结构声明支持，尚未测试。 观测到的创建响应含 error:false 和 job_id，只说明查询已受理，既没有商品数据，也不代表已找到商品。请用返回的 job_id 调用 get-job，等任务进入终态后再处理结果。已完成的德国 iphone 16 查询返回了 36 条 found 商品记录，每条包含 query、status 和 result。商品字段包括 id、name、url、image_urls、description、review_rating、review_count、category_ids、price_min、offers_count、country 和 fetched_at；部分元数据及 price_avg、price_max 为 null。数量与价格只描述该次观测，不是固定返回规模。 第一条商品 204736899 的 offers_count 为 512，但 offers=[]。关键词搜索不返回各商家的报价明细。核对候选商品规格后，再将选定的国家与商品 ID 交给 search-by-id。另行验证过报价明细的是 128GB 黑色款 204771161，并非第一条商品。一个无意义关键词同样被受理为任务，最终完成时返回一条 not_found、result:null，且 summary.found=0。不要把未找到商品当成价格为零。

提交一个 Idealo 数字商品 ID 及其所属国家。在 body 中填写 JSON 文本，例如 {"country":"de","values":["204771161"]}；直接调用网关时，将整段文本作为 body 的字符串值。country 仅接受 de 或 at，德国已验证，奥地利尚未测试。values 必须恰好包含一个 ID 字符串。请从同一国家的商品条目中选取 ID；文档声明创建任务时会拒绝 0 和以零开头的 ID。本操作不涉及店铺账户、价格更新或报价上传。 实际创建响应包含 error:false 和 job_id，需通过 get-job 取回结果。商品 204771161 的终态观测为 status:completed、operation:search-by-id、done=1、total=1、summary.found=1。其 found 记录回显 query，且 result.id=204771161，另有名称 Apple iPhone 16、price_min、price_avg、price_max、offers_count、image_urls、country 和 fetched_at。该次返回中的品牌、描述和评价字段为 null。 结果包含 20 条报价，观测字段包括 title、sellerId、shop_name、shop_url、shop_type、marketplace_name、shop_review_rating、shop_review_count、position、condition、currency、price、shipping、total、voucher、availability_code 和 availability_text。free_return 与 direct_sale 可能为 null；该样本也包含 classification 和 confidence。价格币种为 EUR，部分独立店铺的 marketplace_name 使用字符串 N/A。比价时应结合含运费总价、可售状态和成色，不要只按商品价排序。同一 ID 先前在搜索摘要中的报价数为 82，因此取回的 20 条明细不能证明覆盖全部商家。

每次查询一个由 8–14 位数字组成的 GTIN、EAN、UPC 或 JAN 条码。请始终保留为字符串，包括前导零。在 body 中填写 JSON 文本，例如 {"country":"de","values":["4008400401621"]}；直接调用网关时，将这段文本作为 body 的字符串值。JSON 对象中的 country 只能为 de 或 at，values 必须恰好包含一个条码字符串。实际成功验证只覆盖德国。 观测到的创建响应含 error:false 和 job_id。通过 get-job 取回后，德国 EAN 4008400401621 查询已完成，返回一条 found 的 Ferrero Nutella 商品，id 为 4375366，带有匹配的 ean、country:de、fetched_at、image_urls、category_ids、price_min、price_avg、price_max、offers_count，以及九条 EUR 报价。每条报价包括标题、shop_name、price、shipping、total、成色与可售状态，并带 classification:product_page_match 和 confidence:high；商品的 page_type 为 product。品牌、描述等部分元数据为 null。 比价前必须同时核对商品身份与数量。该 EAN 对应 Nutella 450g，但某条返回报价是 15 x 450g 多件装，且同样标为 product_page_match/high。这些标记本身不能证明是单件或完全相同规格。文档还提到其他页面类型的匹配，但实际观测未覆盖，不能据此承诺统一的分类准确率或完整商家覆盖。审核目录映射后，请连同返回的 ean、商品 ID、国家和时间戳一起保存。

使用已知 Idealo 商品链接查询，而非关键词或条码。在 body 中填写含 country 与 values 的 JSON 对象文本，values 必须恰好包含一个 URL 字符串；直接调用网关时，将整段文本作为 body 的字符串值。country 仅接受 de 或 at，商品链接必须属于相同国家。占位示例使用的是关键词结果中实际出现过的德国商品链接，不是编造的地址。不要提交类目页、任意店铺链接或多个链接。 文档声明创建响应会返回 job_id，随后通过 get-job 取回结果。此路径用于读取指定商品条目及商家报价，但尚无成功的实际 URL 查询响应，因此受理表现与准确结果字段仍未验证。不能把 ID 或条码任务中观测到的详细字段，当成本路径已验证的响应。正式依赖前，应使用当前有效、国家匹配的商品链接单独测试。请保留提交链接与最终逐条状态，并核对任何返回的商品身份。

传入关键词、商品 ID、条码或链接查询刚返回的 job_id。这里不提供可长期复用的示例任务 ID：结果在完成后一小时保留期结束后过期。文档中的生命周期为 pending，随后进入 completed 或 failed；等待期间 results 为空。请间隔轮询，例如从约五秒开始，并配合退避、截止时间和总调用次数预算。一次查询至少需要创建与取回各一次调用；增加轮询只会增加网络请求，并不保证任务更早完成。 实际已完成响应包含 error、job_id、status、source、operation、country、created_at、done、total、summary 和 results。summary 含 found、not_found、error 与 classifications；每条结果含 query、status 和 result。ID、条码查询的 found 结果提供商品身份、价格摘要、offers 和 fetched_at；关键词查询则返回商品摘要，offers=[]。单关键词任务出现过 done=1、total=1，但有 36 条 found 商品记录，因此这两个计数不是不同商品条目的数量。 顶层 error:false 与 status:completed 不代表商品已找到。已验证的无意义关键词任务完成时，done=1、total=1、summary.found=0、summary.not_found=1、summary.error=0，并返回一条 status:not_found、result:null。条目 error 与整个任务 failed 是不同的文档结果，必须同时检查任务状态和每条结果状态。条目提供 errorCode 时，如遇 invalid_query，应修正输入而非盲目重试；其他错误也要限制重试次数。 请在过期前保存可用快照，连同请求国家、query、operation 及商品 fetched_at。created_at 是任务创建时间，不是商品观测时间。null 不能替换成零、false 或空字符串。这个接口读取的是临时任务输出，不提供历史价格档案。文档声明未知或过期 ID 会返回 Job not found，但该错误分支尚未经实际调用验证。

无需商品参数即可发起服务存活检查。文档中的成功响应为 {"ok":true}。该接口未包含在现有实际观测中，因此响应内容与当前可用性都尚未验证。 ping 成功仅表示服务可达，不会创建商品任务、返回商品条目、验证 EAN 匹配，也不能证明商家采集正常或价格新鲜。请将可达性告警、查询任务失败与正常的 not_found 分开处理。需要验证完整采集流程时，应创建商品任务并检查终态结果，不能用 ping 替代。