swagger: '2.0'
info:
  version: 1.0.0
  title: eGov BPA stakeholder registration System.
  description: |
    APIs for BPA stakeholder registration module. This modules handles Below functionality. 
    1. Apply for new BPA stakeholder registration.
    2. Payment for stakeholder registration
    3. Search existing stakeholder registration application.
    4. update existing stakeholder registration application.
  contact:
    name: eGovernments Foundation
    email: contacts@egovernments.org
schemes:
  - https
basePath: /tl-service
x-api-id: org.egov.tl.services
x-common-path: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml'
paths:
  /v1/_search:
    post:
      summary: Get the list of stakeholder registration application defined in the system.
      description: 
        1. Search and get stakeholder registration licenses(s)  based on defined search criteria.
        2. In case multiple parameters are passed stakeholder registration license(s) will be searched as an AND combination of all the parameters.
      parameters:
        - $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/parameters/requestInfo'
        - $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/parameters/tenantId'
        - $ref: '#/parameters/pageNumber'
        - name: status
          in: query
          description: Search based on status.
          type: string
          allowEmptyValue: true
        - name: ids
          type: array
          items:
            type: integer
            format: int64
          in: query
          maxItems: 50
          description: unique identifier of trade licence 
        - name: applicationNumber
          in: query
          description:  Unique application number for a license application.
          type: string
          minLength: 2
          maxLength: 64
        - name: licenseNumber
          in: query
          description: The unique  license number  for a license.
          type: string
          minLength: 2
          maxLength: 64
        - name: oldLicenseNumber
          in: query
          description: The unique  Old license number for a license.
          type: string
          minLength: 2
          maxLength: 64
        - name: mobileNumber
          in: query
          description: The mobile number of a Trade owner.
          type: string
          pattern: '[0-9]'
      responses:
        '200':
          description: License(s) Retrived Successfully
          schema:
            $ref: '#/definitions/TradeLicenseResponse'
        '400':
          description: Invalid input.
          schema:
            $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/ErrorRes'
      tags:
        - TradeLicense
  /v1/_create:
    post:
      summary: Create new stakeholder registration Licenses.
      description: |
        To create new Trade License in the system. API supports bulk creation with max limit as defined in the Trade License Request. Please note that either whole batch succeeds or fails, there's no partial batch success. To create one Trade License, please pass array with one Trade License object. 
          

        Following Conditions are applied -
          1. PropertyId and OldPropertyId is not mandatory, If entered then validate. Invalid number fails trade license creation
          2. supportDocuments for a given Trade License will created. In case of not attaching the Mandatory Supported Documents creation of New Trade License Fails.
          3. LicenseNumber will be autogenerated on final approval for new License.
          4. ApplicationNumber will be autogenerated for new Trade License
      parameters:
        - name: TradeLicenseRequest
          in: body
          description: Details for the new License(s) + RequestInfo meta data.
          required: true
          schema:
            $ref: '#/definitions/TradeLicenseRequest'
      responses:
        '201':
          description: ReponseInfo with License(s) created successfully
          schema:
            $ref: '#/definitions/TradeLicenseResponse'
        '400':
          description: License(s) creation failed
          schema:
            $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ErrorRes'
      tags:
        - TradeLicense
  /v1/_update:
    post:
      summary: update existing stakeholder registration Licenses.
      description: |
        To update existing Trade License in the system. API supports bulk updation with max limit as defined in the Trade License Request. Please note that either whole batch succeeds or fails, there's no partial batch success. To update one Trade License, please pass array with one Trade License object.
      
        Following Conditions are applied -
          1. Before payment Employee or Citizen can update any details of trade license
          2. After payment Citizen or Employee can't change any details of TL.
        
      parameters:
        - name: TradeLicenseRequest
          in: body
          description: Details for the new License(s) + RequestInfo meta data.
          required: true
          schema:
            $ref: '#/definitions/TradeLicenseRequest'
      responses:
        '201':
          description: ReponseInfo with License(s) updated sudcessfully
          schema:
            $ref: '#/definitions/TradeLicenseResponse'
        '400':
          description: TradeLicense(s) updation failed
          schema:
            $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ErrorRes'
      tags:
        - TradeLicense
definitions:
  
  

