645 lines
8.7 KiB
Markdown
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 |
|
|
|
|
---
|