PartsInquiry/backend/txm/doc/API.md

条形码识别 API 对接文档

本文档说明与 Java 后端对接的上传识别接口，返回 EAN‑13 结果；若无法识别返回明确错误提示。

基本信息

• 接口地址：/api/barcode/scan
• 请求方式：POST multipart/form-data
• 参数：
  • file：图片文件（二进制）。
• 成功响应（HTTP 200）：

  { "success": true, "barcodeType": "EAN13", "barcode": "6901234567892" }
  

• 失败响应（HTTP 400）：

  { "success": false, "message": "无法识别，请重新上传" }
  

请求示例（PowerShell）

Invoke-RestMethod -Uri http://127.0.0.1:8000/api/barcode/scan -Method Post -Form @{ file = Get-Item .\sample.jpg }

请求示例（curl）

curl -F "file=@sample.jpg" http://127.0.0.1:8000/api/barcode/scan

Java 示例（Spring WebClient）

WebClient client = WebClient.create("http://127.0.0.1:8000");
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("file", new FileSystemResource(new File("sample.jpg")));

Map res = client.post()
    .uri("/api/barcode/scan")
    .contentType(MediaType.MULTIPART_FORM_DATA)
    .body(BodyInserters.fromMultipartData(body))
    .retrieve()
    .onStatus(s -> s.value() == 400, r -> r.bodyToMono(String.class).map(RuntimeException::new))
    .bodyToMono(Map.class)
    .block();

System.out.println(res);

Java 示例（Spring RestTemplate）

RestTemplate rest = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("file", new FileSystemResource("sample.jpg"));
HttpEntity<MultiValueMap<String, Object>> req = new HttpEntity<>(body, headers);

ResponseEntity<String> resp = rest.postForEntity("http://127.0.0.1:8000/api/barcode/scan", req, String.class);
System.out.println(resp.getStatusCode());
System.out.println(resp.getBody());

返回字段说明

• success：是否识别成功。
• barcodeType：条码类型（当前为 EAN13）。
• barcode：条码数字串。
• message：失败时的人类可读说明。

错误码

• 400：文件为空、图片解析失败、或未识别；返回 { success:false, message:"无法识别，请重新上传" }。
• 413：文件过大（受 config/config.yaml 中 app.server.max_upload_mb 限制）。