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

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