Third-Party Integration Notice

When a third-party system connects to FMS Open Platform, it must first receive client credentials and signing credentials from the platform. The authorization flow is used to obtain an access token. Business APIs are called through /openapi/** and must include the token, API Key, timestamp, nonce, and signature in the request headers.

Before integration, the platform should provide the following credentials:

• clientId
• clientSecret
• apiKey
• apiSecret
• Registered redirectUri

Authorization result

After a user completes authorization, the third-party callback address receives code, state, and domain.

• code: one-time authorization code.
• state: pass-through state value originally sent by the third party.
• domain: used to choose the target service domain for subsequent open platform requests.

Exchange authorization code for token

CopyPOST /oauth2/token
Content-Type: application/json

{
  "grantType": "authorization_code",
  "code": "authorization-code",
  "redirectUri": "https://third.example.com/callback",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Successful response example:

Copy{
  "code": 0,
  "message": "Success",
  "data": {
    "access_token": "access-token",
    "token_type": "Bearer",
    "scope": "default"
  },
  "requestId": "req-1234567890abcd",
  "timestamp": 1760000000000
}

• Request fields use camelCase, such as grantType.
• Token fields in the response use snake_case, such as access_token.
• An authorization code can be consumed only once.
• Missing, expired, or already consumed authorization codes currently map to 10004.
• Tokens do not use a fixed absolute expiration strategy. As long as valid requests continue, the platform renews them automatically.

Refresh token

Copy{
  "grantType": "refresh_token",
  "refreshToken": "old-access-token",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Pass the previous access token through the refreshToken field.

All open business APIs use the /openapi/** prefix, for example /openapi/customer/page, /openapi/farm/page, and /openapi/task/page.

Required headers

CopyAuthorization: Bearer <access_token>
X-Api-Key: <apiKey>
X-Timestamp: <unix timestamp in milliseconds>
X-Nonce: <unique value per request>
X-Signature-Version: v1
X-Signature: <signature result>
Content-Type: application/json

HTTP status codes

For /openapi/**, signature-related failures currently return HTTP 401. Some 10001 responses may include a more specific message, but program logic should rely on code.

Unified response structure

Copy{
  "code": 0,
  "message": "Success",
  "data": {},
  "requestId": "req-xxxx",
  "timestamp": 1760000000000
}

Copy{
  "code": 10014,
  "message": "Request signature is invalid",
  "data": null,
  "requestId": "req-xxxx",
  "timestamp": 1760000000000
}

Log the request path, request time, HTTP status, requestId, and response code on the caller side.

Algorithm

• Algorithm: HmacSHA256
• Output: Base64
• Version: v1
• Key: the assigned apiSecret

Signature validation proves that the request was sent by an integrator holding the correct apiSecret and that the request was not modified in transit.

String to sign

CopyHTTP_METHOD + "\n" +
REQUEST_PATH + "\n" +
CANONICAL_QUERY_STRING + "\n" +
BODY_SHA256 + "\n" +
X-Api-Key + "\n" +
X-Timestamp + "\n" +
X-Nonce

• HTTP_METHOD must be uppercase, such as GET or POST.
• REQUEST_PATH must be the full request path without domain, protocol, or QueryString.
• CANONICAL_QUERY_STRING is the sorted and encoded query string without the leading ?.
• Query parameters must be sorted by parameter name, then by parameter value when names are equal.
• Both query keys and values should be UTF-8 encoded and then URL-encoded. In Java, URLEncoder is recommended, and + should be replaced with %20.
• If no query parameters exist, the blank line must still be preserved.
• BODY_SHA256 is the SHA-256 of the raw request body bytes in lowercase hexadecimal.
• X-Api-Key, X-Timestamp, and X-Nonce must match the actual request header values exactly.

The SHA-256 for an empty request body is always:

Copye3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Canonical Query String example

Copy/openapi/task/page?pageNum=1&pageSize=20&name=demo%20task

The CANONICAL_QUERY_STRING that participates in signing is:

Copyname=demo%20task&pageNum=1&pageSize=20

Do not include the leading ? or the full URL in the string to sign.

Body hash rule

The hashed content must be the exact JSON byte sequence that is ultimately sent. Re-serializing after signing can change field order or whitespace and break signature validation.

Copy{"name":"demo","pageNum":1,"pageSize":20}

Signing flow

1. Prepare the request method, path, query parameters, and raw request body.
2. Compute CANONICAL_QUERY_STRING.
3. Compute BODY_SHA256.
4. Build the string to sign in the fixed field order, using \n between lines.
5. Use apiSecret to apply HmacSHA256 to the string to sign.
6. Base64-encode the result and place it in the X-Signature header.

Common signature failures

• 10013 SIGNATURE_REQUIRED: usually means X-Signature or X-Signature-Version is missing.
• 10014 SIGNATURE_INVALID: first check whether the request path included the domain, whether query parameters were sorted, and whether the body was re-serialized after signing.
• 10015 SIGNATURE_TIMESTAMP_EXPIRED: check whether the client machine time differs too much from standard time.
• 10016 SIGNATURE_NONCE_REPLAY: the same X-Nonce was reused.
• If headers look correct but validation still fails, verify that the correct apiSecret is being used for the right environment. Test and production credentials must not be mixed.

• X-Timestamp must fall inside the allowed time window.
• X-Nonce can be used only once inside the valid window.
• Reusing a nonce returns 10016.

• Wrap a shared HTTP client on the caller side to centralize signing and common headers.
• Record the requestId from every response to make joint debugging and issue tracing easier.
• Do not reuse X-Nonce.
• During integration, let your program logic prioritize the response body code; message is better suited to log analysis.
• Third parties should complete test-environment verification before requesting production endpoints and related details. The platform can reject production credential issuance if test-environment integration has not been completed.
• Do not print full apiSecret, full access_token, or full authorization codes in logs.