fanwei-e10-api-doc/references/output-document-standard.md

Output Document Standard

Use this reference to validate final Markdown API documentation.

Audience

Write for external integration developers. They need stable API behavior, authentication, request payloads, response payloads, examples, and field mapping. They do not need internal E10 management steps or implementation details.

Required sections

The final document should contain:

1. Interface title.
2. Interface description.
3. Prerequisites.
4. OAuth2 access_token acquisition flow.
5. Identity mapping rules.
6. Request information.
7. Request parameters.
8. Request examples.
9. Response parameters.
10. Response examples.
11. Error codes.
12. Workflow field description when documenting workflow creation.
13. File upload prerequisite section only when attachments are involved.

Authentication rules

Always document the two-step OAuth2 flow:

1. POST /papi/openapi/oauth2/authorize to obtain code.
2. POST /papi/openapi/oauth2/access_token to exchange code for access_token.

State that access_token is passed in the request body of business APIs, not in an HTTP Authorization header.

Identity mapping rules

External systems usually do not hold E10 internal user or department IDs. Include a dedicated identity mapping section.

Top-level user identifier options:

Parameter	Meaning
JOB_NUM	Employee job number. Preferred for personnel integrations when job numbers are stable.
EMAIL	Employee email.
MOBILE	Employee mobile number.
idNos	Identity document number.
loginID	E10 login ID.
account	Account value supported by the target E10 configuration.

Department identifier options:

Parameter	Meaning
DEPT_CODE	Department code. Preferred when external systems maintain department codes.
DEPT_NAME	Department name. Use only when names are unique and stable.

For form fields:

• Employee fields should explain dataOptions[].type: "resource" and compatible userType values.
• Department fields should explain dataOptions[].type: "department" and compatible deptType values.
• File fields should explain upload-before-submit behavior.

URL and placeholder rules

Use:

https://<E10_BASE>
<ACCESS_TOKEN>
<APP_KEY>
<APP_SECRET>
<CORP_ID>
<CODE>

Do not use real hostnames, IP addresses, accounts, passwords, cookies, tokens, app secrets, database table names, or internal IDs in external documentation.

Request examples

Provide at least two examples for workflow instance creation:

• Minimal request: only required fields and the smallest valid payload.
• Full request: representative optional fields, identity mapping, and detail rows if available.

Examples must use external identifiers such as EMP001 and DEPT_TECH, not E10 internal IDs.

Field table rules

Use this table header:

| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|

Requiredness should be:

• 是 when confirmed.
• 否 when confirmed optional.
• 需确认 when not available from docs, form rules, or user metadata.

Group fields by business meaning. Do not copy E10 internal group names such as “未分组” or technical database groupings unless the user explicitly wants internal documentation.

Forbidden final-document content

The final external-facing document must not contain:

• E10 version numbers.
• Internal API paths under /api/....
• Internal OpenAPI document page IDs.
• Database table names or column names.
• Browser-harness commands.
• XHR interception details.
• Screenshot paths.
• Login page operation instructions.
• Generated-at metadata.
• Informal labels such as “坑”, “注意”, “陷阱”, “提示”.

Convert operational caveats into formal constraints, parameter notes, or prerequisites.