OpenAPI文档中心 3.0

https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6
Admin
This document provides technical specifications and API interfaces for a shared economy platform's...
Tokens:23,905
Snippets:69
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### 5.2.7 Get Soho Limit List

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Retrieves the monthly and yearly amounts for all collection entities for a given ID card number.

```APIDOC
## POST /openapi/v1/soho/getSohoLimitList

### Description
Retrieves the monthly and yearly amounts for all collection entities for a given ID card number.

### Method
POST

### Endpoint
/openapi/v1/soho/getSohoLimitList

### Parameters
#### Query Parameters
- **idCard** (an) - Required - The ID card number of the worker.

### Request Body
```json
{
  "idCard": "an"
}
```

### Response
#### Success Response (200)
- **monthMoney** (ans) - Monthly amount.
- **yearMoney** (ans) - Yearly amount.

#### Response Example
```json
{
  "data": [
    {
      "levyId": "n",
      "levyName": "ans",
      "monthMoney": "ans",
      "yearMoney": "ans"
    }
  ]
}
```
```

--------------------------------

### POST /openapi/v1/payment/queryPreTaxBudgetList

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Calculates pre-tax budget for payments, considering personal income tax and VAT.

```APIDOC
## POST /openapi/v1/payment/queryPreTaxBudgetList

### Description
Calculates the pre-tax budget for payments, considering personal income tax and value-added tax based on provided formulas and thresholds.

### Method
POST

### Endpoint
`/openapi/v1/payment/queryPreTaxBudgetList`

### Parameters
#### Request Body
- **isPreTaxVatTax** (string) - Optional - Indicates if the budget amount includes VAT (0: Yes, omit if not needed).
- **taxBoList** (List<Object>) - Required - A list of tax calculation data objects.
  
  #### taxBoList items:
  - **amt** (BigDecimal) - Required - Payment amount (in Yuan).
  - **idCard** (String) - Required - ID card number.
  - **payeeName** (String) - Optional - Payee name.

### Request Example
```json
{
  "isPreTaxVatTax": "0",
  "taxBoList": [
    {
      "amt": 10000.00,
      "idCard": "123456789012345678",
      "payeeName": "Jane Doe"
    }
  ]
}
```

### Response
#### Success Response (200)
- **amt** (BigDecimal) - Payment amount.
- **idCard** (String) - ID card number.
- **payeeName** (String) - Payee name.
- **payeeAcc** (String) - Payee account number.
- **afterTaxAmt** (BigDecimal) - Amount after tax (in Yuan).
- **indTaxAmt** (BigDecimal) - Personal income tax amount (in Yuan).
- **vatTaxAmt** (BigDecimal) - Value-added tax amount (in Yuan).
- **taxRatePercent** (String) - Personal income tax rate (%).
- **quickDeduction** (BigDecimal) - Quick deduction amount.
- **yearSettleAmt** (BigDecimal) - Year-to-date settlement amount.
- **monthSettleAmt** (BigDecimal) - Month-to-date settlement amount.
- **payableIndTaxAmt** (BigDecimal) - Year-to-date payable personal income tax.
- **payableVatTaxAmt** (BigDecimal) - Month-to-date payable VAT.
- **paidIndTaxAmt** (BigDecimal) - Year-to-date paid personal income tax.
- **paidVatTaxAmt** (BigDecimal) - Month-to-date paid VAT.

#### Response Example
```json
{
  "amt": 10000.00,
  "idCard": "123456789012345678",
  "payeeName": "Jane Doe",
  "payeeAcc": "621001234567890123",
  "afterTaxAmt": 8500.00,
  "indTaxAmt": 1000.00,
  "vatTaxAmt": 500.00,
  "taxRatePercent": "10%",
  "quickDeduction": 100.00,
  "yearSettleAmt": 100000.00,
  "monthSettleAmt": 5000.00,
  "payableIndTaxAmt": 12000.00,
  "payableVatTaxAmt": 600.00,
  "paidIndTaxAmt": 10000.00,
  "paidVatTaxAmt": 500.00
}
```
```

--------------------------------

### POST /openapi/v1/payment/queryAfterTaxBudgetList

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Calculates after-tax budget for payments, considering personal income tax and VAT.

