订单类接口

创建采购订单

场景：服务商调用当前接口实现企业创建采购订单，配合支付开票接口使用。当前场景只适用于农产品收购交易场景，采购企业面向农户采购初级农产品时，农户出示数农码给到采购企业扫码，扫码后采购企业通过此接口创建相关采购订单（订单携带农户的数农码编号），订单的结果通过查询接口获取。

调用方法B2COrders.createV2

SDK 示例（Java）

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2Param;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2Param.NeedProofsAndCertificates;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2Param.Product;
import java.math.BigDecimal;
import java.util.Arrays;

// 构建商品列表
Product product = Product.builder()
    .goodTypeNames("蔬菜>绿色蔬菜>青菜")
    .productManagementName("有机青菜")
    .expectNumber(new BigDecimal("100"))
    .expectUnits("公斤")
    .expectUnitPrice(new BigDecimal("5.50"))
    .expectPrice(new BigDecimal("550.00"))
    .taxRate(new BigDecimal("0.09"))
    .postMode(0)
    .purchaseDistrictId("110101")
    .purchaseAddress("北京市东城区某某街道某某号")
    .demand("新鲜无虫害")
    .build();

// 构建请求参数
OrdersCreateV2Param param = OrdersCreateV2Param.builder()
    .businessNo("BUSINESS20240126001")
    .snCode("SN123456")
    .customerName("XX食品有限公司")
    .customerUscc("91110000XXXXXXXXXX")
    .payMode(1)
    .totalPrice(new BigDecimal("550.00"))
    .products(Arrays.asList(product))
    .customerStaffPhone("13800138000")
    .transferRemark("测试转账备注")
    .needProofsAndCertificates(NeedProofsAndCertificates.builder()
        .selfProducedCertificate(false)
        .build())
    .build();

// 调用接口
OrdersCreateV2 result = B2COrders.createV2(param);
System.out.println("订单号: " + result.getPurchaseOrderNo());

POST/open-api/ncp-purchase-order/create-v2

请求参数 Body

snCodestring必需

数农码编号

最大长度 100

businessNostring必需

业务请求流水号，必须保持唯一性

最大长度 50

payModeenum<integer>必需

结算账户类型

枚举值:

1银行卡

2微信

totalPricenumber必需

商品总金额

decimal(12, 2)，最多保留 2 位小数

productsarray[object]必需

商品列表

goodTypeNamesstring必需

商品类目名称（多级拼接名称），三级类目名称用 > 分隔，如：蔬菜>绿色蔬菜>青菜。参见 类目编码表

productManagementNamestring可选

自定义商品名称，发票版式将会显示具体内容

最大长度 50

expectNumbernumber必需

采购数量

decimal(18, 8)，最多保留 8 位小数

expectUnitsstring必需

采购商品单位

最大长度 10

expectUnitPricenumber必需

采购商品单价

decimal(18, 8)，最多保留 8 位小数

expectPricenumber必需

采购金额

decimal(12, 2)，最多保留 2 位小数

taxRatenumber可选

税率

decimal(5, 4)

qualitySpecstring可选

品质规格，自定义规格内容

最大长度 50

postModeenum<integer>必需

发货方式

枚举值:

0采购地现场发货

1指定工厂/仓库发货

purchaseDistrictIdstring必需

交货地址编码，6 位行政区划代码，参考全国地区编码

purchaseAddressstring必需

收货详细地址

最大长度 200

demandstring可选

采购要求，自定义内容

最大长度 100

customerNamestring必需

采购商名称

最大长度 100

customerUsccstring必需

采购商统一社会信用代码

长度 18，数字或者大写字母

agentIdentificationstring可选

经纪人外部 ID，跟经纪人手机号二选一；与采购商员工手机号不能同时传入

最大长度 32

agentPhonestring可选

经纪人手机号，跟经纪人外部 ID 二选一；与采购商员工手机号不能同时传入

长度 11

customerStaffPhonestring可选

采购商员工手机号，与经纪人外部 ID、经纪人手机号不能同时传入

长度 11

