Reconciliation API Integration Document #

Background: This document defines the technical specification for the reconciliation interface developed by the RMS to support data pulling by 99. The interface enables 99 to retrieve full transaction data, verify unilateral accounting, and ensure financial reconciliation accuracy.

99 will query the transaction data of RMS at regular intervals every day. RMS needs to provide some API for transaction data query. The query process is as follows:

1.What does RMS need to provide #

1.1 Domain name #

https://www.YourDomainName.com/order/v1/queryByDate

https://www.YourDomainName.com/order/v1 This is an example of the request prefix that needs to be provided by RMS to 99

/queryByDate This is the fixed request path

1.2 API interface #

1.2.1 /queryByDate #

An API interface for querying order data based on a time range, for example: https://www.YourDomainName.com/order/v1/queryByDate

https://www.YourDomainName.com/order/v1 This is an example of the request prefix that needs to be provided by RMS to 99

/queryByDate This is the fixed request path

1.2.2 /queryByIds #

Query the order data API interface by the orderId collection, for example: https://www.YourDomainName.com/order/v1/queryByIds

https://www.YourDomainName.com/order/v1 This is an example of the request prefix that needs to be provided by RMS to 99

/queryByIds This is the fixed request path

2.Authentication Method #

99 will use the "Authentication Method" in the RMS Open API to generate signatures(see link: Authentication Method)

99 shall use the api_key and api_secret to access the reconciliation interface developed by RMS. The authentication process strictly follows the DIDI-AUTH-SHA256 standard.

99 will use the same api_key and api_secret as the RMS Open API.

2.1 Authorization Header Example #

Authorization: DIDI-AUTH-SHA256|{"api_key":"xxx","nonce_string":"xxx","timestamp":"xxx","signature":"xxx"}

Note: RMS need reject requests with expired timestamps, invalid signatures, or missing authorization headers.

3. Integration process #

4. API Code Description #

4.1 Http Code Description #

For all APIs, if an error occurs, 99 will attempt to request three times, with an interval of no more than 3 seconds between each request.

4.2 Http Response Field Description #

4.3 Errno description #

When the request is successful, errno must be 0. When an exception is requested, it is recommended to use the following errno (optional).

4.4 Example Response (Request params check failed) #

{
  "errno": 40002,
  "errmsg": "cnpj is empty",
  "trace_id": "0a0f120f637304feb06e4cabb166e702"
}

5. API interface parameter description #

5.1 /queryByDate #

Description #

Query the order data API interface based on the time range.

99 will regularly check the order data of the previous day from RMS every day to reconcile the order data

Domain: https://www.YourDomainName.com/order/v1

URL: /queryByDate

Request Method: POST

Content-Type: application/json

Request Traffic Limit: <= 5 QPS (request per second)

5.1.1 Request Parameters #

The header of the request must contain a valid signature, and the request body should include the following JSON data:

5.1.2 Example Request #

curl --location --request POST 'https://www.YourDomainName.com/order/v1/queryByDate' \
--header 'Authorization: DIDI-AUTH-SHA256|{"api_key":"de2b29daf0cb69bde91a2622779b43b1","nonce_string":"g3oB6qC7ep4CpgzziReyvW68HlQtGfvp","timestamp":"1760684986","signature":"F269FFEDA4DEE2FE9B7593AD79C29D75450CAF3C23A927A3606C007B7C0F83D9"}' \
--header 'Content-Type: application/json' \
--data '{
    "trace_id": "0a0f120f637304feb06e4cabb166e702",
    "cnpj": "1478351357824",
    "startTime": 1770692400,
    "endTime": 1770778799,
    "pageNo": 1,
    "pageSize": 20
}'

5.1.3 Pagination #

• Pagination Parameters: pageNo (default: 1) and pageSize (default: 100)
• Pagination Logic: The RMS shall return data in pages sorted by orderTime (Order completion time descending); if pageSize exceeds the maximum, it shall be truncated to 1000.

Note: The time range between startTime and endTime shall not exceed 30 days. If exceeded, RMS shall return an error.

5.1.4 Response Parameters #

5.1.5 Data Object Parameters #

5.1.6 Order List Parameters (Order Dimension) #

5.1.7 Order Item Response Parameters (Sub Order Dimension) #

5.1.8 Example Response #

