ectd-ui/fda-api.md
2026-09-15 10:54:51 +08:00

645 lines
8.7 KiB
Markdown

下面我帮你整理成:
# 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 |
---