钉钉消息发送API文档

概述

本文档描述了采购订单管理系统中钉钉消息发送功能的REST API接口。

基础信息

• 基础URL: http://localhost:9095
• API版本: v1.0
• 数据格式: JSON
• 字符编码: UTF-8

接口列表

1. 发送钉钉消息

接口信息

• 接口名称: 发送钉钉消息
• 请求方法: POST
• 接口路径: /api/dingtalk/sendMessage
• 功能描述: 根据检验单号发送不合格检验单的钉钉通知消息

请求参数

请求头:

Content-Type: application/json

请求体:

{
  "releaseNo": "IQC202501270001"
}

参数说明:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| releaseNo | String | 是 | 检验单号，用于查询对应的钉钉消息内容 |

响应结果

成功响应 (HTTP 200):

{
  "code": 200,
  "message": null,
  "successful": 0,
  "data": "接收成功"
}

失败响应 (HTTP 200):

{
  "code": 500,
  "message": "错误信息",
  "successful": 1,
  "data": "接收失败"
}

响应字段说明:
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功，500表示失败 |
| message | String | 错误信息，成功时为null |
| successful | Integer | 成功标识，0表示成功，1表示失败 |
| data | String | 响应数据，成功时为"接收成功"，失败时为"接收失败" |

错误码说明

使用示例

cURL示例:

curl -X POST http://localhost:9095/api/dingtalk/sendMessage \
  -H "Content-Type: application/json" \
  -d '{"releaseNo": "IQC202501270001"}'

JavaScript示例:

fetch('http://localhost:9095/api/dingtalk/sendMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    releaseNo: 'IQC202501270001'
  })
})
.then(response => response.json())
.then(data => {
  if (data.code === 200) {
    console.log('消息发送成功');
  } else {
    console.log('消息发送失败:', data.message);
  }
})
.catch(error => {
  console.error('请求失败:', error);
});

Java示例:

import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;

public class DingtalkApiClient {
    private static final String BASE_URL = "http://localhost:9095";
    private static final OkHttpClient client = new OkHttpClient();
    private static final ObjectMapper objectMapper = new ObjectMapper();

    public static void sendMessage(String releaseNo) throws Exception {
        // 构建请求体
        String requestBody = objectMapper.writeValueAsString(
                Map.of("releaseNo", releaseNo)
        );

        // 创建请求
        Request request = new Request.Builder()
                .url(BASE_URL + "/api/dingtalk/sendMessage")
                .post(RequestBody.create(
                        MediaType.parse("application/json"),
                        requestBody
                ))
                .build();

        // 发送请求
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            System.out.println("响应: " + responseBody);
        }
    }
}

常见错误及解决方案

1. 检验单号为空

   • 错误信息: "检验单号不能为空"
   • 解决方案: 确保传入的releaseNo参数不为null且不为空字符串

2. 数据不存在

   • 错误信息: "钉钉消息发送失败"
   • 解决方案: 确保检验单号在DINGTALK_MSG表中有对应的记录

3. 钉钉API调用失败

   • 错误信息: "钉钉消息发送失败"
   • 解决方案: 检查钉钉应用配置是否正确，确保有发送权限

4. 系统异常

   • 错误信息: 具体的异常信息
   • 解决方案: 检查系统日志，联系技术支持

注意事项

1. 数据准备: 确保检验单号在DINGTALK_MSG表中有对应的记录
2. 权限配置: 确保钉钉应用配置正确且有发送工作通知的权限
3. 调用频率: 建议接口调用频率不超过每分钟1次，避免触发钉钉API限制
4. 用户配置: 确保接收消息的用户在DINGTALK_INFO表中配置正确
5. 网络环境: 确保服务器能够正常访问钉钉开放API

消息格式

发送的钉钉消息格式如下：

供应商[xxx] 来料日期[yyyy-MM-dd] 项目[xxx] 料号[xxx]的不合格检验单被[xxx]审批为[xxx]，请查收!

数据库依赖

该接口依赖以下数据库表：

• DINGTALK_MSG: 存储钉钉消息内容
• DINGTALK_INFO: 存储钉钉用户信息

版本历史

联系支持

如有问题或建议，请联系技术支持团队。