开发文档

环境准备

在开始集成晶速医疗管理系统之前，请确保您的开发环境满足以下要求：

基本要求

  • 支持HTTPS协议的客户端
  • 能够处理JSON格式的数据
  • 有效的API密钥
  • 稳定的网络连接

获取API密钥

请联系我们的技术团队申请API密钥，您需要提供以下信息：

  • 公司名称
  • 联系人信息
  • 应用场景描述
  • 预计调用量

身份认证

所有API请求都需要在HTTP Header中包含API密钥进行身份验证：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

安全建议

  • 不要将API密钥硬编码在代码中
  • 使用环境变量或配置文件存储密钥
  • 定期更换API密钥
  • 监控API调用日志，发现异常及时处理

第一个请求

让我们通过一个简单的示例来了解如何调用API：

cURL示例

curl -X GET "https://api.tongsu.com/v1/customers?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Python示例

import requests

url = "https://api.nhip.com.cn/v1/customers"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
params = {
    "page": 1,
    "page_size": 10
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Java示例

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiClient {
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String BASE_URL = "https://api.jingsu.com/v1";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/customers?page=1&page_size=10"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
}

Java SDK

我们提供Java SDK，方便您快速集成：

Maven依赖

<dependency>
    <groupId>com.jingsu</groupId>
    <artifactId>jingsu-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

使用示例

import com.jingsu.JingsuClient;
import com.jingsu.model.Customer;

public class Example {
    public static void main(String[] args) {
        TongsuClient client = new TongsuClient("YOUR_API_KEY");
        
        Customer customer = new Customer();
        customer.setName("张三");
        customer.setPhone("13800138000");
        
        Customer result = client.createCustomer(customer);
        System.out.println("客户ID: " + result.getId());
    }
}

Python SDK

Python SDK提供简洁的API调用方式：

安装

pip install jingsu-sdk

使用示例

from jingsu import JingsuClient

client = JingsuClient(api_key="YOUR_API_KEY")

customer = client.create_customer(
    name="张三",
    phone="13800138000",
    gender=1
)

print(f"客户ID: {customer['id']}")

Node.js SDK

Node.js SDK支持Promise和async/await：

安装

npm install jingsu-sdk

使用示例

const JingsuClient = require('jingsu-sdk');

const client = new JingsuClient({
  apiKey: 'YOUR_API_KEY'
});

async function createCustomer() {
  try {
    const customer = await client.createCustomer({
      name: '张三',
      phone: '13800138000',
      gender: 1
    });
    
    console.log('客户ID:', customer.id);
  } catch (error) {
    console.error('创建失败:', error);
  }
}

createCustomer();

客户管理集成

客户管理是系统的核心功能，以下是集成要点：

客户数据结构

{
  "id": 1001,
  "name": "张三",
  "phone": "13800138000",
  "gender": 1,
  "birthday": "1990-01-01",
  "address": "北京市朝阳区",
  "tags": [
    {"id": 1, "name": "VIP客户"},
    {"id": 2, "name": "新客户"}
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

集成步骤

  1. 调用创建客户接口，传入基本信息
  2. 获取客户ID，用于后续操作
  3. 根据业务需求添加标签
  4. 定期同步客户信息更新

注意事项

  • 手机号必须唯一，重复手机号会返回错误
  • 客户信息更新时，只传入需要修改的字段
  • 删除客户为逻辑删除，数据仍保留在系统中

支付集成

系统支持多种支付方式，集成时需要注意：

支付流程

  1. 创建支付订单
  2. 获取支付参数
  3. 调用第三方支付SDK
  4. 处理支付回调
  5. 确认支付状态

美团团购支付

美团团购支付需要先核销券码，再进行支付：

1. 调用核销接口：POST /payments/meituan/verify
2. 获取核销结果和金额
3. 确认支付
4. 记录交易信息

支付回调处理

支付成功后，系统会发送Webhook通知：

{
  "event": "payment.success",
  "data": {
    "payment_id": 1001,
    "order_id": 2001,
    "amount": 100.00,
    "status": "paid",
    "paid_at": "2024-01-01T00:00:00Z"
  }
}

Webhook配置

Webhook用于接收系统事件通知，需要配置接收URL：

配置Webhook

请联系技术团队配置您的Webhook URL

事件类型

事件类型 说明
customer.created 客户创建成功
payment.success 支付成功
payment.failed 支付失败
appointment.created 预约创建成功
diagnosis.created 诊疗记录创建成功

验证签名

为确保数据安全，建议验证Webhook签名：

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, signature)

常见问题

Q: API调用频率限制是多少？

A: 标准版每分钟最多100次请求，企业版可提升至1000次/分钟。如需更高配额，请联系商务团队。

Q: 如何处理网络请求超时？

A: 建议设置合理的超时时间（如30秒），并实现重试机制。重试时请使用指数退避策略。

Q: 支持沙箱环境吗？

A: 支持，沙箱环境URL为 https://sandbox-api.jingsu.com/v1，使用测试API密钥。

Q: 如何获取技术支持？

A: 可以通过邮件 support@nhip.com.cn 联系技术团队，或查看故障排查文档。

Q: 数据安全如何保障？

A: 我们采用HTTPS加密传输，数据存储采用加密技术，并定期进行安全审计。

故障排查

常见错误及解决方案

错误 原因 解决方案
401 Unauthorized API密钥无效或过期 检查API密钥是否正确，或联系技术团队更新
400 Bad Request 请求参数错误 检查请求参数格式和必填字段
429 Too Many Requests 超过频率限制 降低请求频率或升级套餐
500 Internal Server Error 服务器错误 稍后重试，如持续出现请联系技术支持

调试技巧

  • 使用工具如Postman或curl测试API
  • 开启详细的日志记录
  • 检查网络连接和DNS解析
  • 验证请求和响应的JSON格式