中国立直麻将天梯榜 API

概述

Base URL 1：https://www.mj-rate.com

Base URL 2：https://www.mj-rate.cn

所有接口均需在请求体中携带 rate_id、sequence、params、timestamp、sign，并通过签名校验。

认证与签名

平台为每个门店分配 rate_id（8 位非零数字串）与 secret。 点击查看申请

签名步骤：

1. 将请求体除 sign 外的字段按键名升序排序；
2. 按 key=value&key=value&... 拼接，末尾追加 &secret=你的secret；
3. 对拼接串做 MD5 并转为大写，得到 sign。

timestamp 为秒级时间戳，与服务器时间差不得超过 ±300 秒。sequence 用于防重放，同一 rate_id + sequence 在 10 分钟内不可重复使用。

请求与响应

请求体统一结构：

{
  "rate_id": 12345678,
  "sequence": ABCD4321,
  "params": { 具体业务参数信息 },
  "timestamp": 1710000000,
  "sign": "XXXXXXXXXXXXXXXX"
}

响应统一结构：

{
  "code": 200,
  "msg": "success",
  "data": { "status": 1, "msg": "操作成功", ... }
}

code 为 200 表示请求被接受；data.status === 1 表示业务成功，0 表示业务失败。

错误码

雀士注册

{
  "rate_id": 12345678,
  "sequence": 87654321,
  "params": {
    "username": "Tom%20Cat",
    "phone": "13800138000",
    "avatar": "data:image/png;base64,iVBORw0KGgo...",
    "gender": 1
  },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": { "uuid": "01234567", "msg": "注册成功", "status": 1 }
}

雀士编辑

{
  "code": 200,
  "msg": "success",
  "data": { "msg": "修改成功", "status": 1 }
}

查询雀士分数与排名

{
  "rate_id": 12345678,
  "sequence": 87654324,
  "params": {
    "phone": "13800138000"
  },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": 1,
    "msg": "处理成功",
    "userInfo": {
      "uuid": "01234567",
      "username": "Tom%20Cat",
      "avatarUrl": "https://xxx/xxx.png"
    },
    "recordData": {
      "global": {
        "four": {
          "total": 0,
          "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0, "fly_total": 0,
          "one_score": 0, "two_score": 0, "three_score": 0, "four_score": 0, "fly_score": 0
        },
        "three": {
          "total": 0,
          "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0, "fly_total": 0,
          "one_score": 0, "two_score": 0, "three_score": 0, "four_score": 0, "fly_score": 0
        }
      },
      "seasons": [
        {
          "seasonId": 1,
          "seasonName": "S1",
          "four": {
            "total": 0,
            "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0, "fly_total": 0,
            "one_score": 0, "two_score": 0, "three_score": 0, "four_score": 0, "fly_score": 0,
            "seasonRank": {
              "id": 1,
              "seasonTotal": 0,
              "bestStartIndex": 0,
              "bestWin": 0,
              "bestSum": 0,
              "bestValid": 1,
              "bestGroup": [],
              "rank": 0
            }
          },
          "three": {
            "total": 0,
            "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0, "fly_total": 0,
            "one_score": 0, "two_score": 0, "three_score": 0, "four_score": 0, "fly_score": 0,
            "seasonRank": {
              "id": 2,
              "seasonTotal": 0,
              "bestStartIndex": 0,
              "bestWin": 0,
              "bestSum": 0,
              "bestValid": 1,
              "bestGroup": [],
              "rank": 0
            }
          },
          "stores": [
            {
              "storeId": 100,
              "storeName": "某某雀庄",
              "four": {
                "total": 0,
                "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0, "fly_total": 0,
                "one_score": 0, "two_score": 0, "three_score": 0, "four_score": 0, "fly_score": 0,
                "seasonRank": {
                  "id": 3,
                  "seasonTotal": 0,
                  "bestStartIndex": 0,
                  "bestWin": 0,
                  "bestSum": 0,
                  "bestValid": 1,
                  "bestGroup": [],
                  "rank": 0
                }
              },
              "three": {
                "total": 0,
                "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0, "fly_total": 0,
                "one_score": 0, "two_score": 0, "three_score": 0, "four_score": 0, "fly_score": 0,
                "seasonRank": {
                  "id": 4,
                  "seasonTotal": 0,
                  "bestStartIndex": 0,
                  "bestWin": 0,
                  "bestSum": 0,
                  "bestValid": 1,
                  "bestGroup": [],
                  "rank": 0
                }
              }
            }
          ]
        }
      ]
    }
  }
}

