8.7 KiB
8.7 KiB
下面我帮你整理成:
FDA ESG NextGen 完整 API 请求规范(适合直接开发)
包括:
- 请求 URL
- Method
- Header
- Request Body
- Response
- 状态说明
- 业务用途
- 你的系统该怎么用
基于你上传的 ESG NextGen API Guide v1.2。
一、整体 API 调用顺序
建议你后端固定流程:
1. 获取 OAuth Token
2. 获取 User/Company 信息
3. 生成 Core ID + 临时上传凭证
4. 创建 Payload
5. 上传 ZIP
6. 提交 Payload
7. 查询 Submission Status
8. 查询 ACK
二、统一基础地址
ESG API
https://external-api-esgng.fda.gov
Upload API
https://upload-api-esgng.fda.gov
三、OAuth Token API
1. 获取 Access Token
Request
POST https://external-api-esgng.fda.gov/as/token.oauth2?grant_type=client_credentials&scope=openid%20profile
Headers
Content-Type: application/x-www-form-urlencoded
Body
client_id=dc-7n2sdxk75a1viyutycu6205s5
client_secret=CYufpEbz4lamjwixerj0Ka
Response
{
"access_token": "aZl2hNYnbuOikJZEhmyA",
"token_type": "Bearer",
"expires_in": 3600
}
四、获取用户与公司信息 API
2. 获取 User/Company
这个接口很重要。
因为后续:
- user_id
- company_id
- authorizing_company_id
都来自这里。
Request
GET https://external-api-esgng.fda.gov/api/esgng/v1/companies?user_email=test@test.com
Headers
accesstoken: {access_token}
Query Parameters
| 参数 | 必填 | 说明 |
|---|---|---|
| user_email | 是 | ESG 注册邮箱 |
Response
{
"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
这是核心接口。
测试环境
GET https://external-api-esgng.fda.gov/api/esgng/v1/credentials/api/test
正式环境
GET https://external-api-esgng.fda.gov/api/esgng/v1/credentials/api
Headers
Content-Type: application/json
accesstoken: {access_token}
Request Body
{
"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
{
"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
GET https://upload-api-esgng.fda.gov/rest/forms/v1/fileupload/payload
Headers
Content-Type: application/json
Body
无。
Response
{
"data": {
"payloadId": "123456",
"uploadFileLink": "https://...",
"submitFormLink": "https://..."
}
}
七、上传 eCTD ZIP 文件
5. Upload ZIP
Request
POST https://upload-api-esgng.fda.gov/rest/forms/v1/fileupload/payload/{payloadId}/file
Headers
Content-Type: multipart/form-data
Path Parameters
| 参数 | 说明 |
|---|---|
| payloadId | Payload ID |
FormData
file: 0001.zip
Response
{
"data": {
"status": "SUCCESS",
"message": "File uploaded successfully"
}
}
八、提交 Payload
6. Submit Payload
真正递交。
Request
POST https://upload-api-esgng.fda.gov/rest/forms/v1/fileupload/payload/{payloadId}/submit
Headers
Content-Type: application/json
Request Body
{
"username": "1-CmpAssociatesInc_2023110733023",
"password": "17948854-108c-4831-9000-0859c52fefc0",
"sha256_checksum": "xxxxxxxxxxxxxxxx"
}
SHA256 说明
FDA 会校验:
ZIP 文件完整性
所以:
必须:
本地计算 ZIP SHA256
Response
{
"data": {
"message": "Payload submitted successfully",
"files": [
{
"id": "111",
"name": "0001.zip",
"size": "1024000",
"link": "https://..."
}
]
}
}
九、查询 Submission Status
7. Get Submission Status
Request
GET https://external-api-esgng.fda.gov/api/esgng/v1/submissions/{core_id}
Headers
accesstoken: {access_token}
Path Parameters
| 参数 | 说明 |
|---|---|
| core_id | Submission Core ID |
Response
{
"core_id": "CmpAssociatesInc_2023110733023",
"status": "Upload Initiated",
"submission_protocol": "API",
"esgngcode": "ESGNG270",
"esgngdescription": "Submission status retrieved successfully."
}
十、获取 ACK 信息(重点)
8. Get ACKs
这个最重要。
Request
GET https://external-api-esgng.fda.gov/api/esgng/v1/acknowledgements/{core_id}
Headers
accesstoken: {access_token}
Response
{
"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 |
十四、推荐状态流转
Published
↓
Submitting
↓
Uploaded
↓
Submitted
↓
ACK1
↓
ACK2
↓
ACK3
↓
Archived
十五、失败状态建议
| 场景 | 状态 |
|---|---|
| OAuth失败 | AuthFailed |
| CoreID失败 | MetadataFailed |
| ZIP上传失败 | UploadFailed |
| Checksum失败 | SubmitFailed |
| ACK3 Reject | TechnicalRejected |