```APIDOC
## POST /openapi/v1/payment/queryAfterTaxBudgetList

### Description
Calculates the after-tax budget for payments, considering personal income tax and value-added tax based on provided formulas and thresholds.

### Method
POST

### Endpoint
`/openapi/v1/payment/queryAfterTaxBudgetList`

### Parameters
#### Request Body
- **isPreTaxVatTax** (string) - Optional - Indicates if the budget amount includes VAT (0: Yes, omit if not needed).
- **taxBoList** (List<Object>) - Required - A list of tax calculation data objects.
  
  #### taxBoList items:
  - **amt** (BigDecimal) - Required - Payment amount (in Yuan).
  - **idCard** (String) - Required - ID card number.
  - **payeeName** (String) - Optional - Payee name.

### Request Example
```json
{
  "isPreTaxVatTax": "0",
  "taxBoList": [
    {
      "amt": 10000.00,
      "idCard": "123456789012345678",
      "payeeName": "Jane Doe"
    }
  ]
}
```

### Response
#### Success Response (200)
- **amt** (BigDecimal) - Payment amount.
- **idCard** (String) - ID card number.
- **payeeName** (String) - Payee name.
- **payeeAcc** (String) - Payee account number.
- **afterTaxAmt** (BigDecimal) - Amount after tax (in Yuan).
- **indTaxAmt** (BigDecimal) - Personal income tax amount (in Yuan).
- **vatTaxAmt** (BigDecimal) - Value-added tax amount (in Yuan).
- **taxRatePercent** (String) - Personal income tax rate (%).
- **quickDeduction** (BigDecimal) - Quick deduction amount.
- **yearSettleAmt** (BigDecimal) - Year-to-date settlement amount.
- **monthSettleAmt** (BigDecimal) - Month-to-date settlement amount.
- **payableIndTaxAmt** (BigDecimal) - Year-to-date payable personal income tax.
- **payableVatTaxAmt** (BigDecimal) - Month-to-date payable VAT.
- **paidIndTaxAmt** (BigDecimal) - Year-to-date paid personal income tax.
- **paidVatTaxAmt** (BigDecimal) - Month-to-date paid VAT.

#### Response Example
```json
{
  "amt": 10000.00,
  "idCard": "123456789012345678",
  "payeeName": "Jane Doe",
  "payeeAcc": "621001234567890123",
  "afterTaxAmt": 8500.00,
  "indTaxAmt": 1000.00,
  "vatTaxAmt": 500.00,
  "taxRatePercent": "10%",
  "quickDeduction": 100.00,
  "yearSettleAmt": 100000.00,
  "monthSettleAmt": 5000.00,
  "payableIndTaxAmt": 12000.00,
  "payableVatTaxAmt": 600.00,
  "paidIndTaxAmt": 10000.00,
  "paidVatTaxAmt": 500.00
}
```
```

--------------------------------

### POST /openapi/v1/soho/register

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Registers a new soho user and initiates the signing process. Handles various authentication types and requires identity verification documents.

```APIDOC
## POST /openapi/v1/soho/register

### Description
Registers a new soho user and initiates the signing process. Handles various authentication types and requires identity verification documents.

### Method
POST

### Endpoint
/openapi/v1/soho/register

### Parameters
#### Request Body
- **name** (string) - Required - Maximum 25 characters - Full name.
- **cardNo** (string) - Required - Numeric - Maximum 25 characters - Account number (e.g., WeChat openId, Alipay ID, bank card number).
- **idCard** (string) - Required - Alphanumeric - Maximum 18 characters - Identity card number.
- **mobile** (string) - Required - Numeric - Maximum 11 characters - Mobile phone number.
- **gender** (string) - Optional - Numeric - Maximum 2 characters - Gender (0: male, 1: female).
- **birthDate** (string) - Optional - Alphanumeric - Maximum 19 characters - Date of birth (format: yyyy-MM-dd).
- **residence** (string) - Optional - Alphanumeric - Maximum 100 characters - Residential address.
- **nation** (string) - Optional - Numeric - Maximum 11 characters - Ethnicity ID.
- **documentType** (string) - Optional - Numeric - Maximum 1 character - Document type (default: 0 for PRC resident ID).
- **authType** (string) - Optional - Numeric - Maximum 1 character - Authentication type (1: two-factor (WeChat, Alipay), 2: three-factor (mobile), 3: three-factor (bank card), 4: four-factor).
- **idCardFace** (string) - Optional - Alphanumeric - URL of the front of the ID card.
- **idCardNational** (string) - Optional - Numeric - URL of the back of the ID card.
- **uploadType** (string) - Optional - Numeric - Maximum 1 character - File upload type (1: URL type) (send: 1).

### Request Example
```json
{
  "name": "John Doe",
  "cardNo": "1234567890123456",
  "idCard": "110101199001011234",
  "mobile": "13800138000",
  "gender": "0",
  "birthDate": "1990-01-01",
  "residence": "123 Main St, Anytown",
  "nation": "1",
  "authType": "2",
  "idCardFace": "http://example.com/id_face.jpg",
  "idCardNational": "http://example.com/id_national.jpg",
  "uploadType": "1"
}
```

### Response
#### Success Response (200)
- **resData** (object) - Response data.
  - **code** (string) - Required - Alphanumeric - Maximum 30 characters - Business response code (0 for success).
  - **msg** (string) - Required - Numeric - Maximum 4 characters - Business response message.

#### Response Example
```json
{
  "resData": {
    "code": "0",
    "msg": "Success"
  }
}
```
```