新增对局记录

{
  "rate_id": 12345678,
  "sequence": 87654323,
  "params": {
    "type": 0,
    "name1": "13800138000", "score1": 35000,
    "name2": "13900139000", "score2": 25000,
    "name3": "13700137000", "score3": 22000,
    "name4": "13600136000", "score4": 18000,
    "record_time": "2026-03-11 20:00:00"
  },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
            "msg": "添加成功",
            "status": 1,
            "record_id": 64位字符串，请自行保存记录，后续可用此 ID 修改和删除记录
            "errCode": 200, // 错误码，见下表
           }
}

修改对局记录

{
  "code": 200,
  "msg": "success",
  "data": { "msg": "对局记录修改成功", "status": 1, "errCode": 200}
}

删除对局记录

{
  "code": 200,
  "msg": "success",
  "data": { "msg": "对局记录删除成功", "status": 1 }
}

查询对局记录

{
  "rate_id": 12345678,
  "sequence": 87654323,
  "params": {
    "type": 0,
    "phone": "13800138000",
    "start_time": 1710000000,
    "end_time": "2026-03-21 20:00:00",
    "page": 1,
    "page_size": 100
  },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
            "msg": "查询成功",
            "status": 1,
            "total": 888, // 符合查询条件的总记录数据
            "recordList": {
                    {
                      "id": 64位字符串,
                      "storeName": 雀庄名称, "typeName"： "天梯四麻" 或 "天梯三麻",
                      "name1"： 一位雀士昵称, "score1"： 一位雀士分数,
                      "name2"： 二位雀士昵称, "score2"： 二位雀士分数,
                      "name3"： 三位雀士昵称, "score3"： 三位雀士分数,
                      "name4"： 四位雀士昵称 三麻时为空, "score4"： 四位雀士分数 三麻时为空,
                      "recordTime"： 对局时间, "createTime"： 记录时间
                    },
                    {
                      "id": 64位字符串,
                      "storeName": 雀庄名称, "typeName"： "天梯四麻" 或 "天梯三麻",
                      "name1"： 一位雀士昵称, "score1"： 一位雀士分数,
                      "name2"： 二位雀士昵称, "score2"： 二位雀士分数,
                      "name3"： 三位雀士昵称, "score3"： 三位雀士分数,
                      "name4"： 四位雀士昵称 三麻时为空, "score4"： 四位雀士分数 三麻时为空,
                      "recordTime"： 对局时间, "createTime"： 记录时间
                    },...
                },
           }
}

记录操作执行错误码

查询用户赛季排名（该部分功能尚未完善）

{
  "code": 200,
  "msg": "success",
  "data": {
    "username": "张三",
    "avatarUrl": "",
    "status": 1,
    "seasonId": 1,
    "seasonName": "S1",
    "seasonTotal": 12,
    "bestStartIndex": 2,
    "bestSum": 45.5,
    "bestGroup": [{ "score": 35000, "rank": 0, "point": 40.0 }],
    "createTime": "2026-03-01 00:00:00",
    "msg": "查询成功",
    "status": 1
  }
}

下载用户赛季证书

{
  "rate_id": 12345678,
  "sequence": "ABCD1234",
  "params": {
    "season_id": 2,
    "phone": "13800138000",
    "type": 0
  },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "fail",
  "data": {
    "status": 0,
    "msg": "该雀士暂无对应模式的全国榜成绩，无法生成证书"
  }
}

获取用户赛季证书图片地址

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": 1,
    "msg": "赛季证书已存在",
    "imageUrl": "www.mj-rate.com/static/resources/season/certificate/s2/gradeId_5_userId_12345.jpg"
  }
}

生涯模块

{
  "rate_id": 12345678,
  "sequence": "ABCD1234",
  "params": {},
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": 1,
    "msg": "查询成功",
    "data": {
      "title": "规则说明标题",
      "lastUpdateTime": "2026-05-01",
      "ruleList": [ { "name": "段位名", "tarot": "塔罗", "floors": 0, "star": 0, "rank": [], "win": 0, "exempt": "降段说明" } ],
      "activityList": [],
      "tips_win": "连胜奖励说明",
      "tips_exempt": "降段豁免说明",
      "tips_activity": "活跃度说明"
    }
  }
}