#################### Master Data ##########################

  TradeType:
    type: object
    description: 1. This is the detail classification, based on which fees are defined. In Goods, these are the products dealt with and in Service, these are the names of different services. .
     2. License Transactions are enabled at TradeCategoryDetail. 
        License API only allow transactions for active trade category, TradeSubCategory and TradeCategoryDetail.
     3. Consumer of TradeCategoryDetail api should not enable transactions for 'active=false' category,
     4. This is the master data for trade license, it's defined under mdms service.
     5. To get data from mdms 'moduleName=TradeLicense, masterName=TradeCategoryDetail and tradeSubCategory={code of trade sub category master}'.
     6. Multiple TradeCategoryDetail can be defined under single TradeSubCategory
     7. Cobination of tradeSubCategory and code is unique.
     8. License Fees is defined at tradeCategoryDetail level.
     9. Each tradeCategoryDetail is map to a single TradeCategoryUOM
    properties:
      name:
        type: string
        description: name of the UsageCategorySubMinor
        maxLength: 128
        minLength: 2
      code:
        type: string
        description: code of the UsageCategorySubMinor
        maxLength: 64
        minLength: 2
      uom:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/Uom'
      active:
        type: boolean
        description: if the value is true then only any transaction is applicable for perticular TradeCategoryDetail.
    required:
      - code
      - uom
##############################################      
  AccessoryCategory:
    type: object
    description: 1. This is the master data for accessory.
     2. We can add accessories only for active AccessoryCategory .
     4. This is the master data for trade license, it's defined under mdms service.
     5. To get data from mdms 'moduleName=TradeLicense, masterName=AccessoryCategory and tradeSubCategory={code of trade sub category master}'.
     6. Multiple TradeCategoryDetail can be defined under single TradeSubCategory
     7. Cobination of tradeSubCategory and code is unique.
     8. License Fees is defined at tradeCategoryDetail level.
     9. Each tradeCategoryDetail is map to a single TradeCategoryUOM
    properties:
      name:
        type: string
        description: Unit of measurement name.
        maxLength: 128
        minLength: 2
      code:
        type: string
        description: Unique code of uom.
        maxLength: 64
        minLength: 2
      uom:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/Uom'
      active:
        type: boolean
        description: if the value is true then only any transaction is applicable.
    required:
      - code

##############################################      
  
  OwnerInfo:
      allOf:
        - $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/egov-user/contracts/v1-0-0.yml#/definitions/User'
        - type: object
          properties:
            isPrimaryOwner:
              type: boolean
              description: The owner is primary or not
            ownerShipPercentage:
              type: number
              format: double
              description: Ownership percentage.
            ownerType:
              type: string
              description: 'Type of owner, based on this option Exemptions will be applied. This is master data defined in mdms.'
              maxLength: 256
              minLength: 4
            relationship:
              type: string
              description: Relationship with owner.
              enum:
              - FATHER
              - HUSBAND
            documents:
              description: Document of the owner.
              items:
                $ref: '#/definitions/Document'
  

##############################################      


  Organisation:
      type: object
      properties:
        instituionName:
          type: string
          description: Name of the Organisation
        contactNo:
          type: number
          format: double
          description: Organisation Contact No.
        authorizedName:
          type: string
          description: Name of authorized Person
        designation:
          type: string
          description: Designation of authorized person
          maxLength: 256
          minLength: 4
        organisationRegistrationNo:
          type: string
          description: "Registration no fo orgainsation"
          maxLength: 256
          minLength: 4
        address:
          $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/Address'


##############################################


  Document:
    type: object
    description: A Object holds the basic data for a Trade License
    properties:
      tenantId:
        type: string
        description: Unique Identifier of ULB
        maxLength: 128
        minLength: 2
      documentType:
        type: string
        minLength: 2
        maxLength: 64
        description: 1.Unique document type code from common master.
          2. This is defined under mdms common master. 
          3. Object defination is defined under 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/DocumentType'
      fileStoreId:
        type: string
        minLength: 2
        maxLength: 64
        description: Unique file store id of uploaded document.
      documentUid:
        type: string
        minLength: 2
        maxLength: 64
        description: document number(eg.Pan number, aadhar number).
      auditDetails:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/AuditDetails'
    required:
      - tenantId
      - documentType
      - fileStoreId


