Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

报关

POST /v1/customs/declare

使用此接口向海关传输信息。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：


注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

  • 如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
  • 如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

declarationRequestId String  REQUIRED

商户为识别申报请求而分配的专属 ID。每个申报请求号的长度从 1 位到 32 位不等。  

更多信息：

  • 此为幂等字段。
  • 最大长度：32 字符

paymentId String  REQUIRED

Antom 为识别支付而分配的支付 ID。

更多信息：

  • 最大长度：64 字符

declarationAmount Amount  REQUIRED

累计交易申报金额，不能超过总交易金额。目前仅支持中国海关申报。默认币种为CNY（人民币）。

注意：此字段可以从 支付通知 接口和 支付结果查询 接口中的customsDeclarationAmount字段获取。

Show child parameters

customs CustomsInfo  REQUIRED

海关信息

Show child parameters

merchantCustomsInfo MerchantCustomsInfo  REQUIRED

在海关系统中注册的商户信息。 

Show child parameters

splitOrder Boolean  REQUIRED

此字段表明订单是否被拆分成多份分别报关。如果此字段的值为true，则允许订单拆分。

注意：如果此字段的值为false，则不允许订单拆分。

suborderId String  

商户分配的子订单 ID。

注意事项：

  • 当 splitOrder 为true时，指定此字段。在以下业务场景中，子订单 ID 作为支付信息中的订单 ID 传输给海关：
    • 支付包含多个商品，需要提交给不同的海关，或者海关要求按商品分别提交。
    • 合并支付中，部分商品需要进行海关申报。
    • 其他需要拆分海关申报的情况。
  • 订单拆分后，确保这些子订单的子订单 ID 与支付信息中的订单 ID 相同。否则，因信息不一致，订单会被拒绝。

更多信息：

  • 最大长度：64 字符

buyerCertificate Certificate  

购买者信息。

注意事项：

  • 当需要验证购买者信息时指定此字段。实际上，建议在此接口中提供购买者信息，以符合海关申报政策要求并便于 Antom 检查购买者信息。虽然此字段是可选的，但建议指定此字段，因为海关会随机检查购买者信息。
  • 如果不指定此字段，商家需要确保购买者和付款人的信息一致。海关检测到的任何不一致都将导致申报被拒绝。指定此字段可以降低订单被退回的风险。
Show child parameters

出参

result Result  REQUIRED

请求结果，包含状态和错误代码等信息。 

注意：此字段不表示申报结果。此字段仅表示 报关 接口 是否调用成功。

Show child parameters

customsPaymentId String  

申报服务提供商提供给海关的支付 ID。

注意：当 result.resultCode 为 S 时，返回此字段。

更多信息：

  • 最大长度：64 字符

customsOrderId String  

申报服务提供商提供给海关的订单 ID。

注意：当 result.resultCode 为 S 时，返回此字段。

更多信息：

  • 最大长度：64 字符

identityCheckResult String  

身份验证结果。有效值为：

  • CHECK_PASSED：表示买家也是付款人。
  • CHECK_NOT_PASSED：表示买家不是付款人。

注意：当 result.resultCode 为 S 时返回此字段。如果未返回此字段，表示未检查买家的身份。

clearingChannel String  

清算组织。有效值包括：

  • CUP: 表示清算渠道为银联。例如，当用户使用银行卡支付时，可能会返回此值。
  • NUCC: 表示清算渠道为 NetsUnion。例如，当用户使用银行卡支付时，可能会返回此值。
  • OTHER: 表示清算渠道为其他。例如，当用户使用花呗等信用产品时，会返回此值。

注意：此字段在以下两种情况下返回：

  • resultCode 为 S。
  • 返回了海关报关信息。

clearingTransactionId String  

清算组织的 ID。

注意：此字段在以下两种情况下返回：

  • resultCode 为 S。
  • 返回了海关报关信息。

更多信息：

  • 最大长度：64 字符

customsProviderRegistrationId String  

海关系统中的注册 ID。

注意：此字段在以下两个条件都满足时返回：

  • resultCode 为 S。
  • 返回了海关收据。

更多信息：

  • 最大长度：32 字符
API Explorer
示例代码沙箱运行

请求

URL

请求体

响应

Case
Success
响应体

更多信息

本节提供了关于此接口的额外信息。

海关代码 

此表显示了海关代码的详细信息：


海关名称统一海关解决方案海关代码Antom注册ID
海关总署传输至 ZONGSHUZONGSHU31222699S7
河南保税物流中心传输至 ZHENGZHOUZHENGZHOU31222699S7
宁波海关传输至 NINGBONINGBO31222699S7
新郑综合保税区（机场）传输至 ZONGSHUZONGSHU31222699S7
天津海关传输至 ZONGSHUZONGSHU31222699S7
上海海关传输至 SHANGHAI_CBTSHANGHAI_CBT31222699S7
广州海关（机场）传输至 ZONGSHUZONGSHU31222699S7
广州海关（南沙）传输至 ZONGSHUZONGSHU31222699S7
广州海关（黄埔）传输至 ZONGSHUZONGSHU31222699S7
广州海关（沙田）传输至 ZONGSHUZONGSHU31222699S7
杭州海关传输至 ZONGSHUZONGSHU31222699S7

 

