Third-party sync API (WealthTree)

This document describes the HTTP requests the WealthTree iOS app sends to a user-provided third-party sync server, so anyone can implement a compatible endpoint.

Base URL: your server endpoint (example: https://api.xscsd.cn/v1/cloudkit/index).

Auth

If the user enters an API Key in the app, it is sent as a header:

X-API-Key: {apiKey}

If left blank, the header is omitted.

The app also sends:

• Content-Type: application/json (upload only)
• Accept: application/json

Endpoint

WealthTree uses a single endpoint for upload and download.

POST {base}?sync_type={upload|download}&user_id={userId}&app_name=WealthTree

Notes:

• sync_type is required.
• For download, user_id and app_name must be present (query params).
• For upload, the backend validates required fields from the JSON body (see below). Including user_id/app_name in the query is harmless.

Data model

The app uploads/downloads a full snapshot object called WealthData.

Upload

Request:

POST {base}?sync_type=upload&user_id={userId}&app_name=WealthTree

JSON body (required fields):

{
  "user_id": "string",
  "app_name": "WealthTree",
  "name": "wealthtree-backup",
  "remark": "iOS backup from WealthTree",
  "data": "{...json string...}" 
}

data can be either:

• a JSON object (WealthData), OR
• a JSON string containing the WealthData JSON.

The current iOS implementation sends data as a JSON string for compatibility.

Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 123,
    "user_id": "...",
    "app_name": "WealthTree",
    "name": "wealthtree-backup",
    "remark": "...",
    "createtime": "YYYY-MM-DD HH:mm:ss",
    "updatetime": "YYYY-MM-DD HH:mm:ss"
  }
}

Note:

• Upload success response returns metadata only (it does not echo back the snapshot data).

Error (400 example):

{ "detail": "缺少必填字段" }

Download

Request:

POST {base}?sync_type=download&user_id={userId}&app_name=WealthTree

Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 123,
    "user_id": "...",
    "app_name": "WealthTree",
    "name": "wealthtree-backup",
    "remark": "...",
    "data": { /* WealthData snapshot object */ },
    "createtime": "YYYY-MM-DD HH:mm:ss",
    "updatetime": "YYYY-MM-DD HH:mm:ss"
  }
}

The iOS app extracts the snapshot from data.data.

Compatibility note:

• Server may return data.data as a JSON object (current FastAPI behavior), or as a JSON string. The iOS app accepts both.

Errors

This FastAPI backend returns errors as:

{ "detail": "..." }

Common cases:

• HTTP 400: { "detail": "sync_type 参数错误" }
• HTTP 400 (download): { "detail": "缺少 user_id 或 app_name" }
• HTTP 400 (upload): { "detail": "缺少必填字段" }
• HTTP 400 (upload): { "detail": "data 不能为空" }
• HTTP 400 (upload): { "detail": "data 需为合法 JSON 字符串或对象" }
• HTTP 404 (download): { "detail": "未找到记录" }

Quick test (curl)

Upload:
curl -i -X POST '{base}?sync_type=upload&user_id={userId}&app_name=WealthTree' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'X-API-Key: {apiKey}' -d '{"user_id":"{userId}","app_name":"WealthTree","name":"wealthtree-backup","remark":"iOS backup from WealthTree","data":"{}"}'

Download:
curl -i -X POST '{base}?sync_type=download&user_id={userId}&app_name=WealthTree' -H 'Accept: application/json' -H 'X-API-Key: {apiKey}'