openapi: 3.0.1
info:
  title: PRODUCT-DATA-SERVICE
  description: This API specification serves as reference within product-data-service project for how to design and specify HTTPs-based APIs.
  contact:
    name: SiGREEN API Support
    url: https://api.sigreen-dev.siemens.cloud/
    email: sigreensupport.industry@siemens.com
  version: 1.15.0-v2
servers:
  - url: https://app.sigreen.siemens.com/api/v2
    description: SiGREEN Production Server
  - url: https://app-uat.sigreen-playground.siemens.cloud/api/v2
    description: SiGREEN User Acceptance Test (UAT) Server
security:
  - bearerAuth: []
tags:
  - name: Factory Emissions
    description: '![shopfloor](https://developer.siemens.com/sigreen/images/api-package-shopfloor-blue.svg) Factory emissions APIs'
paths:
  /api/v2/products/{id}/factoryEmissions:
    post:
      tags:
        - Factory Emissions
      summary: Upload factory emissions for a product in SiGREEN.
      description: Upload factory emissions for a product in SiGREEN. Version 2 of the API includes the productionStage object.
      operationId: uploadFactoryEmissionDataV1
      parameters:
        - name: id
          in: path
          description: UUID to identify the product of the company in SiGREEN
          required: true
          schema:
            type: string
          example: C99BE31E-3698-422D-91E3-8270102CC7D5
      requestBody:
        description: Upload factory emissions for a product in SiGREEN
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductFactoryEmissionRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactoryResponse'
        '400':
          description: Bad request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Bad request
                status: 400
                instance: /api/products/{id}/factoryEmissions
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                errors:
                  - code: SIG-BUS-0001
                    detail: Invalid product id
        '401':
          description: Unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Unauthorized
                status: 401
                instance: /api/products/{id}/factoryEmissions
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                errors:
                  - code: SIG-TEC-0003
                    detail: Invalidate Authentication
        '403':
          description: Forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Forbidden
                status: 403
                instance: /api/products/{id}/factoryEmissions
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                errors:
                  - code: SIG-TEC-0005
                    detail: Invalidate Authorization
        5XX:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Internal Server Error
                status: 500
                instance: /api/products/{id}/factoryEmissions
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                errors:
                  - code: SIG-TEC-0002
                    detail: Internal service error
    delete:
      tags:
        - Factory Emissions
      summary: Delete factory emissions for a product in SiGREEN.
      description: API to delete factory emissions for a product in SiGREEN.
      operationId: deleteFactoryEmissionData
      parameters:
        - name: id
          in: path
          description: UUID of the Product in SiGREEN.
          required: true
          schema:
            type: string
          example: C98BE31E-3698-412D-91E3-8270102CC7D5
        - name: factoryId
          in: query
          description: UUID of the factory in SiGREEN.
          required: true
          schema:
            type: string
          example: D98BE31E-3698-412D-91E3-8270102CC7D5
        - name: batchNumber
          in: query
          description: batchNumber of the Product in SiGREEN.
          required: false
          schema:
            type: string
          example: batchNumber
        - name: revision
          in: query
          description: revision of the Product in SiGREEN.
          required: false
          schema:
            type: string
          example: revision
        - name: from
          in: query
          description: The start date of the date range when the emission was created in SiGREEN.DateTime (ISO 8601; UTC Timezone)
          required: false
          schema:
            type: string
          example: '2022-11-20T08:30:00.000Z'
        - name: to
          in: query
          description: The end date of the date range when the emission was created in SiGREEN.DateTime (ISO 8601; UTC Timezone)
          required: false
          schema:
            type: string
          example: '2022-11-20T08:30:00.000Z'
      responses:
        '204':
          description: No content
        '400':
          description: Bad request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Bad request
                status: 400
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                instance: /api/products/{id}/factoryEmissions
                errors:
                  - detail: Invalid product ID
                    code: SIG-BUS-0001
        '401':
          description: Unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: unauthorized
                status: 401
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                instance: /api/products/{id}/factoryEmissions
                errors:
                  - detail: Invalid Authentication
                    code: SIG-BUS-0001
        '403':
          description: Forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Forbidden
                status: 403
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                instance: /api/products/{id}/factoryEmissions
                errors:
                  - detail: Invalid Authorization
                    code: SIG-BUS-0001
        5XX:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.siemens.com/sigreen/validation-error.html
                title: Internal Server Error
                status: 500
                traceId: d7e420c2-5a49-4a34-8ead-9c52a8f91577
                instance: /api/products/{id}/factoryEmissions
                errors:
                  - detail: Internal service error
                    code: SIG-BUS-0001
