将外部业务集成至财税中台

通过标准化的 Webhook 机制，您的业务系统（如 shipchain.top, 56ata.com 等货代 ERP/跨境商城）可在交易节点触发后，自动将资金流、单据流抛送至 ShipChain Tax 财税中台，实现自动记账、智能核销与关税推演。

鉴权机制 (Authentication)

为保障业财数据的绝对安全，所有的 Webhook 调用请求必须在 HTTP Header 中携带高强度校验密钥。若密钥缺失或错误，中台网关将直接阻断请求并返回 403 Forbidden，同时记录在 SRE 安全审计日志中。

Header Name: X-Internal-Secret

Secret Key: 请向财务系统 SRE 工程师或在企业账套设置中获取正式环境的专属通信密钥。

订单支付/成交信号推送

当业务系统中的一笔订单客户完成付款时调用。财税中台接收后，将自动生成“应收账款核销”的草稿凭证，并进入银行流水待匹配池。

POST https://tax.shipchain.top/api/webhook/shipchain_order_paid

请求体参数 (Body Parameters - JSON)

参数名	类型	必填	描述
`order_id`	string	Required	业务系统的唯一订单号 / 提单号 (Order SN / MBL)
`amount`	float	Required	订单支付总金额 (保留两位小数)
`customer_name`	string	Required	客户或供应商的户名（需尽量与企业公户打款的真实抬头一致，以便 AI 自动对账）
`currency`	string	Optional	结算币种代码 (如 USD, EUR)。默认缺省值为 `CNY`

请求示例 (Request)

curl -X POST https://tax.shipchain.top/api/webhook/shipchain_order_paid \
              -H "Content-Type: application/json" \
              -H "X-Internal-Secret: SHIPCHAIN_WEBHOOK_SECRET_2026" \
              -d '{
              "order_id": "ORD-202605-001",
              "amount": 12500.00,
              "customer_name": "义乌市星辰跨境贸易"
              }'

<?php
              $curl = curl_init();
              curl_setopt_array($curl, [
              CURLOPT_URL => "https://tax.shipchain.top/api/webhook/shipchain_order_paid",
              CURLOPT_CUSTOMREQUEST => "POST",
              CURLOPT_POSTFIELDS => json_encode([
              "order_id" => "ORD-202605-001",
              "amount" => 12500.00,
              "customer_name" => "义乌市星辰跨境贸易"
              ]),
              CURLOPT_HTTPHEADER => [
              "Content-Type: application/json",
              "X-Internal-Secret: SHIPCHAIN_WEBHOOK_SECRET_2026"
              ],
              ]);
              $response = curl_exec($curl);
              curl_close($curl);
              echo $response;

import requests
              import json

              url = "https://tax.shipchain.top/api/webhook/shipchain_order_paid"
              headers = {
              "Content-Type": "application/json",
              "X-Internal-Secret": "SHIPCHAIN_WEBHOOK_SECRET_2026"
              }
              payload = {
              "order_id": "ORD-202605-001",
              "amount": 12500.00,
              "customer_name": "义乌市星辰跨境贸易"
              }

              response = requests.post(url, headers=headers, data=json.dumps(payload))
              print(response.text)

响应示例 (Response)

{
          "status": "success",
          "msg": "订单 ORD-202605-001 财务接收成功",
          "auto_ledger": {
          "status": "DRAFT_CREATED",
          "debit": 12500.00,
          "credit_income": 11792.45,
          "credit_tax": 707.55
          },
          "timestamp": 1718041530
          }

OpenAPI 文档