{
  "rate_id": 12345678,
  "sequence": "ABCD1235",
  "params": { "phone": "13800138000" },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "rate_id": 12345678,
  "sequence": "ABCD1236",
  "params": { "phone": "13800138000" },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": 1,
    "msg": "查询成功",
    "data": {
      "careerAnalysis": {
        "gradeId": 0, "star": 0, "win": 0,
        "record_total": 0, "season_record_total": 0,
        "one_total": 0, "two_total": 0, "three_total": 0, "four_total": 0,
        "exempt": 0, "globalRankText": 0,
        "starLog": [], "gradeInfo": { }
      },
      "activityList": []
    }
  }
}

{
  "rate_id": 12345678,
  "sequence": "ABCD1237",
  "params": { "page": 1, "page_size": 20 },
  "timestamp": 1710000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": 1,
    "msg": "查询成功",
    "data": {
      "careerList": [
        {
          "userId": 1, "gradeId": 0, "star": 0,
          "uuid": "01234567", "username": "昵称", "avatarUrl": "https://...",
          "storeId": 0, "rank": 1, "gradeTxt": "段位·塔罗", "storeName": "雀庄名", "gradeImageUrl": "https://..."
        }
      ],
      "count": 100
    }
  }
}

门店接口

{
  "rate_id": "12345678",
  "sequence": "87654321",
  "params": {
    "licenseType": 1,
    "companyName": "示例科技有限公司",
    "companyCode": "91310000XXXXXXXXXX",
    "idCardName": "张三",
    "companyPhone": "13800138000",
    "name": "示例雀庄（上海店）",
    "phone": "02112345678",
    "ip": "1.2.3.4",
    "logo": "data:image/png;base64,...."
  },
  "timestamp": 1700000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "rate_id": "23456789",
    "secret": "YOUR_RATE_SECRET",
    "msg": "注册成功",
    "status": 1
  }
}

{
  "rate_id": "23456789",
  "sequence": "11223344",
  "params": {
    "name": "示例雀庄（上海店）- 新名称",
    "phone": "02100001111",
    "address": "上海市浦东新区XX路XX号",
    "longitude": "121.500000",
    "latitude": "31.200000"
  },
  "timestamp": 1700000000,
  "sign": "YOUR_SIGN"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "msg": "编辑成功",
    "status": 1
  }
}

服务器消息推送

当门店在平台侧已配置推送接收地址时，系统在特定业务事件触发后会向该地址异步发起 POST 请求，请求体为 Content-Type: application/json; charset=utf-8 的 JSON 数据。推送任务经队列投递，与开放 API 的签名校验无关。

成功响应约定

接口应返回 HTTP 状态码 2xx，且响应正文经去除首尾空白后必须为字符串 ok（区分大小写）。否则视为失败；平台会间隔约 10 秒重试，同一任务最多尝试 3 次。单次请求超时约 30 秒。

请求体结构

平台 POST 的 JSON 结构如下。其中 data 为业务负载：除各推送类型自有字段外，平台会合并 uuid（雀士编号）、phone（手机号）、storeId（门店对外 rate_id）等公共字段。

{
  "type": "season_enter_top100",
  "token": "与门店绑定的 serverToken",
  "data": {
    "uuid": "01234567",
    "phone": "13800138000",
    "storeId": 12345678,
    ... 各 type 对应的业务字段 ...
  }
}

推送类型（type）与触发场景

以下为当前平台会发起的推送类型；具体 data 内业务字段可能随版本扩展，接入时请做好未知字段兼容。

签名伪代码

客户端需与服务端保持一致的 params 序列化与字段排序。

input = { rate_id, sequence, params(object), timestamp }
secret = 门店 secret

params_str = JSON.stringify(sortKeysRecursively(params))

data = {
  "params": params_str,
  "rate_id": rate_id,
  "sequence": sequence,
  "timestamp": timestamp
}
sort keys of data asc
signStr = join(key=value, "&") + "&secret=" + secret
sign = upper(MD5(signStr))

PHP 调用示例（cURL）

<?php

class MjRateApiClient
{
    const RATE_ID = 'YOUR_RATE_ID';
    const RATE_SECRET = 'YOUR_RATE_SECRET';
    const RATE_URL = 'https://www.mj-rate.com/api/';

