员工福利购物 / 企业采购

额度与下单

员工福利与企业采购用的都是企业额度：企业的钱先进企业额度池，管理员再按批次发给员工，员工下单时从自己的额度扣减； 企业也可以配置为由员工自己付现金（支付宝 / 微信 / 对公，见下文）。

接口字段统一叫 points。福利应用的界面通常叫「福豆」，采购应用请叫「企业额度」或「采购额度」——叫法只在你的界面上，接口不区分。

1. 1
   管理员发放额度

   以管理员身份（x-open-user 放 owner 或 admin）调 POST /v1/enterprise/org/points，用 userId 指定员工，或 action: "grant-all" 全员发放。福利类型 theme 的可选值用 GET /v1/enterprise/points/themes 查，不要写死。每批额度最长 90 天有效，到期未用完退回企业。

2. 2
   员工结算预览

   调 POST /v1/enterprise/checkout/render 拿权威价、运费和库存，响应里的 points.sufficient 告诉你这单额度够不够。

3. 3
   员工下单

   调 POST /v1/enterprise/orders，固定带 payWith: "auto"：扣额度还是让员工付现金由平台按企业配置（见下文）。扣额度与建单在同一个事务里， 不会出现扣了额度却没建单。收货地址传省、市、区名称，用 GET /v1/divisions 逐级选出省、市、区县和乡镇街道（街道名称放 street）——自己写的叫法 （如「杭州」少了「市」、撤并前的旧区名）上游会以 321000 地址没有找到 拒单。也可以把地址存进地址簿，下单传 addressId。

员工付现金（福利与采购都支持）

每单由谁付由平台按与企业的约定配置：全额扣员工额度，或员工在企业购收银台自己付现金（支付宝个人、微信、对公转账）。 福豆与现金按比例混合暂未开放，开放后接入不用改。下单统一带 payWith: "auto"，平台按配置处理； 你的 appKey 没开通员工付现金时一律扣额度。

• 结算预览返回 cash 就是这单要员工付现金：cash.cent 是金额，cash.payTypes 是可选的支付方式。 在你的下单页让员工选一种，作为下单的 payType 传入（要付现金却没传返回 PAY_TYPE_REQUIRED）。 可选范围由平台按 appKey 配置；没配时支付宝小程序为支付宝 + 对公，微信小程序为微信 + 对公，网页为全部（电脑上不含微信）。
• 响应里的 launchUrl 是付款入口，24 小时有效。把员工带过去付款；对公支付会显示收款账户信息， 员工用企业对公账户转账，到账有延迟。device 选电脑或手机（缺省按 appKey 登记的端）。
• 付完平台核实到账、扣额度（如有）、结清订单，再跳回你传的 returnUrl（须 https，且是你登记的回调地址的域名或其子域），并追加 bizOrderId 与 result。没传 returnUrl 时停在平台的结果页。
• 员工中途关了页面、链接过期：调 POST /v1/enterprise/orders/{bizOrderId} 带 action: "resume-pay" 取新的链接（不会重复收钱）；默认沿用发起过的支付方式，传新的 payType 可以更换。已经付完的会直接结清。
• 订单关闭或售后时，现金由企业购原路退回，额度退回员工。

result 只是提示，是否已付清以订单为准：订单详情的 mixedPay.status 为 confirmed 才算付清（pending 未付、paid 已到账结清中、failed 订单已关），也会收到 order.status 推送。员工付现金要找平台为你的 appKey 开通。