--------------------------------

### POST /openapi/v1/order/queryAddTaxList

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries for merchant C-end VAT settlement details, supporting pagination.

```APIDOC
## POST /openapi/v1/order/queryAddTaxList

### Description
Queries for merchant C-end value-added tax (VAT) settlement details. This endpoint supports data retrieval in pages and allows for continuous fetching using the `count` and `flag` parameters. It returns up to 1000 records per request.

### Method
POST

### Endpoint
`/openapi/v1/order/queryAddTaxList`

### Parameters
#### Request Body
- **levyId** (Long) - Optional - Levy subject ID.
- **idCard** (String) - Optional - ID card number.
- **month** (String) - Required - Query month in 'YYYY-MM' format (e.g., '2024-09').
- **count** (n) - Required - The number of records to fetch. Start with 1 for the first query. Increment for subsequent queries if `flag` is 1.

### Request Example
```json
{
  "levyId": 12345,
  "idCard": "123456789012345678",
  "month": "2024-09",
  "count": 1
}
```

### Response
#### Success Response (200)
- **flag** (int) - Continuation flag: 0 (no more data), 1 (more data available).
- **size** (int) - Number of orders in the current fetch round.
- **list** (Array<Object>) - List of merchant order details.
  
  #### list[] items:
  - **calculateYear** (String) - Settlement year.
  - **calculateQuarter** (String) - Settlement quarter.
  - **levyId** (Long) - Levy subject ID.
  - **idCard** (String) - ID card number.
  - **month** (String) - Query month.
  - **name** (String) - Name.
  - **advanceTaxAmt** (BigDecimal) - Advance settlement tax amount (Yuan).
  - **declareTaxAmt** (BigDecimal) - Declared settlement tax amount (Yuan).
  - **shouldPaymentRefund** (BigDecimal) - Tax amount to be refunded (Yuan).
  - **refundableAmt** (BigDecimal) - Refundable tax amount (Yuan).
  - **actualPaymentRefund** (BigDecimal) - Actual tax refunded (Yuan).
  - **isCompleted** (String) - Whether tax refund/payment is completed (0=Completed, 1=Not Completed).
  - **levyName** (String) - Levy subject name.

#### Response Example
```json
{
  "data": {
    "flag": 1,
    "size": 10,
    "list": [
      {
        "calculateYear": "2024",
        "calculateQuarter": "Q3",
        "levyId": 12345,
        "idCard": "123456789012345678",
        "month": "2024-09",
        "name": "Alice Smith",
        "advanceTaxAmt": 1000.00,
        "declareTaxAmt": 1200.00,
        "shouldPaymentRefund": 0.00,
        "refundableAmt": 200.00,
        "actualPaymentRefund": 200.00,
        "isCompleted": "0",
        "levyName": "Tax Authority A"
      }
    ]
  }
}
```
```

--------------------------------

### POST /openapi/v1/contract/signContract

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Initiates the signing of a contract for a soho user. Supports direct signing or signing via a mini-program link.

```APIDOC
## POST /openapi/v1/contract/signContract

### Description
Initiates the signing of a contract for a soho user. Supports direct signing or signing via a mini-program link.

### Method
POST

### Endpoint
/openapi/v1/contract/signContract

### Parameters
#### Request Body
- **name** (string) - Required - Optional - Maximum 25 characters - Full name.
- **idCard** (string) - Required - Alphanumeric - Maximum 18 characters - Identity card number.
- **levyId** (string) - Required - Numeric - Maximum 19 characters - Levy entity ID.
- **sendType** (string) - Optional - Alphanumeric - Maximum 2 characters - Sending type (0: direct contract signing, 1: mini-program signing).

### Request Example
```json
{
  "name": "John Doe",
  "idCard": "110101199001011234",
  "levyId": "1234567890123456789",
  "sendType": "0"
}
```

### Response
#### Success Response (200)
- **data** (object) - Response data.
  - **code** (string) - Required - Alphanumeric - Maximum 30 characters - Business response code (0 for success).
  - **msg** (string) - Required - Numeric - Maximum 4 characters - Business response message.

#### Response Example
```json
{
  "data": {
    "code": "0",
    "msg": "Success"
  }
}
```
```

--------------------------------

### POST /openapi/v1/order/querySupervisionTaxList

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries for merchant C-end personal income tax settlement details, supporting pagination.