components:
  schemas:
    Batch:
      required:
        - batchNumber
        - dataSource
      type: object
      properties:
        batchNumber:
          maxLength: 100
          minLength: 0
          type: string
          description: The batch number
          example: BATCH12345
        assessmentYear:
          type: integer
          description: Assessment year for the batch
          format: int32
          example: 2023
        dataSource:
          maxLength: 100
          minLength: 0
          type: string
          description: Data source for the batch information
          example: Internal System
        comment:
          maxLength: 100
          minLength: 0
          type: string
          description: Additional comments about the batch
          example: First batch of the year
      description: Details of a batch including its number, quantity, assessment year, data source, and additional comments.
    FactoryEmissionActivity:
      required:
        - emissionUnit
        - primaryDataShare
        - shareOnTotal
        - total
        - typeOfActivity
      type: object
      properties:
        typeOfActivity:
          maxLength: 50
          minLength: 0
          type: string
          description: Type of activity causing the emission
          example: Electricity
        total:
          type: number
          description: Total emissions
          example: 1000.9
        primaryDataShare:
          type: number
          description: Share of primary data in the total calculation
          example: 75.8
        shareOnTotal:
          type: number
          description: Share of total emissions
          example: 25.8
        emissionUnit:
          type: string
          description: Unit of the emission measurement
          example: kgCO2e/piece
          enum:
            - kgCO2e/piece
            - kgCO2e/Piece
            - kgCO2e/kg
            - kgCO2e/L
            - kgCO2e/m²
            - kgCO2e/m³
            - kgCO2e/kWh
            - kgCO2e/tkm
            - kgCO2e/MJ
            - kgCO2e/m2
            - kgCO2e/m3
        comment:
          maxLength: 250
          minLength: 0
          type: string
          description: Additional comments about the emission
          example: Estimated values
        fossil:
          type: number
          description: Fossil emissions
          example: 500.8
        biogenic:
          type: number
          description: Biogenic emissions
          example: 300.5
        dLuc:
          type: number
          description: Direct Land Use Change emissions
          example: 200.7
        landUse:
          type: number
          description: Land use emissions
          example: 100.2
        aircraft:
          type: number
          description: Aircraft emissions
          example: 50.1
      description: List of factory emissions
    ProductFactoryEmissionRequest:
      required:
        - factoryId
        - from
        - quantity
        - to
      type: object
      properties:
        revision:
          maxLength: 100
          minLength: 0
          type: string
          description: Revision number of the emission data
          example: '1'
        factoryId:
          type: string
          description: Unique identifier of the factory
          example: 123e4567-e89b-12d3-a456-426614174000
        from:
          type: string
          description: Start date in ISO 8601 format
          example: '2023-01-01T00:00:00.000Z'
        to:
          type: string
          description: End date in ISO 8601 format
          example: '2023-01-31T23:59:59.590Z'
        quantity:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: Quantity of the batch
          example: 100
        batch:
          $ref: '#/components/schemas/Batch'
        productionStage:
          $ref: '#/components/schemas/ProductionStage'
        emissions:
          type: array
          description: List of factory emissions
          items:
            $ref: '#/components/schemas/FactoryEmissionActivity'
        comment:
          maxLength: 200
          minLength: 0
          type: string
          description: Additional comments
          example: Emission data collected manually
        sourceSystem:
          maxLength: 200
          minLength: 0
          type: string
          description: Source system of the emission data
          example: API
      description: Product Factory emission request data.
    ProductionStage:
      type: object
      properties:
        pcfIncludingBiogenic:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP total (incl. bio.).  kg CO2e/declared unit
          example: '79.868015629124'
        pcfExcludingBiogenic:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP total (excl. bio.). kg CO2e/declared unit
          example: '56.868015629124'
        fossilGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP fossil. kg CO2e/declared unit
          example: '43.868015629124'
        biogenic:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP biogenic. kg CO2e/declared unit
          example: '35.868015629124'
        biogenicCarbonEmissionsOtherThanCO2:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP biogenic CO2e-emissions (only other GHG emissions than CO2 – excludes biogenic CO2). kg CO2e/declared unit
          example: '0.868015629124'
        biogenicCarbonWithdrawal:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP biogenic CO2-withdrawal (biogenic CO2 contained in the product). kg CO2e/declared unit
          example: '1.868015629124'
        luGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP land use (LU). kg CO2e/declared unit
          example: '22.868015629124'
        aircraftGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP aircraft emissions. kg CO2e/declared unit
          example: '11.868015629124'
        landManagementGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP land management GHG emissions or Removals (incl. non-CO2 sources). kg CO2e/declared unit
          example: '44.868015629124'
        otherBiogenicGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP biogenic CO2e-emissions other biogenic (excluding LUC and Land management). kg CO2e/declared unit
          example: '55.868015629124'
        dLucAndLuGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP direct land use change (dLUC) and GWP land use (LU). kg CO2e/declared unit
          example: '2.868015629124'
        dLucGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP direct land use change (dLUC). kg CO2e/declared unit
          example: '3.868015629124'
        iLucGhgEmissions:
          maxLength: 15
          minLength: 0
          type: string
          description: Production stage GWP indirect land use change emissions. kg CO2e/declared unit
          example: '22.868015629124'
      description: Production stage details
    FactoryResponse:
      type: object
      properties:
        id:
          type: string
          description: UUID to identify the factory of a company in SiGREEN.
          example: 098MS0-IN9099-HJH98275-LML892
    Errors:
      type: object
      properties:
        code:
          type: string
          description: An application-specific error code, expressed as a string value, mostly is this used for validation errors. The format and type of code representation MUST be harmonized across all services within SiGREEN. The code focuses on programs and doesn’t have to be human-readable.
          example: SIG_VLD-092
        detail:
          type: string
          description: Developer friendly, human-readable, detailed description specific to the occurrence of the problem.
          example: 'Invalid Date Format. Please send valid date format (for eg: yyyy-MM-dd''T''HH:mm:ss''Z'')'
        pointer:
          type: string
          description: String with a generated pointer to the wrong value; Collections integrated as an integer, starts with 0
          example: /data/0/from
      description: Extended error array to include descriptions about errors like validation errors.
    Problem:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. This should be a human-redable documentation for the problem type (e.g. list of SiGREEN Validation errors). When this member is not present, its value is assumed to be 'about:blank'.
          example: https://developer.siemens.com/sigreen/validation-error.html
        title:
          type: string
          description: 'Developer friendly, human-readable description or summary that SHOULD NOT change from occurrence to occurrence of the problem. In case of using a custom HTTP status codes in the status field of the error object, the title MUST provide a concise description of the HTTP error code (for example: status: ''599'', title: ''Network Connection Timeout'').'
          example: Bad request
        status:
          type: integer
          description: Numeric HTTP status code for the specific error.
          format: int32
          example: 400
        instance:
          type: string
          description: 'A URI reference that points to the specific resource where the problem was identified (for example: points to the api resource /api/v1/products/{productId}).'
          example: /api/v1/products/{productId}
        traceId:
          type: string
          description: A unique string identifier (UUID), representing a flow through the system.
          example: UUID
        errors:
          type: array
          description: List of detailed error objects
          items:
            $ref: '#/components/schemas/Errors'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
