下面我帮你整理成: # FDA ESG NextGen 完整 API 请求规范(适合直接开发) 包括: * 请求 URL * Method * Header * Request Body * Response * 状态说明 * 业务用途 * 你的系统该怎么用 基于你上传的 ESG NextGen API Guide v1.2。 --- # 一、整体 API 调用顺序 建议你后端固定流程: ```text id="g1u6ot" 1. 获取 OAuth Token 2. 获取 User/Company 信息 3. 生成 Core ID + 临时上传凭证 4. 创建 Payload 5. 上传 ZIP 6. 提交 Payload 7. 查询 Submission Status 8. 查询 ACK ``` --- # 二、统一基础地址 ## ESG API ```http id="z5c4m6" https://external-api-esgng.fda.gov ``` --- ## Upload API ```http id="7pl3wf" https://upload-api-esgng.fda.gov ``` --- # 三、OAuth Token API # 1. 获取 Access Token --- ## Request ```http id="wl7g0j" POST https://external-api-esgng.fda.gov/as/token.oauth2?grant_type=client_credentials&scope=openid%20profile ``` --- ## Headers ```http id="t7tx8k" Content-Type: application/x-www-form-urlencoded ``` --- ## Body ```x-www-form-urlencoded id="t3h5gm" client_id=dc-7n2sdxk75a1viyutycu6205s5 client_secret=CYufpEbz4lamjwixerj0Ka ``` --- ## Response ```json id="ny1y0j" { "access_token": "aZl2hNYnbuOikJZEhmyA", "token_type": "Bearer", "expires_in": 3600 } ``` --- # 四、获取用户与公司信息 API # 2. 获取 User/Company 这个接口很重要。 因为后续: * user_id * company_id * authorizing_company_id 都来自这里。 --- ## Request ```http id="yrgofn" GET https://external-api-esgng.fda.gov/api/esgng/v1/companies?user_email=test@test.com ``` --- ## Headers ```http id="0m4h3m" accesstoken: {access_token} ``` --- ## Query Parameters | 参数 | 必填 | 说明 | | ---------- | -- | -------- | | user_email | 是 | ESG 注册邮箱 | --- ## Response ```json id="4f6zpc" { "user_id": 55, "user_email": "testagent5@test.com", "company_id": 30, "company_name": "Actual Agency", "company_status": "Approved", "authorizing_companies": [ { "authorizing_company_id": 2, "authorizing_company_name": "Oldio Corp" } ], "esgngcode": "ESGNG390", "esgngdescription": "Company Information retrieved successfully from ESGNG." } ``` --- # 五、生成 FDA Submission Core ID # 3. Generate Submission ID 这是核心接口。 --- # 测试环境 ```http id="4lf9kp" GET https://external-api-esgng.fda.gov/api/esgng/v1/credentials/api/test ``` --- # 正式环境 ```http id="5b3u2e" GET https://external-api-esgng.fda.gov/api/esgng/v1/credentials/api ``` --- ## Headers ```http id="vgkz4s" Content-Type: application/json accesstoken: {access_token} ``` --- ## Request Body ```json id="2q6qvr" { "user_id": "2", "fda_center": "CBER", "company_id": "2", "authorizing_company_id": "2", "submission_type": "510K", "file_count": 1, "description": "eCTD Sequence 0001", "submission_protocol": "API" } ``` --- # 参数说明 | 字段 | 必填 | 说明 | | ---------------------- | -- | --------------- | | user_id | 是 | 用户 ID | | fda_center | 是 | FDA Center | | company_id | 是 | 公司 ID | | authorizing_company_id | 是 | 授权公司 ID | | submission_type | 是 | Submission Type | | file_count | 是 | 文件数量 | | description | 否 | 描述 | | submission_protocol | 是 | 固定 API | --- # FDA Center 示例 | 值 | Center | | ----- | ------ | | CBER | 生物制品 | | CDER | 药品 | | CDRH | 医疗器械 | | CVM | 动物药 | | CFSAN | 食品 | --- # Response ```json id="bx0tqr" { "core_id": "CmpAssociatesInc_2023110733023", "temp_user": "1-CmpAssociatesInc_2023110733023", "temp_password": "17948854-108c-4831-9000-0859c52fefc0", "esgngcode": "ESGNG210", "esgngdescription": "Core Id and Temporary Credentials generated and stored successfully." } ``` --- # 六、创建 Upload Payload # 4. Create Payload --- ## Request ```http id="j4fjlwm" GET https://upload-api-esgng.fda.gov/rest/forms/v1/fileupload/payload ``` --- ## Headers ```http id="jz3dk9" Content-Type: application/json ``` --- ## Body 无。 --- ## Response ```json id="4g8d1r" { "data": { "payloadId": "123456", "uploadFileLink": "https://...", "submitFormLink": "https://..." } } ``` --- # 七、上传 eCTD ZIP 文件 # 5. Upload ZIP --- ## Request ```http id="jlwmhx" POST https://upload-api-esgng.fda.gov/rest/forms/v1/fileupload/payload/{payloadId}/file ``` --- ## Headers ```http id="1l5xj4" Content-Type: multipart/form-data ``` --- ## Path Parameters | 参数 | 说明 | | --------- | ---------- | | payloadId | Payload ID | --- ## FormData ```text id="8l8j9f" file: 0001.zip ``` --- ## Response ```json id="m0nd7l" { "data": { "status": "SUCCESS", "message": "File uploaded successfully" } } ``` --- # 八、提交 Payload # 6. Submit Payload 真正递交。 --- ## Request ```http id="w1i4b6" POST https://upload-api-esgng.fda.gov/rest/forms/v1/fileupload/payload/{payloadId}/submit ``` --- ## Headers ```http id="n52hxm" Content-Type: application/json ``` --- ## Request Body ```json id="7d0qmy" { "username": "1-CmpAssociatesInc_2023110733023", "password": "17948854-108c-4831-9000-0859c52fefc0", "sha256_checksum": "xxxxxxxxxxxxxxxx" } ``` --- # SHA256 说明 FDA 会校验: ```text id="5v3p2u" ZIP 文件完整性 ``` 所以: 必须: ```text id="q4n1z0" 本地计算 ZIP SHA256 ``` --- # Response ```json id="v0i0vw" { "data": { "message": "Payload submitted successfully", "files": [ { "id": "111", "name": "0001.zip", "size": "1024000", "link": "https://..." } ] } } ``` --- # 九、查询 Submission Status # 7. Get Submission Status --- ## Request ```http id="12c7g8" GET https://external-api-esgng.fda.gov/api/esgng/v1/submissions/{core_id} ``` --- ## Headers ```http id="h1h6fz" accesstoken: {access_token} ``` --- ## Path Parameters | 参数 | 说明 | | ------- | ------------------ | | core_id | Submission Core ID | --- ## Response ```json id="j56q1y" { "core_id": "CmpAssociatesInc_2023110733023", "status": "Upload Initiated", "submission_protocol": "API", "esgngcode": "ESGNG270", "esgngdescription": "Submission status retrieved successfully." } ``` --- # 十、获取 ACK 信息(重点) # 8. Get ACKs 这个最重要。 --- ## Request ```http id="lqvz0x" GET https://external-api-esgng.fda.gov/api/esgng/v1/acknowledgements/{core_id} ``` --- ## Headers ```http id="m5g1bo" accesstoken: {access_token} ``` --- ## Response ```json id="4m2f9l" { "core_id": "ci241211033255.xxx", "acknowledgements": [ { "acknowledgement": "ACK1", "status": "Upload Received", "message": "Submission successfully received by ESG", "created_date": "12-11-2024, 03:34:10" }, { "acknowledgement": "ACK2", "status": "Submitted to Center", "message": "Submission successfully submitted to HFP", "created_date": "12-11-2024, 03:34:17" } ], "esgngcode": "ESGNG360", "esgngdescription": "Retrieved all acknowledgements for the given submission." } ``` --- # 十一、ACK 业务含义 | ACK | 含义 | | ---- | ------------- | | ACK1 | ESG 收到文件 | | ACK2 | FDA Center 收到 | | ACK3 | 技术验证结果 | --- # 十二、推荐你的后端接口封装 建议: # 1. FDAAuthService 负责: * token缓存 * token刷新 --- # 2. ESGSubmissionService 负责: * 创建 CoreID * 创建 Payload * 上传 ZIP * 提交 Payload --- # 3. ESGAckService 负责: * 查询 ACK * 更新状态 * ACK 下载 --- # 十三、推荐数据库设计 ## submission_record | 字段 | 类型 | | ------------ | -------- | | id | bigint | | sequence_id | bigint | | core_id | varchar | | payload_id | varchar | | status | varchar | | ack1_status | varchar | | ack2_status | varchar | | ack3_status | varchar | | ack3_message | text | | submit_time | datetime | | archive_time | datetime | --- # 十四、推荐状态流转 ```text id="z0n8j4" Published ↓ Submitting ↓ Uploaded ↓ Submitted ↓ ACK1 ↓ ACK2 ↓ ACK3 ↓ Archived ``` --- # 十五、失败状态建议 | 场景 | 状态 | | ----------- | ----------------- | | OAuth失败 | AuthFailed | | CoreID失败 | MetadataFailed | | ZIP上传失败 | UploadFailed | | Checksum失败 | SubmitFailed | | ACK3 Reject | TechnicalRejected | ---