invoiceRemarkstring可选

发票备注，自定义发票备注

最大长度 450

transferRemarkstring可选

转账备注

最大长度 60

needProofsAndCertificatesobject可选

需要上传的农户证明和合格证

selfProducedCertificateboolean可选

自产自销证明，true 需要上传，false 不需要

animalQuarantineCertificateboolean可选

动物检疫证明，true 需要上传，false 不需要

loggingCertificateboolean可选

采伐证，true 需要上传，false 不需要

forestOwnershipCertificateboolean可选

林木权属证明，true 需要上传，false 不需要

plantingOriginInfoboolean可选

种养殖产地信息，true 需要上传，false 不需要

conformityCertificateboolean可选

承诺达标合格证，true 需要上传，false 不需要

extendFieldsarray[object]可选

订单附件

namestring可选

字段名称，如：农户与农产品照片、过磅单、收购合同、砍伐证、其他资料等

valuestring可选

附件链接地址

响应参数

msgstring可选

显示消息内容

codeinteger必需

响应码，200 表示接口请求正常

dataobject必需

请求数据结构体

purchaseOrderNostring可选

订单编号，code 为 200 时返回

下单前查询需要上传的证明材料

场景：服务商在调用创建采购订单接口前，可通过本接口按下单必要参数预查询该笔订单需要农户上传的证明材料和合格证。接口只使用外部系统可获取的采购商、数农码、商品类目和金额信息，不需要传入数字农人内部 ID。

注意

本接口仅返回平台/税务侧配置命中的农户证明材料，不查询采购商自定义证明配置，也不查询旧合格证配置。

调用方法B2COrders.needUploadProof

SDK 示例（Java）

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersNeedUploadProof;
import com.gc365.sznr.sdk.model.b2c.OrdersNeedUploadProofParam;
import java.math.BigDecimal;
import java.util.Collections;

OrdersNeedUploadProofParam.Product product = OrdersNeedUploadProofParam.Product.builder()
    .goodTypeNames("蔬菜>绿色蔬菜>青菜")
    .build();

OrdersNeedUploadProofParam param = OrdersNeedUploadProofParam.builder()
    .snCode("SN123456")
    .customerName("XX食品有限公司")
    .customerUscc("91110000XXXXXXXXXX")
    .totalPrice(new BigDecimal("550.00"))
    .products(Collections.singletonList(product))
    .build();

OrdersNeedUploadProof result = B2COrders.needUploadProof(param);
System.out.println("需要上传证明 bitCode: " + result.getNeedUploadProof());
System.out.println("需要上传证明列表: " + result.getCertificates());

POST/open-api/ncp-purchase-order/need-upload-proof

请求参数 Body

snCodestring必需

数农码编号，用于识别农户

最大长度 100

customerNamestring必需

采购商名称

最大长度 100

customerUsccstring必需

采购商统一社会信用代码

最大长度 18，数字或者大写字母

totalPricenumber必需

商品总金额，用于匹配平台/税务侧金额区间配置

productsarray[object]必需

商品列表

goodTypeNamesstring必需

商品类目名称（多级拼接名称），三级类目名称用 > 分隔，如：蔬菜>绿色蔬菜>青菜。参见 类目编码表

响应参数

msgstring可选

显示消息内容

codeinteger必需

响应码，200 表示接口请求正常

dataobject必需

需要上传的证明材料信息

needUploadProofinteger必需

需要上传证明材料的证明类型 bitCode，0 表示无需上传证明材料

certificatesarray[object]必需

需要上传的农户证明材料列表

certificateTypeenum<string>必需

证明类型，返回值来自平台/税务侧证明配置，不涉及旧合格证配置表

枚举值:

SELF_PRODUCED_CERTIFICATE自产自销证明

ANIMAL_QUARANTINE_CERTIFICATE动物检疫证明

LOGGING_CERTIFICATE采伐证

FOREST_OWNERSHIP_CERTIFICATE林木权属证明

PLANTING_ORIGIN_INFO种养殖产地信息维护

certificateTypeNamestring必需