    public static function send(string $path, array $bizParams): array
    {
        $body = [
            'rate_id' => self::RATE_ID,
            'sequence' => (string)random_int(10000000, 99999999),
            'params' => $bizParams,
            'timestamp' => time(),
        ];
        $body['sign'] = self::buildSign($body);

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, self::RATE_URL . $path);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json; charset=utf-8']);
        $res = curl_exec($ch);
        curl_close($ch);

        $json = json_decode((string)$res, true);
        return is_array($json) ? $json : ['code' => 0, 'message' => '解析失败', 'data' => $res];
    }

    private static function buildSign(array $body): string
    {
        $sign = strtoupper((string)($body['sign'] ?? ''));
        unset($body['sign']);

        $data = [];
        foreach ($body as $k => $v) {
            $data[$k] = is_array($v)
                ? json_encode(self::sortKeysRecursive($v), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
                : (string)$v;
        }
        ksort($data, SORT_STRING);

        $parts = [];
        foreach ($data as $k => $v) {
            $parts[] = $k . '=' . $v;
        }
        $parts[] = 'secret=' . self::RATE_SECRET;
        return strtoupper(md5(implode('&', $parts)));
    }

    private static function sortKeysRecursive(array $arr): array
    {
        ksort($arr, SORT_STRING);
        foreach ($arr as $k => $v) {
            if (is_array($v)) $arr[$k] = self::sortKeysRecursive($v);
        }
        return $arr;
    }
}

// 示例：注册雀士
$resp = MjRateApiClient::send('user/regedit', [
    'username' => rawurlencode('Tom Cat'),
    'phone' => '13800138000',
    'gender' => 1,
    // 'avatar' => 'data:image/png;base64,...' // ≤200KB（解码后）
]);
var_dump($resp);

Java 调用示例（OkHttp）

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.*;

public class MjRateApiClient {
    static final String RATE_ID = "YOUR_RATE_ID";
    static final String RATE_SECRET = "YOUR_RATE_SECRET";
    static final String RATE_URL = "https://www.mj-rate.com/api/";

    static final ObjectMapper MAPPER = new ObjectMapper();
    static final OkHttpClient HTTP = new OkHttpClient.Builder()
            .callTimeout(java.time.Duration.ofSeconds(30))
            .build();

    public static Map<String, Object> send(String path, Map<String, Object> bizParams) throws Exception {
        Map<String, Object> body = new LinkedHashMap<>();
        body.put("rate_id", RATE_ID);
        body.put("sequence", String.valueOf(10000000 + new Random().nextInt(90000000)));
        body.put("params", bizParams);
        body.put("timestamp", System.currentTimeMillis() / 1000);
        body.put("sign", buildSign(body));

        String json = MAPPER.writeValueAsString(body);
        Request req = new Request.Builder()
                .url(RATE_URL + path)
                .post(RequestBody.create(json, MediaType.parse("application/json; charset=utf-8")))
                .build();
        try (Response resp = HTTP.newCall(req).execute()) {
            String res = resp.body() != null ? resp.body().string() : "";
            return MAPPER.readValue(res, new TypeReference<Map<String, Object>>() {});
        }
    }

    private static String buildSign(Map<String, Object> body) throws Exception {
        Map<String, String> data = new TreeMap<>();
        for (Map.Entry<String, Object> e : body.entrySet()) {
            if ("sign".equals(e.getKey())) continue;
            Object v = e.getValue();
            if (v instanceof Map || v instanceof List) {
                data.put(e.getKey(), MAPPER.writeValueAsString(sortKeysRecursive(v)));
            } else {
                data.put(e.getKey(), String.valueOf(v));
            }
        }
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> e : data.entrySet()) {
            if (sb.length() > 0) sb.append('&');
            sb.append(e.getKey()).append('=').append(e.getValue());
        }
        sb.append("&secret=").append(RATE_SECRET);
        return md5Upper(sb.toString());
    }

    private static Object sortKeysRecursive(Object obj) {
        if (obj instanceof Map) {
            Map<String, Object> m = new TreeMap<>();
            ((Map<?, ?>) obj).forEach((k, v) -> m.put(String.valueOf(k), sortKeysRecursive(v)));
            return m;
        }
        if (obj instanceof List) {
            List<Object> out = new ArrayList<>();
            for (Object v : (List<?>) obj) out.add(sortKeysRecursive(v));
            return out;
        }
        return obj;
    }

    private static String md5Upper(String s) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] dig = md.digest(s.getBytes(StandardCharsets.UTF_8));
        StringBuilder hex = new StringBuilder();
        for (byte b : dig) hex.append(String.format("%02x", b));
        return hex.toString().toUpperCase(Locale.ROOT);
    }

    public static void main(String[] args) throws Exception {
        Map<String, Object> params = new LinkedHashMap<>();
        params.put("username", java.net.URLEncoder.encode("Tom Cat", "UTF-8"));
        params.put("phone", "13800138000");
        params.put("gender", 1);
        Map<String, Object> resp = send("user/regedit", params);
        System.out.println(resp);
    }
}