##############################################
  
  TradeLicense:
    type: object
    description: A Object holds the basic data for a Trade License
    properties:
      id:
        type: string
        minLength: 2
        maxLength: 64
        description: Unique Identifier of the Trade License (UUID)
        readOnly: true
      tenantId:
        type: string
        description: Unique Identifier of ULB
        maxLength: 128
        minLength: 2
      name:
        type: string
        description: Name of the trade.
        maxLength: 256
        minLength: 2
      licenseType:
        type: string
        description: Identifier of the licensee type
        enum:
          - TEMPORARY
          - PERMANENT
      licenseNumber:
        type: string
        description: Unique License Number of the Trade. This is  unique in system for a tenant. This is mandatory but always be generated on the final approval. In Case of Legacy License User will enter the Old License Number.
        maxLength: 64
        minLength: 2
        readOnly: true
      oldLicenseNumber:
        type: string
        description: Unique Old License Number of the Trade. This is  unique in system for a tenant. This is mandatory  for legacy license(DataEntry).
        maxLength: 64
        minLength: 2
      propertyId:
        type: string
        description:  Unique property id.
        maxLength: 64
        minLength: 2
      oldPropertyId:
        type: string
        description: Unique Old property id.
        maxLength: 64
        minLength: 2
      applicationDate:
        type: integer
        format: int64
        description: date on which applicaiton has been generated for new Trade License.
        readOnly: true
      commencementDate:
        type: integer
        format: int64
        description: Commencement Date of the trade as epoch
      issuedDate:
        type: integer
        format: int64
        description: 1. License issued Date of the trade as epoch.
         2. Application approval date.
        readOnly: true
      financialYear:
        type: string
        description:  TradeLicense applicable for financial year.
        maxLength: 64
        minLength: 2
      validFrom:
        type: integer
        format: int64
        description: Date from when license is valid as epoch
      validTo:
        type: integer
        format: int64
        description: Expiry Date of the Trade License as epoch
      action:
        type: string
        description: 1. Perform action to change the state of the trade license.
          2. INITIATE, if application is getting submitted without required document.
          3. APPLY, if application is getting submitted with application documents, in that case api will validate all the required application document.
          4. APPROVE action is only applicable for specific role, that role has to be configurable at service level.
            Employee can approve a application only if application is in APPLIED state and Licesance fees is paid.
        enum:
          - INITIATE
          - APPLY
          - APPROVE
          - REJECT
          - CANCEL
      status:
        type: string
        description: Unique identifier (code) of the Trade license Status
        enum:
          - INITIATED
          - APPLIED
          - APPROVED
          - REJECTED
          - CANCELED
      tradeLicenseDetail:
        $ref: '#/definitions/TradeLicenseDetail'
      auditDetails:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/AuditDetails'
    required:
      - tenantId
      - licenseType
      - commencementDate
      - tradeLicenseDetail
  
  TradeLicenseDetail:
        type: object
        description: A Object holds the basic data for a License
        properties:
          surveyNo:
            type: string
            description: Survey number.
          subOwnerShipCategory:
            type: string
            description: Unique code of SubOwnerShipCategory from SubOwnerShipCategory master of MDMS.
          structureType:
            type: string
            description: StructureType and Structure subtype, this mdms data.
            maxLength: 64
            minLength: 2
          operationalArea:
            type: number
            format: double
            description: This is always in sq yard. 
            maxLength: 128
            minLength: 2
          organisatiion:
            $ref: '#/definitions/Organisation'
            description: Organisation Details in licensee application
          owners:
            description: 'Trade owners, these will be citizen users in system.'
            type: array
            items:
              $ref: '#/definitions/OwnerInfo'
          channel:
            type: string
            description: 'License can be created from different channels' 
            maxLength: 64
            minLength: 2
            enum:
              - COUNTER
              - CITIZEN
              - DATAENTRY
          address:
            $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/Address'
          tradeUnits:
            description: licensee type in case of stakeholder registration.
            type: array
            items:
              $ref: '#/definitions/TradeUnit'
          accessories:
            description: Send list of accessories here.
            type: array
            items:
              $ref: '#/definitions/Accessory'
          applicationDocuments:
            description: 1. List of all the required documents.
              2. Application can be submitted without required document
              3. Once all the document submitted then only application submition process will be completed.
              4. Mandatry application documents for a trade type are defined under ApplicationDocument master which is defined under MDMS.
            type: array
            items:
              $ref: '#/definitions/Document'
          verificationDocuments:
            description: 1. Verification Documents will uploaded at the time of approval.
              2. Mandatry verification documents for a trade type are defined under VerificationDocument master which is defined under MDMS.
            type: array
            items:
              $ref: '#/definitions/Document'
          additionalDetail:
            type: string
            description: 'Json object to store additional details about license'
          auditDetails:
            $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/AuditDetails'
        required:
          - tenantId
          - subOwnerShipCategory
          - owners
          - channel
          - tradeUnits
  
  TradeUnit:
    type: object
    description: A Object holds the basic data for a Trade License
    properties:
      tenantId:
        type: string
        description: Unique Identifier of ULB
        maxLength: 128
        minLength: 2
      tradeType:
        type: string
        minLength: 2
        maxLength: 64
        description: Unique Identifier of the Trade License (UUID)
      uom:
        type: string
        description: Unique License Number of the Trade. This is  unique in system for a tenant. This is mandatory but always be generated on the final approval. In Case of Legacy License User will enter the Old License Number.
        maxLength: 32
        minLength: 2
      uomValue:
        type: string
        description: Unique License Number of the Trade. This is  unique in system for a tenant. This is mandatory but always be generated on the final approval. In Case of Legacy License User will enter the Old License Number.
        maxLength: 32
        minLength: 2
      auditDetails:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/AuditDetails'
    required:
      - tenantId        
  
  Accessory:
    type: object
    description: A Object holds the basic data for a Trade License
    properties:
      tenantId:
        type: string
        description: Unique Identifier of ULB
        maxLength: 128
        minLength: 2
      accessoryCategory:
        type: string
        minLength: 2
        maxLength: 64
        description: Unique Identifier of the Trade License (UUID)
      uom:
        type: string
        description: Unique License Number of the Trade. This is  unique in system for a tenant. This is mandatory but always be generated on the final approval. In Case of Legacy License User will enter the Old License Number.
        maxLength: 32
        minLength: 2
      uomValue:
        type: string
        description: Unique License Number of the Trade. This is  unique in system for a tenant. This is mandatory but always be generated on the final approval. In Case of Legacy License User will enter the Old License Number.
        maxLength: 32
        minLength: 2
      auditDetails:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/AuditDetails'
    required:
      - tenantId
      
  TradeLicenseRequest:
    description: 'Contract class to receive request. Array of TradeLicense items are used in case of create, whereas single TradeLicense item is used for update'
    properties:
      RequestInfo:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-1-1.yml#/definitions/RequestInfo'
      Licenses:
        description: Used for search result and create only
        type: array
        minimum: 1
        maximum: 100
        items:
          $ref: '#/definitions/TradeLicense'
          
  TradeLicenseResponse:
    description: 'Contract class to send response. Array of TradeLicense items are used in case of search results or response for create, whereas single TradeLicense item is used for update'
    properties:
      ResponseInfo:
        $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ResponseInfo'
      Licenses:
        description: Used for search result and create only
        type: array
        maximum: 500
        items:
          $ref: '#/definitions/TradeLicense'
parameters:
  pageSize:
    name: pageSize
    in: query
    description: Number of records returned.
    type: integer
    minimum: 0
    exclusiveMinimum: true
    maximum: 100
    exclusiveMaximum: false
    multipleOf: 10
    default: 20
  pageNumber:
    name: pageNumber
    in: query
    description: Page number
    type: integer
    default: 1
  sortProperty:
    name: sort
    in: query
    description: TradeLicense results will be sorted by licenseNumber ascending by default if this parameter is not provided.
    type: array
    uniqueItems: true
    minItems: 1
    maxItems: 3
    collectionFormat: pipes
    items:
      type: string
      pattern: '[-+](licenseNumber|tradeTitle|ownerName)'
    default:
      - +licenseNumber
tags:
  - name: TradeLicense
    description: APIs required for Trade License.
  - name: NoticeDocument
    description: APIs required to handle Notice Doucments.