证明类型名称

bitCodeinteger必需

证明类型 bitCode

订单支付开票

场景：配合订单创建接口使用，调用创建订单后服务商通过调用支付开票接口发起支付开票申请。调用本接口后，待收款的农户在数字农人平台上确认收款。

注意

农户收款确认后，系统将自动进行款项划拨，即企业付款和农户收款。

调用方法B2COrders.payAndInvoiceV2

SDK 示例（Java）

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersPayAndInvoiceV2Param;

OrdersPayAndInvoiceV2Param param = OrdersPayAndInvoiceV2Param.builder()
    .purchaseOrderNo("PO20240126001")
    .build();

B2COrders.payAndInvoiceV2(param);

POST/open-api/ncp-purchase-order/payAndInvoice-v2

请求参数 Body

purchaseOrderNostring可选

平台订单编号

最大长度 64

businessNostring可选

业务请求流水号，与平台订单编号必须至少传一个

最大长度 50

响应参数

msgstring可选

错误消息

codeinteger必需

响应码，200 表示正常

dataobject可选

数据有就显示，没有就不显示

订单查询

场景：发起订单支付开票后，服务商可通过此接口查询订单支付开票结果。

调用方法B2COrders.oneV2

SDK 示例（Java）

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersQueryOneV2Param;
import com.gc365.sznr.sdk.model.b2c.OrdersQueryOneV2;

// 通过订单号查询
OrdersQueryOneV2Param param = OrdersQueryOneV2Param.builder()
    .purchaseOrderNo("PO20240126001")
    .build();

OrdersQueryOneV2 result = B2COrders.oneV2(param);

POST/open-api/ncp-purchase-order/one-v2

请求参数 Body

purchaseOrderNostring可选

采购订单编号，传创建订单时的请求订单号

最大长度 64

businessNostring可选

业务请求流水号，与采购订单编号至少传一个

响应参数

msgstring可选

错误消息

codeinteger必需

响应码，200 表示正常

dataobject必需

订单数据

purchaseOrderNostring必需

采购订单编号

externalOrderNostring必需

业务请求流水号

taxOrgansstring必需

省市级税务机关，参考税务机关编码

accountTypeenum<string>可选

经纪人账户类型，只有经纪人模式的订单才有值，否则为 null

枚举值:

MARGIN保证金账户

INTERNAL企业授权账户

snCodestring必需

数农码

bankNamestring可选

开户行

最大长度 50

bankNostring可选

农户收款的银行卡号

最大长度 50

statusenum<string>必需

订单状态

枚举值:

WAIT_PAY待付款

WAIT_PERFECT待完善

WAIT_COMPLETE待补全

WAIT_INVOICE待开票

FINISH已完成

CANCEL已取消

payStatusenum<integer>必需

支付状态

枚举值:

0待支付

1已支付

2已取消

3支付失败

4支付中

5待收款方确认

payMsgstring可选

支付错误信息

最大长度 500

payTimestring可选

支付时间

receiptPaymentsTimestring可选

收款时间

invoiceStatusenum<integer>必需

发票状态

枚举值:

0待开票

1开票中

2开票成功

3开票失败

invoiceMsgstring可选

发票错误信息

最大长度 500

totalPricenumber必需

商品总金额

taxAmountnumber必需

税额

productsarray[object]必需

商品列表

goodTypeNamesstring必需

商品类目名称（多级拼接名称），三级类目用 > 分隔

productManagementNamestring可选

自定义商品名称

expectNumbernumber必需

采购数量

expectUnitsstring必需

采购商品单位

expectUnitPricenumber必需

采购商品单价

expectPricenumber必需

采购金额

taxAmountnumber必需

税额，农产品免税

qualitySpecstring可选

品质规格

postModeenum<integer>必需

发货方式

枚举值:

0采购地现场发货

1指定工厂/仓库发货

purchaseDistrictIdstring必需

交货地址编码，参考全国地区编码

purchaseProvinceNamestring必需

收货省名称

purchaseCityNamestring必需

收货市名称

purchaseDistrictNamestring必需