Node.js 调用示例（fetch）

import crypto from 'node:crypto';

const RATE_ID = 'YOUR_RATE_ID';
const RATE_SECRET = 'YOUR_RATE_SECRET';
const RATE_URL = 'https://www.mj-rate.com/api/';

function sortKeysRecursive(obj) {
  if (Array.isArray(obj)) return obj.map(sortKeysRecursive);
  if (obj && typeof obj === 'object') {
    const out = {};
    Object.keys(obj).sort().forEach((k) => { out[k] = sortKeysRecursive(obj[k]); });
    return out;
  }
  return obj;
}

function buildSign(body) {
  const copy = { ...body };
  delete copy.sign;
  const data = {};
  Object.keys(copy).forEach((k) => {
    const v = copy[k];
    data[k] = (v && typeof v === 'object') ? JSON.stringify(sortKeysRecursive(v)) : String(v);
  });
  const keys = Object.keys(data).sort();
  const parts = keys.map((k) => `${k}=${data[k]}`);
  parts.push(`secret=${RATE_SECRET}`);
  return crypto.createHash('md5').update(parts.join('&'), 'utf8').digest('hex').toUpperCase();
}

async function send(path, bizParams) {
  const body = {
    rate_id: RATE_ID,
    sequence: String(Math.floor(10000000 + Math.random() * 90000000)),
    params: bizParams,
    timestamp: Math.floor(Date.now() / 1000),
  };
  body.sign = buildSign(body);

  const res = await fetch(RATE_URL + path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
    body: JSON.stringify(body),
  });
  return await res.json();
}

// 示例：注册雀士
const resp = await send('user/regedit', {
  username: encodeURIComponent('Tom Cat'),
  phone: '13800138000',
  gender: 1,
  // avatar: 'data:image/png;base64,...'
});
console.log(resp);

Python 调用示例（requests）

import hashlib
import json
import random
import time
import urllib.parse

import requests

RATE_ID = "YOUR_RATE_ID"
RATE_SECRET = "YOUR_RATE_SECRET"
RATE_URL = "https://www.mj-rate.com/api/"

def sort_keys_recursive(obj):
    if isinstance(obj, list):
        return [sort_keys_recursive(v) for v in obj]
    if isinstance(obj, dict):
        return {k: sort_keys_recursive(obj[k]) for k in sorted(obj.keys())}
    return obj

def build_sign(body: dict) -> str:
    data = {}
    for k, v in body.items():
        if k == "sign":
            continue
        if isinstance(v, (dict, list)):
            data[k] = json.dumps(sort_keys_recursive(v), ensure_ascii=False, separators=(",", ":"))
        else:
            data[k] = str(v)
    parts = [f"{k}={data[k]}" for k in sorted(data.keys())]
    parts.append(f"secret={RATE_SECRET}")
    raw = "&".join(parts)
    return hashlib.md5(raw.encode("utf-8")).hexdigest().upper()

def send(path: str, biz_params: dict) -> dict:
    body = {
        "rate_id": RATE_ID,
        "sequence": str(random.randint(10000000, 99999999)),
        "params": biz_params,
        "timestamp": int(time.time()),
    }
    body["sign"] = build_sign(body)
    resp = requests.post(RATE_URL + path, json=body, timeout=30)
    return resp.json()

# 示例：注册雀士
resp = send("user/regedit", {
    "username": urllib.parse.quote("Tom Cat"),
    "phone": "13800138000",
    "gender": 1,
    # "avatar": "data:image/png;base64,..."
})
print(resp)

技术支持与联系方式

如需对接支持、接口开通、问题排查，请通过以下方式联系我们：