erpnew/docs/api_v2_shipment_delivery_photo_api.md

API v2 Shipment Delivery Photo 文档

本文档说明司机按出货单上传送达照片的 API。

数据结构

{
  "id": 1,
  "shipment_id": 100,
  "delivery_id": 20,
  "photo": "https://image.yuwen.cloud/media/shipment_delivery_photos/demo.jpg",
  "remark": "已送达并签收",
  "created_by": 8,
  "created_at": "2026-04-28T20:00:00+08:00",
  "updated_at": "2026-04-28T20:00:00+08:00"
}

说明：

• photo 使用项目现有七牛存储。
• shipment_id 与 delivery_id 都是必填。
• 同一个 shipment_id + delivery_id 组合允许多次写入，不做唯一性限制。
• 后端会校验 shipment.delivery_id == delivery_id，不一致时拒绝写入。

列表查询

• URL: /api/v2/shipment-delivery-photos/
• Method: GET

查询参数：

参数	类型	说明
shipment_id	int	可选，按出货单筛选
delivery_id	int	可选，按送货单筛选

说明：

• 支持只传 shipment_id
• 支持只传 delivery_id
• 支持同时传两者，按 AND 过滤

成功响应：ShipmentDeliveryPhoto[]

创建送达照片

• URL: /api/v2/shipment-delivery-photos/
• Method: POST
• Content-Type: multipart/form-data

请求参数：

参数	类型	必填	说明
shipment	int	是	出货单 ID
delivery	int	是	送货单 ID
photo	file	是	送达照片
remark	string	否	备注

说明：

• created_by 由当前登录用户自动写入
• shipment 与 delivery 必须属于当前商户
• delivery 必须与 shipment.delivery_id 一致

成功响应：201 Created，返回 ShipmentDeliveryPhoto

详情查询

• URL: /api/v2/shipment-delivery-photos/<photo_id>/
• Method: GET

成功响应：ShipmentDeliveryPhoto

更新送达照片

• URL: /api/v2/shipment-delivery-photos/<photo_id>/
• Method: PATCH / PUT
• Content-Type: multipart/form-data

允许更新：

参数	类型	说明
shipment	int	出货单 ID
delivery	int	送货单 ID
photo	file	照片
remark	string	备注

说明：

• 更新时仍会执行 shipment.delivery_id == delivery_id 一致性校验
• PATCH 支持部分更新
• PUT 需要传完整字段

删除送达照片

• URL: /api/v2/shipment-delivery-photos/<photo_id>/
• Method: DELETE

成功响应：204 No Content