拍照接口文档

接口概述

在拍照机客户端本机触发一次拍摄。调用效果与拍摄页操作一致：先填入货号，再按左脚或右脚启动对应拍摄程序。

接口会等待这只脚的程序执行结束再返回。成功只表示程序已跑完，响应里不包含图片文件或 base64。照片仍按客户端原有流程落盘。

运行环境: 拍照机客户端（Electron）已启动。接口跑在客户端内部，调用方访问本机 localhost。

接口信息

基本信息

接口地址: http://localhost:3001/take_photo
请求方法: POST
Content-Type: application/json
超时建议: 客户端超时请大于单次拍摄时长。接口最长等待 10 分钟，超时返回失败。

接口路径

POST /take_photo

同一端口上的 POST /generate 仍是图片生成接口，互不影响。同一时间只能有一个拍照请求在执行。

请求参数

请求体结构

{
  "goods_art_no": "A596351",
  "foot": "left"
}

参数说明

字段	类型	必填	说明
goods_art_no	string	是	货号。也可用字段名 `货号` 或 `goodsArtNo`
foot	string	是	左右脚。也可用字段名 `左右脚`、`side`、`type`

foot 取值：

传值	实际动作
`left`、`l`、`0`、`左`、`左脚`	执行左脚程序
`right`、`r`、`1`、`右`、`右脚`	执行右脚程序

货号前后空格会被去掉。未识别的左右脚会直接失败。

响应格式

业务结果看 JSON 里的 code。code 不为 0 时，HTTP 状态码为 500，响应体仍是 JSON。

成功响应

HTTP 状态码: 200

{
  "code": 0,
  "msg": "货号:A596351,执行完成",
  "data": {
    "goods_art_no": "A596351",
    "foot": "left",
    "action": "执行左脚程序"
  }
}

字段	类型	说明
code	number	`0` 表示这只脚的拍摄程序已执行完成
msg	string	设备返回的完成说明
data.goods_art_no	string	本次货号
data.foot	string	`left` 或 `right`
data.action	string	`执行左脚程序` 或 `执行右脚程序`

失败响应

HTTP 状态码: 500

{
  "code": 1,
  "msg": "货号不能为空"
}

参数错误、设备忙、拍摄失败都是这个结构。已经开始拍摄后失败时，可能带上 data（货号、左右脚、动作名）。

常见 msg：

msg	说明
货号不能为空	未传货号
左右脚不能为空，请传 left/right 或左/右	未传或无法识别左右脚
拍摄程序正在运行，请稍候	已有拍摄在进行，不要并发调用
拍照接口仅在客户端内可用	客户端未启动，或不是在客户端里访问
设备服务未连接	8 秒内连不上本机拍摄服务
mcu设备未连接,请先连接设备	拍摄开始前 MCU 未连接
MCU 连接失败 / MCU串口未连接,请检查	拍摄过程中 MCU 断开，接口立即返回失败
请检查相机是否连接 / 相机未连接	拍摄过程中相机断开或相机软件未打开，接口立即返回失败
mcu设备未初始化	设备未完成初始化
当前有未完成的任务，请稍后再试	设备上还有未结束的动作
货号[xxx]已存在,请勿重复拍摄~	该货号已有拍摄记录，需先在客户端删除后再拍
当前没有可用配置	对应左脚或右脚没有可用拍摄配置
拍照超时	超过 10 分钟仍未结束

msg 还可能是设备返回的具体步骤失败原因，以实际返回为准。

其他错误

HTTP 状态码	说明	响应体
404	路径或方法不对	`Not Found`（纯文本）
413	请求体过大	`Payload Too Large`（纯文本）

调用示例

cURL

左脚：

curl -X POST http://localhost:3001/take_photo \
  -H "Content-Type: application/json" \
  -d "{\"goods_art_no\":\"A596351\",\"foot\":\"left\"}"

右脚（中文字段）：

curl -X POST http://localhost:3001/take_photo \
  -H "Content-Type: application/json" \
  -d "{\"货号\":\"A596351\",\"左右脚\":\"右\"}"

请把调用超时调到 10 分钟以上。curl 可加 --max-time 600。

Python

import requests

url = "http://localhost:3001/take_photo"
payload = {
    "goods_art_no": "A596351",
    "foot": "left",  # 右脚传 "right"
}

# 失败时 HTTP 状态码是 500，但仍返回 JSON，不要用 raise_for_status() 丢掉响应体
response = requests.post(url, json=payload, timeout=600)
result = response.json()

if result.get("code") == 0:
    print("拍摄完成:", result.get("msg"))
    print(result.get("data"))
else:
    print("拍摄失败:", result.get("msg"))

JavaScript

const response = await fetch("http://localhost:3001/take_photo", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    goods_art_no: "A596351",
    foot: "right",
  }),
});

const result = await response.json();
if (result.code === 0) {
  console.log("拍摄完成", result.data);
} else {
  console.error("拍摄失败", result.msg);
}

调用前检查

拍照机客户端已打开，本机可以访问 http://localhost:3001。
拍摄设备已连接并完成初始化。
左脚、右脚拍摄配置已在客户端配好。
该货号当前没有未删除的拍摄记录。重复货号会被拒绝。
上一次拍摄已经结束。接口不支持并发，进行中再次调用会返回「拍摄程序正在运行，请稍候」。
调用方与客户端在同一台电脑上。这是本机接口，不对外网开放。

拍摄页处于打开状态时，输入框会显示本次货号，界面进入与点击左右脚相同的拍摄状态。

注意事项

一次请求只拍一只脚。左脚、右脚需要分两次调用。
请求在程序结束前不会返回，请勿使用默认的短超时。
以响应 JSON 的 code 判断成败。code === 0 为成功，其余为失败。
接口不返回照片内容。拍完后的文件位置与客户端拍摄页一致。
中途在客户端点停止，接口会以失败返回，msg 为终止说明。

takePhoto.API.md 6.2 KB 文件历史 原始文件