收货县区名称

purchaseAddressstring必需

收货详细地址

demandstring可选

采购要求

invoiceRemarkstring可选

发票备注

最大长度 450

needUploadProofboolean可选

是否需要农户上传自产自销证明

extendFieldsarray[object]可选

订单附件

namestring可选

字段名称

valuestring可选

字段值（附件链接地址）

查询支付回单

场景：批量查询企业已完成交易的支付订单回单信息（只适合订单状态是"已完成"），支持银行和微信支付回单数据查询。

调用方法B2COrders.receiptUrl

SDK 示例（Java）

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersReceiptUrlParam;
import java.util.Arrays;

OrdersReceiptUrlParam param = OrdersReceiptUrlParam.builder()
    .purchaseOrderNos(Arrays.asList("PO20240126001"))
    .build();

OrdersReceiptUrl result = B2COrders.receiptUrl(param);
System.out.println("回执URL: " + result.getReceiptUrls());

POST/open-api/ncp-purchase-order/receipt-url

请求参数 Body

purchaseOrderNosarray[string]可选

采购订单号数组，创建订单时生成的采购订单号，与 businessNos 二选一

businessNosarray[string]可选

外部单号数组，与 purchaseOrderNos 二选一

响应参数

msgstring可选

错误消息

codeinteger必需

响应码，200 表示正常

dataobject必需

数据结构体

receiptUrlsarray[object]必需

支付回单数组

purchaseOrderNostring必需

采购订单号

receiptUrlstring必需

支付回单的地址

订单批量查询

场景：服务商可通过此接口批量查询采购订单详情。支持通过采购订单编号列表或外部业务流水号列表查询，当两个列表同时传入时，以采购订单编号列表为准。

调用方法B2COrders.listV2

SDK 示例(Java)

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersListV2Param;
import com.gc365.sznr.sdk.model.b2c.OrdersListV2;
import java.util.Arrays;

// 通过订单号列表查询
OrdersListV2Param param = OrdersListV2Param.builder()
    .purchaseOrderNos(Arrays.asList("PO20240126001", "PO20240126002"))
    .build();

OrdersListV2 result = B2COrders.listV2(param);

POST/open-api/ncp-purchase-order/list-v2

请求参数 Body

purchaseOrderNosarray[string]可选

采购订单编号列表

businessNosarray[string]可选

外部业务流水号列表

响应参数

msgstring可选

错误消息

codeinteger必需

响应码,200 表示正常

dataarray[object]可选

订单列表数据,具体结构请参考订单查询接口返回的 data 对象

errorCodestring可选

业务错误码

stackTraceStringstring可选

堆栈异常信息

订单取消

场景：当企业已提交开票和转账申请，订单状态处于某个阶段（订单状态已完成、已取消或者支付状态已支付、支付失败等情况除外），且因业务原因企业有意向取消该笔申请时，调用此接口完成订单支付开票申请的取消。

调用方法B2COrders.cancel

SDK 示例（Java）

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersCancelParam;

OrdersCancelParam param = OrdersCancelParam.builder()
    .purchaseOrderNo("PO20240126001")
    .cancelReason("PLAN_CHANGE")
    .cancelRemark("计划有变")
    .build();

B2COrders.cancel(param);

POST/open-api/ncp-purchase-order/cancel

请求参数 Body

purchaseOrderNostring可选

采购订单号，创建订单时生成的采购订单号，与 businessNo 二选一

businessNostring可选

外部单号，与 purchaseOrderNo 二选一

cancelReasonenum<string>必需

取消原因

枚举值:

ORDER_INFO_ERROR订单信息有误

PLAN_CHANGE计划有变取消交易

REPEAT_PAY_ORDER重复下单

OFFLINE_TRADE需要线下交易

OTHER其他原因

cancelRemarkstring可选

补充说明，订单取消时补充取消的具体详细原因

最大长度 20

响应参数

msgstring必需

显示消息内容

codeinteger必需

响应码，200 表示取消成功，非 200 表示取消失败

okboolean必需

操作是否成功