多商业数据直连服务 V6.0

每一批数据，清楚地抵达。

DDI 接收端将商业系统提交的原始流向文件与交付元数据集中留存。管理员可以按批次查看、下载和清理，源文件内容不会被解析或改写。

RAW BYTE PRESERVATION·TRACEABLE DELIVERY

READYDDI 06

01 / CONTROL ROOM

交付批次与原始文件

管理员操作区

管理员令牌

令牌只在本次浏览器会话内使用，不会写入 URL 或页面存储。

尚未加载批次。

采集批次—

原始文件—

保全字节—

全选文件	批次标识	接收时间	商业	数据类型	原始文件	大小	操作
请输入管理员令牌后加载接收记录。

接口文档

这份规范面向需要接入 DDI 接收端的开发人员、实施人员和业务负责人。按照下面的请求、响应和验收清单实施，即可完成一次可追踪的原始文件交付。

查看完整 Markdown 合同 ↗

01接口地址与请求规则＋

发送端使用 POST /api/v1/ingest，请求地址为接收端的正式域名，例如 https://your-domain.example/api/v1/ingest。接口接收单个原始文件；一次业务采集产生多个文件时，为每个文件发送一次请求，并用相同的 X-DDI-Batch-ID 关联为同一批次。

请求体必须是文件的原始二进制字节流，不要转成 Base64、JSON、表单字段或重新编码。接收端会把请求体分块保存，确保下载时字节与发送时一致。

02请求头：生产接入要求＋

接收端为兼容历史客户端，会为缺少的部分元数据补默认值；但新接入必须按下表传递，才能获得准确的批次下载、检索和审计信息。

请求头要求说明

Content-Type应传文件 MIME 类型；未知时使用 application/octet-stream。

Content-Length应传原始请求体字节数，必须与实际发送长度一致。

X-DDI-Source应传发送端或适配器名称，用于后台筛选和排查。

X-DDI-Company应传商业全称；中文请使用 UTF-8 URL 编码。

X-DDI-Batch-ID应传本次采集的唯一标识；同批文件使用同一个值。

X-DDI-Filename应传原始文件名；中文请使用 UTF-8 URL 编码。

X-DDI-Data-Type应传例如 纯销、购进、配送、库存。

X-DDI-Sent-At可选发送端 ISO 8601 时间；当前用于发送端自身日志对照。

03成功响应与错误处理＋

成功时返回 201 Created 和 JSON：{"id":"服务器文件标识","receivedAt":"UTC 时间","byteSize":123,"chunkCount":1,"storage":"d1-chunks"}。发送端应记录 HTTP 状态、id、receivedAt、文件名、字节数和本地 SHA-256，作为后续核对凭据。

201文件已完整接收，可结束本次发送。

400请求体为空或参数不可用，修正后再发。

401仅管理员接口使用；发送端不应自行添加管理员令牌。

413请求体超过服务限制，应拆分文件或联系管理员。

502/503/超时网络或接收站暂时不可用，使用指数退避重试。

建议重试间隔为 5 秒、15 秒、45 秒，最多 3 次；每次重试必须继续使用相同的 X-DDI-Batch-ID 和文件名，并在本地记录失败原因。

04批次、下载与验收＋

批次是一次采集任务的逻辑容器，不是单个文件。后台列表按 X-DDI-Batch-ID 聚合文件；点击“下载本批次”会得到一个 ZIP，里面包含该批次的全部原始文件，文件名重复时系统会自动追加序号。ZIP 使用无压缩存储，便于保留原始字节。

接入验收至少包括：发送端收到 201；后台显示文件数量、文件名、大小和批次一致；下载单文件与下载批次 ZIP 均可打开；对任一文件计算 SHA-256 后，与发送端原文件一致。

05最小可运行示例＋

PowerShell：

$file = Get-Item '.\纯销_20260907.csv'
$batch = 'LUOYANG-20260907-001'
$headers = @{
  'Content-Type' = 'text/csv; charset=utf-8'
  'X-DDI-Source' = '洛阳宝神鹿大药房有限公司'
  'X-DDI-Company' = '洛阳宝神鹿大药房有限公司'
  'X-DDI-Batch-ID' = $batch
  'X-DDI-Filename' = [uri]::EscapeDataString($file.Name)
  'X-DDI-Source-Type' = '纯销'
}
Invoke-RestMethod -Method Post -Uri 'https://your-domain.example/api/v1/ingest' -Headers $headers -InFile $file.FullName -ContentType $headers['Content-Type']

curl：

curl --fail-with-body -X POST \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-DDI-Source: demo' \
  -H 'X-DDI-Company: demo-company' \
  -H 'X-DDI-Batch-ID: DEMO-20260907-001' \
  -H 'X-DDI-Filename: demo.bin' \
  --data-binary '@demo.bin' \
  https://your-domain.example/api/v1/ingest

每一批数据，清楚地抵达。

交付批次与原始文件

最近接收记录

接口文档