```APIDOC
## POST /openapi/v1/order/querySupervisionTaxList

### Description
Queries for merchant C-end personal income tax settlement details. This endpoint supports data retrieval in pages and allows for continuous fetching using the `count` and `flag` parameters. It returns up to 1000 records per request.

### Method
POST

### Endpoint
`/openapi/v1/order/querySupervisionTaxList`

### Parameters
#### Request Body
- **levyId** (Long) - Optional - Levy subject ID.
- **idCard** (String) - Optional - ID card number.
- **month** (String) - Required - Query month in 'YYYY-MM' format (e.g., '2024-09').
- **count** (n) - Required - The number of records to fetch. Start with 1 for the first query. Increment for subsequent queries if `flag` is 1.

### Request Example
```json
{
  "levyId": 12345,
  "idCard": "123456789012345678",
  "month": "2024-09",
  "count": 1
}
```

### Response
#### Success Response (200)
- **flag** (int) - Continuation flag: 0 (no more data), 1 (more data available).
- **size** (int) - Number of orders in the current fetch round.
- **list** (Array<Object>) - List of merchant order details.
  
  #### list[] items:
  - **levyId** (Long) - Levy subject ID.
  - **idCard** (String) - ID card number.
  - **month** (String) - Query month.
  - **name** (String) - Name.
  - **advanceTaxAmt** (BigDecimal) - Advance settlement tax amount (Yuan).
  - **calculateTaxAmt** (BigDecimal) - Settlement tax amount (Yuan).
  - **declareTaxAmt** (BigDecimal) - Declared settlement tax amount (Yuan).
  - **shouldRefundTax** (BigDecimal) - Tax amount to be refunded (Yuan).
  - **shouldPaidTax** (BigDecimal) - Tax amount to be paid (Yuan).
  - **actualRefundTax** (BigDecimal) - Actual tax refunded (Yuan).
  - **actualPaidTax** (BigDecimal) - Actual tax paid (Yuan).
  - **isCompleted** (String) - Whether tax refund/payment is completed (0=Completed, 1=Not Completed).
  - **levyName** (String) - Levy subject name.

#### Response Example
```json
{
  "data": {
    "flag": 1,
    "size": 10,
    "list": [
      {
        "levyId": 12345,
        "idCard": "123456789012345678",
        "month": "2024-09",
        "name": "Alice Smith",
        "advanceTaxAmt": 500.00,
        "calculateTaxAmt": 600.00,
        "declareTaxAmt": 600.00,
        "shouldRefundTax": 0.00,
        "shouldPaidTax": 100.00,
        "actualRefundTax": 0.00,
        "actualPaidTax": 100.00,
        "isCompleted": "0",
        "levyName": "Tax Authority A"
      }
    ]
  }
}
```
```

--------------------------------

### POST /openapi/v1/task/queryGoodsAllList

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries all invoice categories and task classifications system-wide.

