openapi: 3.0.3 info: title: Qualification Required Package API version: 1.0.0 description: 营业执照为必填资质；法人身份证为选填资质，缺省时不创建、不替换法人身份证记录。 paths: /api/merchant/v1/files/qualifications: post: summary: 客户单独上传或替换选填资质 description: >- 需要 merchant:qualification:upload；客户范围只取登录 Token，不接受客户ID。 LEGAL_PERSON_ID 可在已有营业执照后单独新增或替换，不要求重新上传营业执照。 BUSINESS_LICENSE 不允许走此入口，必须与18位统一社会信用代码通过 required-package 一并上传。 security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/QualificationType'} - {$ref: '#/components/parameters/CertificateNo'} - {$ref: '#/components/parameters/ValidTo'} - {$ref: '#/components/parameters/Replace'} requestBody: required: true content: multipart/form-data: schema: type: object required: [file] properties: file: type: string format: binary maxLength: 5242880 description: PDF/JPG/PNG/BMP，最大5MB，声明媒体类型必须与文件签名一致 responses: '200': description: 成功或业务失败，失败时按 code 判断并保留 requestId/traceId content: application/json: schema: oneOf: - {$ref: '#/components/schemas/QualificationUploadSuccess'} - {$ref: '#/components/schemas/ErrorResponse'} '401': {$ref: '#/components/responses/Error'} '403': {$ref: '#/components/responses/Error'} /api/merchant/v1/files/qualifications/required-package: post: summary: 客户上传必需资质包 description: 需要 merchant:qualification:upload；营业执照必填，法人身份证选填。 security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/UnifiedSocialCreditCode'} - {$ref: '#/components/parameters/BusinessLicenseValidTo'} - {$ref: '#/components/parameters/LegalPersonIdValidTo'} - {$ref: '#/components/parameters/ReplaceBusinessLicense'} - {$ref: '#/components/parameters/ReplaceLegalPersonId'} requestBody: {$ref: '#/components/requestBodies/RequiredPackage'} responses: '200': {$ref: '#/components/responses/PackageResult'} /api/platform/v1/files/qualifications/{tenantId}/required-package: post: summary: 平台为客户上传必需资质包 description: 需要 platform:customer:create 或 platform:customer:edit；营业执照必填，法人身份证选填。 security: [{bearerAuth: []}] parameters: - {$ref: '#/components/parameters/TenantId'} - {$ref: '#/components/parameters/UnifiedSocialCreditCode'} - {$ref: '#/components/parameters/BusinessLicenseValidTo'} - {$ref: '#/components/parameters/LegalPersonIdValidTo'} - {$ref: '#/components/parameters/ReplaceBusinessLicense'} - {$ref: '#/components/parameters/ReplaceLegalPersonId'} requestBody: {$ref: '#/components/requestBodies/RequiredPackage'} responses: '200': {$ref: '#/components/responses/PackageResult'} components: securitySchemes: bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT} parameters: QualificationType: name: qualificationType in: query required: true schema: {type: string, enum: [LEGAL_PERSON_ID, FREIGHT_FORWARDER_CERTIFICATE, BANK_ACCOUNT_LICENSE]} CertificateNo: name: certificateNo in: query required: false schema: {type: string, maxLength: 128} ValidTo: name: validTo in: query required: false schema: {type: string, format: date} Replace: name: replace in: query required: false description: 同类有当前资质时必须显式为true；成功后旧文件元数据标记为已替代 schema: {type: boolean, default: false} TenantId: name: tenantId in: path required: true schema: {$ref: '#/components/schemas/Id'} UnifiedSocialCreditCode: name: unifiedSocialCreditCode in: query required: true schema: {type: string, pattern: '^[0-9A-Za-z]{18}$'} BusinessLicenseValidTo: name: businessLicenseValidTo in: query required: false schema: {type: string, format: date} LegalPersonIdValidTo: name: legalPersonIdValidTo in: query required: false description: 仅上传legalPersonId时允许填写 schema: {type: string, format: date} ReplaceBusinessLicense: name: replaceBusinessLicense in: query required: false schema: {type: boolean, default: false} ReplaceLegalPersonId: name: replaceLegalPersonId in: query required: false description: 未上传legalPersonId时必须为false schema: {type: boolean, default: false} requestBodies: RequiredPackage: required: true content: multipart/form-data: schema: type: object required: [businessLicense] properties: businessLicense: type: string format: binary description: 营业执照，必填；PDF/JPG/PNG/BMP，最大5MB legalPersonId: type: string format: binary nullable: true description: 法人身份证，选填；PDF/JPG/PNG/BMP，最大5MB responses: Error: description: 认证或授权失败，响应包含请求关联元数据 content: application/json: schema: {$ref: '#/components/schemas/ErrorResponse'} PackageResult: description: 资质包上传结果 content: application/json: schema: type: object required: [code, data] properties: code: {type: string, enum: ['200']} data: {$ref: '#/components/schemas/PackageUploadResult'} schemas: Id: {type: string, pattern: '^[1-9][0-9]*$'} QualificationUploadSuccess: type: object required: [code, message, data, timestamp] properties: code: {type: string, enum: ['200']} message: {type: string} data: {$ref: '#/components/schemas/QualificationUploadResult'} requestId: {type: string, nullable: true} traceId: {type: string, nullable: true} timestamp: {type: string, format: date-time} ErrorResponse: type: object required: [code, message, requestId, traceId, timestamp] properties: code: {type: string, example: A0403} message: {type: string} data: {nullable: true} requestId: {type: string, minLength: 1} traceId: {type: string, minLength: 1} timestamp: {type: string, format: date-time} QualificationUploadResult: type: object required: [qualificationId, tenantStatus, documentUrl] properties: qualificationId: {$ref: '#/components/schemas/Id'} reviewId: allOf: [{$ref: '#/components/schemas/Id'}] nullable: true description: 上传不自动送审，当前固定为null tenantStatus: {type: string, enum: [PROFILE_REQUIRED, REJECTED]} documentUrl: {type: string, minLength: 1} PackageUploadResult: type: object required: [businessLicenseQualificationId, tenantStatus, businessLicenseDocumentUrl] properties: businessLicenseQualificationId: {$ref: '#/components/schemas/Id'} legalPersonIdQualificationId: allOf: [{$ref: '#/components/schemas/Id'}] nullable: true tenantStatus: {type: string} businessLicenseDocumentUrl: {type: string, minLength: 1} legalPersonIdDocumentUrl: {type: string, nullable: true}