openapi: 3.0.3
info:
  title: Qualification Required Package API
  version: 1.0.0
  description: 营业执照为必填资质；法人身份证为选填资质，缺省时不创建、不替换法人身份证记录。
paths:
  /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:
    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，最大5MB
              legalPersonId:
                type: string
                format: binary
                nullable: true
                description: 法人身份证，选填；PDF/JPG/PNG，最大5MB
  responses:
    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]*$'}
    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}