```APIDOC
## POST /openapi/v1/task/queryGoodsAllList

### Description
Queries all invoice categories and task classifications system-wide.

### Method
POST

### Endpoint
/openapi/v1/task/queryGoodsAllList

### Parameters
(No request parameters specified)

### Request Example
```json
{
  "message": "No specific request body parameters defined for this endpoint."
}
```

### Response
#### Success Response (200)
- **data** (array) - Array of task classifications and invoice categories
  - **taskClassifyId** (n) - Task classification ID (innermost)
  - **taskClassifyName** (ans) - Task classification name
  - **taskDescription** (ans) - Task description
  - **skillDemands** (ans) - Skill requirements
  - **invoiceTypeList** (array) - List of associated invoice categories
    - **invoiceType** (ans) - Invoice category product ID
    - **invoiceTypeName** (n) - Invoice category product full name
    - **levyIdList** (n) - Associated levy ID collection

#### Response Example
```json
{
  "data": [
    {
      "taskClassifyId": "1",
      "taskClassifyName": "Design",
      "taskDescription": "Graphic design tasks",
      "skillDemands": "Adobe Photoshop",
      "invoiceTypeList": [
        {
          "invoiceType": "INV456",
          "invoiceTypeName": "Design Services",
          "levyIdList": "levy1"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Add Task Information API

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Creates a new task with details such as name, type, budget, and requirements. Offline tasks require location details.

```APIDOC
## POST /openapi/v1/task/addTaskInfo

### Description
Adds a new task with specified parameters. Offline tasks require province, city, area, and address.

### Method
POST

### Endpoint
/openapi/v1/task/addTaskInfo

### Parameters
#### Query Parameters
- **taskName** (ans) - Required - Task name.
- **taskType** (n) - Required - Task type (e.g., 2 for regular task).
- **taskTypeId** (n) - Required - Task category ID (obtained via `/openapi/v1/task/queryTaskCategory` endpoint).
- **endTime** (date) - Required - Task end date (yyyy-MM-dd).
- **invoiceType** (n) - Required - Invoice category ID (obtained via `/openapi/v1/task/queryTaskCategory` endpoint).
- **recruitingNumber** (n) - Required - Number of people to recruit.
- **officeMode** (n) - Required - Office mode (0: online completion, 1: offline completion).
- **taskBudget** (n) - Required - Task budget (in Yuan).
- **skillDemands** (ans) - Required - Skill requirements.
- **taskDescription** (ans) - Required - Task description.
- **settlementMethod** (n) - Required - Settlement method (0: daily, 1: monthly, 2: per-completion, 3: piece-rate, 4: lump sum).
- **province** (n) - Optional - Province (required for offline tasks, obtain code via `/api/v1/region/province` endpoint).
- **city** (n) - Optional - City (required for offline tasks).
- **area** (n) - Optional - District (required for offline tasks).
- **address** (ans) - Optional - Detailed office address (required for offline tasks).

### Request Example
```json
{
  "taskName": "Develop Mobile App",
  "taskType": 2,
  "taskTypeId": 101,
  "endTime": "2024-12-31",
  "invoiceType": 202,
  "recruitingNumber": 5,
  "officeMode": 0,
  "taskBudget": 50000,
  "skillDemands": "React Native, Node.js, API integration",
  "taskDescription": "Develop a cross-platform mobile application for e-commerce.",
  "settlementMethod": 4,
  "province": "310000",
  "city": "310100",
  "area": "310101",
  "address": "123 Tech Park, Shanghai"
}
```

### Response
#### Success Response (200)
- **taskInfoId** (n) - Task ID returned after task creation (effective after approval).

#### Response Example
```json
{
  "taskInfoId": "TASK98765"
}
```
```

--------------------------------

### POST /openapi/v1/invoice/queryInvoice

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries basic information for invoicing.

```APIDOC
## POST /openapi/v1/invoice/queryInvoice

### Description
Queries for basic invoicing information. This endpoint requires the levy subject ID.

### Method
POST

### Endpoint
`/openapi/v1/invoice/queryInvoice`

### Parameters
#### Request Body
- **levyId** (n) - Required - Levy subject ID.

### Request Example
```json
{
  "levyId": 19
}
```

### Response
#### Success Response (200)
This endpoint returns invoice-related information based on the provided `levyId`. The specific fields returned would depend on the system's implementation.

#### Response Example
```json
{
  "invoiceInfo": {
    "invoiceNumber": "INV-2024-001",
    "issueDate": "2024-10-26",
    "amount": 5000.00,
    "status": "Issued"
  }
}
```
```

--------------------------------

### POST /openapi/v1/merchant/queryGoodsList

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries all invoice product categories belonging to a merchant. Requires the merchant's levy ID.

```APIDOC
## POST /openapi/v1/merchant/queryGoodsList

### Description
Queries all invoice product categories belonging to a merchant. Requires the merchant's levy ID.

### Method
POST

### Endpoint
/openapi/v1/merchant/queryGoodsList

### Parameters
#### Request Body
- **levyId** (n) - Required - Merchant's levy ID

### Request Example
```json
{
  "levyId": "20"
}
```

### Response
#### Success Response (200)
- **data** (array) - List of invoice categories
  - **invoiceType** (ans) - Required - Invoice category product ID
  - **invoiceTypeName** (n) - Invoice category product full name

#### Response Example
```json
{
  "data": [
    {
      "invoiceType": "INV123",
      "invoiceTypeName": "Product A"
    }
  ]
}
```
```

--------------------------------

### POST /openapi/v1/soho/querySohoInfo

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries the information of a soho user based on provided identifiers. Returns details including signing status and various identification fields.

```APIDOC
## POST /openapi/v1/soho/querySohoInfo

### Description
Queries the information of a soho user based on provided identifiers. Returns details including signing status and various identification fields.

### Method
POST

### Endpoint
/openapi/v1/soho/querySohoInfo

### Parameters
#### Request Body
- **name** (string) - Required - Optional - Maximum 25 characters - Full name.
- **idCard** (string) - Required - Alphanumeric - Maximum 18 characters - Identity card number.
- **cardNo** (string) - Optional - Numeric - Maximum 25 characters - Bank card number.
- **mobile** (string) - Optional - Numeric - Maximum 11 characters - Mobile phone number.

### Response
#### Success Response (200)
- **data** (object) - Response data containing soho information.
  - **name** (string) - Required - Optional - Maximum 25 characters - Full name.
  - **cardNo** (string) - Required - Numeric - Maximum 25 characters - Bank card number.
  - **idCard** (string) - Required - Alphanumeric - Maximum 18 characters - Identity card number.
  - **mobile** (string) - Required - Numeric - Maximum 11 characters - Bank-reserved mobile phone number.
  - **gender** (string) - Optional - Numeric - Maximum 2 characters - Gender (0: male, 1: female).
  - **birthDate** (string) - Optional - Alphanumeric - Maximum 19 characters - Date of birth (format: yyyy-MM-dd HH:mm:ss).
  - **residence** (string) - Optional - Alphanumeric - Maximum 100 characters - Residential address.
  - **nation** (string) - Optional - Numeric - Maximum 11 characters - Ethnicity ID.
  - **documentType** (string) - Optional - Numeric - Maximum 1 character - Document type (0: PRC resident ID).
  - **signingState** (string) - Optional - Numeric - Maximum 1 character - Signing status (0: not signed, 1: signed, 2: cancelled).
  - **createTime** (string) - Optional - Alphanumeric - Maximum 20 characters - Signing time.
  - **appId** (string) - Optional - Alphanumeric - Maximum 30 characters - WeChat AppID.
  - **openId** (string) - Optional - Alphanumeric - Maximum 30 characters - WeChat openId.
  - **regSource** (string) - Optional - Numeric - Maximum 1 character - Registration source (0: backend, 1: API, 2: mini-program, 3: official account, 4: H5).
  - **idCardPhoto** (string) - Optional - Numeric - Maximum 1 character - ID card photo status (0: no, 1: yes).
  - **levyIdList** (array) - Optional - List of signing levy IDs (List<Long>).
  - **isMobileAuth** (string) - Optional - Numeric - Maximum 2 characters - Mobile number verification status (0: verified, 1: unverified, 2: failed).
  - **isFace** (string) - Optional - Numeric - Maximum 2 characters - Face verification status (0: completed, 1: not completed).

#### Response Example
```json
{
  "data": {
    "name": "John Doe",
    "cardNo": "1234567890123456",
    "idCard": "110101199001011234",
    "mobile": "13800138000",
    "gender": "0",
    "birthDate": "1990-01-01 10:00:00",
    "residence": "123 Main St, Anytown",
    "nation": "1",
    "documentType": "0",
    "signingState": "1",
    "createTime": "2023-01-01T10:00:00Z",
    "appId": "wx1234567890abcdef",
    "openId": "o3Z8x0jK_aY3f9_a3x_9f3Z8x0",
    "regSource": "1",
    "idCardPhoto": "1",
    "levyIdList": [1, 2, 3],
    "isMobileAuth": "0",
    "isFace": "0"
  }
}
```
```

--------------------------------

### 5.7.5 Query Province/City/District List

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Retrieves a list of provinces, cities, and districts.

```APIDOC
## GET /api/regions/list

### Description
This endpoint retrieves a hierarchical list of administrative regions (provinces, cities, districts).

### Method
GET

### Endpoint
/api/regions/list

### Parameters
No parameters are required for this endpoint.

### Response
#### Success Response (200)
- **regions** (array) - A list of regions, each containing sub-regions.
  - **id** (string) - Region ID
  - **name** (string) - Region name
  - **cities** (array) - List of cities within this region
    - **id** (string) - City ID
    - **name** (string) - City name
    - **districts** (array) - List of districts within this city
      - **id** (string) - District ID
      - **name** (string) - District name

#### Response Example
```json
{
  "regions": [
    {
      "id": "province1",
      "name": "Province A",
      "cities": [
        {
          "id": "city1",
          "name": "City X",
          "districts": [
            {
              "id": "district1",
              "name": "District P"
            }
          ]
        }
      ]
    }
  ]
}
```
```

--------------------------------

### POST /openapi/v1/accAsset/queryAccAsset - Account Query API

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries account balance and frozen amounts for a given merchant and levy subject. It also provides rebate information.

```APIDOC
## POST /openapi/v1/accAsset/queryAccAsset

### Description
Queries account balance and frozen amounts for a given merchant and levy subject. It also provides rebate information.

### Method
POST

### Endpoint
/openapi/v1/accAsset/queryAccAsset

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bankId** (n) - Required - Bank code
- **levyId** (n) - Required - Levy subject ID

### Request Example
```json
{
  "bankId": "string",
  "levyId": "string"
}
```

### Response
#### Success Response (200)
- **merchantId** (n) - Merchant ID
- **bankId** (n) - Bank code
- **bankName** (n) - Bank name
- **bankNo** (n) - Bank account number
- **cashAmt** (s) - Account balance (in cents)
- **cashFreeze** (s) - Frozen amount (in cents)
- **accName** (n) - Account name
- **accBank** (n) - Account bank
- **rebateCashAmt** (n) - Rebate available balance (levy subject dimension)
- **rebateCashFreeze** (n) - Rebate frozen amount (levy subject dimension)

#### Response Example
```json
{
  "data": [
    {
      "merchantId": "string",
      "bankId": "string",
      "bankName": "string",
      "bankNo": "string",
      "cashAmt": "string",
      "cashFreeze": "string",
      "accName": "string",
      "accBank": "string",
      "rebateCashAmt": "number",
      "rebateCashFreeze": "number"
    }
  ]
}
```
```

--------------------------------

### POST /openapi/v1/soho/getSohoLimitQuery

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries the amount issued to a soho user within the current month or year.

```APIDOC
## POST /openapi/v1/soho/getSohoLimitQuery

### Description
Queries the amount issued to a soho user within the current month or year.

### Method
POST

### Endpoint
/openapi/v1/soho/getSohoLimitQuery

### Parameters
#### Request Body
- **idCard** (string) - Required - Alphanumeric - Maximum 18 characters - Identity card number.
- **levyId** (string) - Required - Numeric - Maximum 19 characters - Levy entity ID.

### Request Example
```json
{
  "idCard": "110101199001011234",
  "levyId": "1234567890123456789"
}
```

### Response
#### Success Response (200)
(Specific response fields for this endpoint are not detailed in the provided text. Typically, this would include the queried amount and currency.)

#### Response Example
```json
{
  "data": {
    "issuedAmount": "1000.00",
    "currency": "CNY"
  }
}
```
```

--------------------------------

### POST /openapi/v1/task/taskDetail

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries the details of a specific task. Requires the task ID.

```APIDOC
## POST /openapi/v1/task/taskDetail

### Description
Queries the details of a specific task. Requires the task ID.

### Method
POST

### Endpoint
/openapi/v1/task/taskDetail

### Parameters
#### Request Body
- **taskId** (n) - Required - Task ID

### Request Example
```json
{
  "taskId": "20"
}
```

### Response
#### Success Response (200)
- **data** (object) - Task details
  - **id** (n) - Required - Task ID
  - **merchantId** (n) - Optional - Merchant ID
  - **taskName** (ans) - Optional - Task name
  - **taskType** (n) - Optional - Task type (0: Recruitment, 1: Targeted, 2: Regular)
  - **taskTypeId** (n) - Optional - Task category ID
  - **state** (c) - Optional - Status (0: Valid, 1: Invalid)
  - **auditState** (c) - Optional - Audit status (0: Auditing, 10: Approved, 20: Rejected)
  - **expireState** (c) - Optional - Expiration status (0: Not expired, 1: Expired)
  - **taskTypeIdStr** (ans) - Optional - Task category name
  - **taskBudget** (n) - Optional - Task budget
  - **taskDescription** (ans) - Optional - Task description
  - **settlementMethod** (n) - Optional - Settlement method (0: Daily, 1: Monthly, 2: Per-instance, 3: Piece-rate, 4: Lump sum)
  - **settlementRemarks** (ans) - Optional - Settlement remarks
  - **skillDemands** (ans) - Optional - Skill requirements
  - **officeMode** (n) - Optional - Office mode (0: Online, 1: Offline)
  - **auditRemarks** (ans) - Optional - Audit remarks
  - **province** (an) - Optional - Province
  - **city** (an) - Optional - City
  - **area** (an) - Optional - Area
  - **recruitingNumber** (an) - Optional - Number of recruits
  - **auditTime** (ans) - Optional - Audit time
  - **collectionEndDate** (ans) - Optional - Task collection end date
  - **endTime** (ans) - Optional - Task end date
  - **invoiceType** (ans) - Optional - Invoice category ID
  - **invoiceTypeName** (ans) - Optional - Invoice category name

#### Response Example
```json
{
  "data": {
    "id": "20",
    "merchantId": "123",
    "taskName": "Sample Task",
    "taskType": 2,
    "taskTypeId": "1",
    "state": 0,
    "auditState": 10,
    "expireState": 0,
    "taskTypeIdStr": "Regular Task",
    "taskBudget": 1000,
    "taskDescription": "This is a sample task description.",
    "settlementMethod": 2,
    "settlementRemarks": "Pay upon completion.",
    "skillDemands": "Programming, Design",
    "officeMode": 0,
    "auditRemarks": "Approved.",
    "province": "CA",
    "city": "Los Angeles",
    "area": "Downtown",
    "recruitingNumber": "5",
    "auditTime": "2023-10-27T10:00:00Z",
    "collectionEndDate": "2023-11-10",
    "endTime": "2023-11-30",
    "invoiceType": "INV001",
    "invoiceTypeName": "Consulting Services"
  }
}
```
```

--------------------------------

### POST /openapi/v1/invoice/refundInvoice

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

This endpoint allows querying for refunded invoices within a specified date range.

```APIDOC
## POST /openapi/v1/invoice/refundInvoice

### Description
Queries for refunded invoices within a specified date range. Supports pagination through `count` and `flag` parameters.

### Method
POST

### Endpoint
`/openapi/v1/invoice/refundInvoice`

### Parameters
#### Query Parameters
- **startTime** (datetime) - Required - Start date for the refund query (e.g., '2023-05-30 00:00:00').
- **endTime** (datetime) - Required - End date for the refund query (e.g., '2023-06-30 00:00:00').

#### Request Body
This endpoint does not have a request body.

### Request Example
```json
{
  "startTime": "2023-05-30 00:00:00",
  "endTime": "2023-06-30 00:00:00"
}
```

### Response
#### Success Response (200)
- **merchantBatchId** (ans) - Merchant batch ID.
- **merchantOrderId** (ans) - Merchant order ID.
- **orderId** (ans) - Order serial number.
- **amt** (n) - Amount of refund.
- **payeeName** (s) - Payee name.
- **chargebackReason** (n) - Reason for chargeback.
- **chargebackTime** (n) - Time of chargeback.
- **perTaxType** (2) - Personal income tax deduction method (0: no deduction, 1: borne by individual).
- **perTaxRate** (string) - Personal income tax rate.
- **perTaxAmt** (number) - Personal income tax amount (in cents).
- **perAddTaxAmt** (n) - Value-added tax amount (in cents).

#### Response Example
```json
{
  "data": [
    {
      "merchantBatchId": "batch123",
      "merchantOrderId": "order456",
      "orderId": "serial789",
      "amt": 10000,
      "payeeName": "John Doe",
      "chargebackReason": "Invalid order",
      "chargebackTime": "2023-06-15 10:00:00",
      "perTaxType": "1",
      "perTaxRate": "3%",
      "perTaxAmt": 500,
      "perAddTaxAmt": 200
    }
  ]
}
```
```

--------------------------------

### 5.2.9 Soho Face Verify Link URL

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Generates a link for worker face verification.

```APIDOC
## POST /openapi/v1/soho/faceVerifyLinkUrl

### Description
Generates a link for worker face verification. This link can be used to initiate a face verification process for the worker.

### Method
POST

### Endpoint
/openapi/v1/soho/faceVerifyLinkUrl

### Parameters
#### Request Body
- **name** (o) - Required - The name of the worker.
- **idCard** (an) - Required - The ID card number of the worker.

### Request Example
```json
{
  "name": "o",
  "idCard": "an"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the face verification link URL.

#### Response Example
```json
{
  "data": {
    "url": "string"
  }
}
```
```

--------------------------------

### Query Task Information API

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Retrieves a list of tasks with their details, including task ID, merchant ID, name, and type.

```APIDOC
## POST /openapi/v1/task/queryTaskInfo

### Description
Queries detailed information about tasks.

### Method
POST

### Endpoint
/openapi/v1/task/queryTaskInfo

### Parameters
(No explicit query parameters are detailed in the provided text for this endpoint.)

### Request Example
(No specific request body is detailed in the provided text for this endpoint.)

### Response
#### Success Response (200)
- **id** (n) - Required - Task ID.
- **merchantId** (n) - Optional - Merchant ID.
- **taskName** (ans) - Optional - Task name.
- **taskType** (n) - Optional - Task type (0: recruitment, 1: targeted, 2: regular).
- **taskTypeId** (n) - Optional - Task category ID.

#### Response Example
```json
[
  {
    "id": "TASK98765",
    "merchantId": "MERCHANT123",
    "taskName": "Develop Mobile App",
    "taskType": 2,
    "taskTypeId": 101
  }
]
```
```

--------------------------------

### POST /openapi/v1/task/queryGoodsByLevyId

Source: https://www.yuque.com/pid3r5/pdl887/wy518e3ldcyll7uq?singleDoc#qFJf6/index_singleDoc_qFJf6

Queries all invoice product categories for a levy ID, without merchant isolation. This endpoint is currently paused.

```APIDOC
## POST /openapi/v1/task/queryGoodsByLevyId

### Description
Queries all invoice product categories for a levy ID, without merchant isolation. This endpoint is currently paused.

### Method
POST

### Endpoint
/openapi/v1/task/queryGoodsByLevyId

### Parameters
#### Request Body
- **levyId** (n) - Required - Levy ID

### Request Example
```json
{
  "levyId": "20"
}
```

### Response
#### Success Response (200)
- **data** (array) - List of invoice categories
  - **invoiceType** (ans) - Required - Invoice category product ID
  - **invoiceTypeName** (n) - Invoice category product full name

#### Response Example
```json
{
  "data": [
    {
      "invoiceType": "INV789",
      "invoiceTypeName": "Service X"
    }
  ]
}
```
```
Tokens:
Raw