支付信息重传

报关 接口可以重新触发，用于将支付数据发送到海关。重传在以下情况下使用：

  • 海关系统中缺少支付数据。
  • 之前的申报数据包含错误信息。

注意事项：

  • declarationRequestId 必须与原始请求相同，否则将被视为新请求。
  • 在重传中，仅能修改 merchantCustomsCode、merchantCustomsName、customsPlace, declarationAmount、suborderId 和 buyer。重传的 declarationAmount 不计入海关申报的总金额。


重传条件

在重新触发接口之前，请确保满足以下条件：

  • Antom 系统中存在具有相同 declarationRequestId 的申报。
  • 自上次调用以来已超过 5 分钟。（Antom 可能会根据实际情况调整此时间值。）
  • 除以下字段的值外，所有信息保持不变：
    • merchantCustomsCode
    • merchantCustomsName
    • customsCode 
    • declarationAmount
    • suborderId
    • buyerCertificate.holderName.fullName 
    • buyerCertificate.certificateNo 
  • 如果 declarationAmount 已更改，新的申报金额不能超过原始总交易金额。

重传响应

以下列表描述了不同情况下的响应：

  • 如果重传条件不满足且没有任何参数值改变，返回幂等成功。
  • 如果重传条件不满足但有一个或多个参数值改变，将返回错误代码CONTEXT_INCONSISTENT或其他错误代码。
  • 如果重传条件满足且重传成功，返回值将与第一次成功传输时的返回值相同。 

结果码

结果码值结果码信息行动建议
SUCCESSS成功

海关申报成功。调用 报关结果查询 接口查询海关申报结果。

ACCESS_DENIEDF访问被拒绝。

请联系 Antom 技术支持获取详细原因。

INVALID_APIF调用的接口无效或未激活。

请联系 Antom 技术支持解决此问题。 

CLIENT_INVALIDF客户端 ID 无效。Antom 对客户端 ID 有限制。

检查客户端 ID 是否正确，或联系 Antom 技术支持获取详细原因。

DUPLICATED_DECLARATIONSF同一订单在同一海关只能申报一次。

检查 paymentId 是否已被用于海关报关。使用不同的支付 ID 来发起报关请求。

INVALID_CONTRACTF合同中的参数值与当前交易不符。

检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 Antom 技术支持排查问题。

INVALID_SIGNATUREF签名验证失败。请求签名所用的私钥与 Antom Dashboard 的公钥不匹配。

检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息可能有用：

KEY_NOT_FOUNDF找不到 Antom 或商户的私钥或公钥。

检查私钥或公钥是否存在。如果不存在，请在 Antom Dashboard 中上传私钥。

MEDIA_TYPE_NOT_ACCEPTABLEF服务器不支持客户端可接受的媒体类型。

请检查媒体类型是否正确，并使用 Antom 接受的媒体类型。

MERCHANT_NOT_REGISTEREDF商户未注册。

请使用注册接口注册商户。如果无法调用注册接口，请联系 Antom 技术支持。

METHOD_NOT_SUPPORTEDF服务器不支持请求的 HTTP 方法。仅支持 POST 方法。

确保 HTTP 方法为POST。

NO_INTERFACE_DEFF接口未定义。

请检查链接是否正确。请参考接口文档中的端点信息。 

ORDER_NOT_EXISTF订单不存在。

检查 paymentId 是否正确。如果正确，请联系 Antom 技术支持了解具体原因。 

ORDER_STATUS_INVALIDF订单状态无效。交易正在进行中或交易失败。

检查订单状态并采取相应操作。如果交易处理中，请等待。交易失败时，不要发起申报。否则，请联系 Antom 技术支持了解具体原因。

PARAM_ILLEGALF缺少必需参数，或存在非法参数。例如，非数字输入、无效日期，或参数长度和类型错误。

检查并验证当前接口所需的请求字段（包括头字段和正文字段）是否正确传递并有效。

PROCESS_FAILF发生了常见的业务失败。

获取 Antom 技术支持前请勿重试。

REPEAT_REQ_INCONSISTENTF金额或货币与先前请求不同。

使用唯一的 declarationRequestId 值重新发起海关申报。在重传场景中，确保满足重传条件部分的所有条件并进行重传。

RISK_REJECTF请求因风险控制被拒绝。

提示用户请求被拒绝，因为风险控制失败。

SYSTEM_ERRORF发生系统错误。

获取 Antom 技术支持前请勿重试。

TOTAL_DECLARATION_AMOUNT_EXCEEDF申报总额超过了支付金额。

确认申报总额是否超过支付金额。请创建一个金额小于或等于支付金额的新申报，或联系 Antom 技术支持。

USER_STATUS_ABNORMALF用户在支付方式端的状态异常。

如需了解具体原因，请联系 Antom 技术支持。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过限制。

再次调用接口以解决问题。如果问题仍未解决，请联系 Antom 技术支持。

UNKNOWN_EXCEPTIONU由于未知原因，接口调用失败。

再次调用接口以解决问题。如果问题未解决，请联系 Antom 技术支持。