{
  "errno": 0,
  "errmsg": "success",
  "trace_id": "0a0f120f637304feb06e4cabb166e702",
  "data": {
    "totalNum": 1,
    "orderList": [
      {
        "discountCode": "3MHSG",
        "cnpj": "1341351235",
        "orderId": "cbef3eed-b4d6-4be5-a2ac-71f1576a3148",
        "orderTime": 1743649061,
        "orderStatus": 1,
        "orderItemList": [
          {
            "orderItemId": "a3e7ae73-c1a3-460f-a606-45d9541bba8e",
            "productCode": "1001",
            "originalAmount": 5.00,
            "totalDiscount": 0.33,
            "stationDiscount": 0.26,
            "platformDiscount": 0.07,
            "paymentAmount": 4.67,
            "quantity": 1.32,
            "partnershipFee": 0
          },
          {
            "orderItemId": "c549965d-c484-4bc1-b606-9f847adc7193",
            "productCode": "123",
            "originalAmount": 5.00,
            "totalDiscount": 0.23,
            "stationDiscount": 0.18,
            "platformDiscount": 0.05,
            "paymentAmount": 4.77,
            "quantity": 0.911,
            "partnershipFee": 0
          }
        ]
      }
    ]
  }
}

5.1.9 Example Response (No Matching Data) #

If no matching data exists: Return totalNum=0 and empty orderList.

{
  "errno": 0,
  "errmsg": "success",
  "trace_id": "0a0f120f637304feb06e4cabb166e702",
  "data": {
    "totalNum": 0,
    "orderList": []
  }
}

5.2 /queryByIds #

Description #

Query the order data API interface by the orderId collection.

When the order data returned by RMS is missing, 99 will use orderIds to query the order data of RMS.

For example: When 99 had 100 orders on the previous day but the RMS returned less than 100, 99 will use the set of orderIds that the RMS did not return to query again

Domain: https://www.YourDomainName.com/order/v1

URL: /queryByIds

Request Method: POST

Content-Type: application/json

Request Traffic Limit: <= 5 QPS (request per second)

5.2.1 Request Parameters #

The header of the request must contain a valid signature, and the request body should include the following JSON data:

5.2.2 Example Request #

curl --location --request POST 'https://www.YourDomainName.com/order/v1/queryByIds' \
--header 'Authorization: DIDI-AUTH-SHA256|{"api_key":"de2b29daf0cb69bde91a2622779b43b1","nonce_string":"g3oB6qC7ep4CpgzziReyvW68HlQtGfvp","timestamp":"1760684986","signature":"F269FFEDA4DEE2FE9B7593AD79C29D75450CAF3C23A927A3606C007B7C0F83D9"}' \
--header 'Content-Type: application/json' \
--data '{
    "trace_id": "0a0f120f637304feb06e4cabb166e702",
    "cnpj": "1478351357824",
    "orderIdList": [
      "3b146f42-180e-4bc1-960f-8efe907e00001",
      "d290f1ee-6c54-4b01-90e6-d701748f00002"
  ]
}'

5.2.3 Response Parameters #

5.2.4 Data Response Parameters (Order Dimension) #

5.2.5 Order Item Response Parameters (Sub Order Dimension) #

5.2.6 Example Response #

{
  "errno": 0,
  "errmsg": "success",
  "trace_id": "0a0f120f637304feb06e4cabb166e702",
  "data": [
    {
      "discountCode": "3MHSG",
      "cnpj": "1341351235",
      "orderId": "cbef3eed-b4d6-4be5-a2ac-71f1576a3148",
      "orderTime": 1743649061,
      "orderStatus": 1,
      "orderItemList": [
        {
          "orderItemId": "a3e7ae73-c1a3-460f-a606-45d9541bba8e",
          "productCode": "1001",
          "originalAmount": 5.00,
          "totalDiscount": 0.33,
          "stationDiscount": 0.26,
          "platformDiscount": 0.07,
          "paymentAmount": 4.67,
          "quantity": 1.32,
          "partnershipFee": 0
        },
        {
          "orderItemId": "c549965d-c484-4bc1-b606-9f847adc7193",
          "productCode": "123",
          "originalAmount": 5.00,
          "totalDiscount": 0.23,
          "stationDiscount": 0.18,
          "platformDiscount": 0.05,
          "paymentAmount": 4.77,
          "quantity": 0.911,
          "partnershipFee": 0
        }
      ]
    }
  ]
}

5.2.7 Example Response (No Matching Data) #

If no matching data exists: Return empty data

{
  "errno": 0,
  "errmsg": "success",
  "trace_id": "0a0f120f637304feb06e4cabb166e702",
  "data": []
}

Reconciliation API Document Update Log #

Description #

This log records all update histories of the API document, including new APIs, field adjustments, function optimizations, bug fixes, etc. It helps external integrators track changes and adapt to the integration work. Update records are sorted in descending order of version numbers, with the latest updates displayed first.

Update Records #

V1.0.0 - 2026-02-10 #

1. Released the initial version,Clarified API calling specifications, signature rules, error code definitions, and data format descriptions.

• API interface:/queryByDate
• API interface:/queryByIds