n3rgy Upload API

openapi: 3.2.0
info:
  title: Customer Service API V2 Upload API
  description: Customer Service API V2.
  version: '1.0'
  contact:
    name: N3rgy Support
    email: support@n3rgy.com
servers:
- url: https://api-v2.data.n3rgy.com
  description: Live API
- url: https://api-v2-sandbox.data.n3rgy.com
  description: Sandbox API
tags:
- name: Upload
paths:
  /upload/data/deviceid/{deviceId}/readingtype/{readingType}:
    post:
      summary: Upload data to device.
      description: Uploads data into a device identified by its deviceId.
      operationId: uploadData
      security:
      - ApiKeyAuth: []
      parameters:
      - name: deviceId
        description: Device Identifier
        in: path
        required: true
        schema:
          type: string
          example: 0CA2F400005CDFA3
      - name: readingType
        description: Type of the reading being imported. Tariffs not supported. Consumption and import are alias, same for production and export.
        in: path
        required: true
        schema:
          type: string
          enum:
          - consumption
          - production
          - import
          - export
          - READ_INSTANTANEOUS_IMPORT_REGISTERS
          - READ_INSTANTANEOUS_EXPORT_REGISTERS
          - RETRIEVE_IMPORT_DAILY_READ_LOG
          - RETRIEVE_EXPORT_DAILY_READ_LOG
          - RETRIEVE_DAILY_CONSUMPTION_LOG
          example: import
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MeteredValues'
        required: true
      responses:
        200:
          description: Indicates that the request has succeeded. Data stored for a device identified by the deviceId.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check parameter settings or values. Notice that the values are numeric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        404:
          description: Not Found. The provided deviceId does not match a device.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Device not found
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
  /upload/data/deviceid/{deviceId}/readingtype/{readingType}/starttime/{startTime}/endtime/{endTime}:
    delete:
      summary: Deletes data from a device.
      description: Deletes data from a device identified by its deviceId. Data to be purged are type and time bounded.
      operationId: deleteData
      security:
      - ApiKeyAuth: []
      parameters:
      - name: deviceId
        description: Device Identifier
        in: path
        required: true
        schema:
          type: string
          example: 0CA2F400005CDFA3
      - name: readingType
        description: Type of the reading being imported. Tariffs not supported. Consumption and import are alias, same for production and export.
        in: path
        required: true
        schema:
          type: string
          enum:
          - consumption
          - production
          - import
          - export
          example: import
      - name: startTime
        description: Date/time from which the values will be deleted (in the ISO8601 format).
        in: path
        required: true
        schema:
          type: string
          format: date
          example: 2023-01-24 05:29:36+00:00
      - name: endTime
        description: Date/time till which the values will be deleted (in the ISO8601 format).
        in: path
        required: true
        schema:
          type: string
          format: date
          example: 2023-01-25 05:29:36+00:00
      responses:
        200:
          description: Indicates that the request has succeeded. Data deleted for a device identified by the deviceId.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check parameter settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        404:
          description: Not Found. The provided deviceId does not match a device.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Device not found
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
  /upload/devices/:
    post:
      summary: Adds a new non-SMETS device to the inventory.
      description: 'Adds a new non-SMETS device to the inventory.

        The given device shall not specify the hanId, as it will be generated by the service.

        The device fields will be verified for match with the customer permission specified in customer-extended-permissions.uploadsAccessFilter.

        If it doesn''t match then operation will be forbidden.

        '
      operationId: addDevice
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDevice'
        required: true
      responses:
        200:
          description: Indicates that the request has succeeded. The inventory data was updated accordingly.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  deviceId:
                    type: string
                    example: 0CA2F400005CDFA3
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check the schema for the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        409:
          description: Conflict. The request could not be completed due to a conflict with the current state of the resource. The device already exists in the inventory. To update it use PUT method instead.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Device already exists
                  conflictingDeviceId:
                    type: string
                    example: 0CA2F400005CDFA3
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
    get:
      summary: Retrieves a list of devices from the inventory.
      description: Retrieves a list of devices from the inventory. Only devices matching with the customer permission specified in customer-extended-permissions.uploadsAccessFilter will be retrieved.
      operationId: listDevices
      security:
      - ApiKeyAuth: []
      parameters:
      - name: startAt
        description: Start position index.
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
          example: 0
      - name: maxResults
        description: Max number of records to be returned.
        in: query
        schema:
          type: integer
          minimum: 10
          multipleOf: 10
          default: 500
          example: 1000
      responses:
        200:
          description: Indicates that the request has succeeded. Retrieves a list of devices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AMRDevice'
        204:
          description: No Content. The request was fulfilled, but no information to retrieve in the response body. The StartAt parameter might be exceeding the total number of records.
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check parameter settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
  /upload/devices/deviceid/{deviceId}:
    get:
      summary: Retrieves a device from the inventory.
      description: Retrieves a device from the inventory. Only devices matching with the customer permission specified in customer-extended-permissions.uploadsAccessFilter will be retrieved.
      operationId: getDevice
      security:
      - ApiKeyAuth: []
      parameters:
      - name: deviceId
        description: Device Identifier
        in: path
        required: true
        schema:
          type: string
          example: 0CA2F400005CDFA3
      responses:
        200:
          description: Indicates that the request has succeeded. Retrieves a device identified by the deviceId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AMRDevice'
        204:
          description: No Content. The request was fulfilled, but no information to retrieve in the response body. The StartAt parameter might be exceeding the total number of records.
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check parameter settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        404:
          description: Not Found. The provided deviceId does not match a device.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Device not found
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
    put:
      summary: Updates an existing non-SMETS device in the inventory.
      description: Updates an existing non-SMETS device to the inventory. The given device shall not specify the hanId. The device fields will be verified for match with the customer permission specified in customer-extended-permissions.uploadsAccessFilter. If it doesn't match then operation will be forbidden. Both new and old fields values must be checked.
      operationId: updateDevice
      security:
      - ApiKeyAuth: []
      parameters:
      - name: deviceId
        description: Device Identifier
        in: path
        required: true
        schema:
          type: string
          example: 0CA2F400005CDFA3
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDevice'
        required: true
      responses:
        200:
          description: Indicates that the request has succeeded. Updated a device identified by the deviceId.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: updated
                  deviceId:
                    type: string
                    example: 0CA2F400005CDFA3
        204:
          description: No Content. The request was fulfilled, but no information to retrieve in the response body. The inventory data was updated accordingly.
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check parameter settings or values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        404:
          description: Not Found. The provided deviceId does not match a device.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Device not found
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
    delete:
      summary: Deletes a non-SMETS device from the inventory
      description: Deletes a non-SMETS device from the inventory, identified by the deviceId. The device fields will be verified for a match with the customer permission specified in customer-extended-permissions.uploadsAccessFilter. If it doesn't match then the operation will be forbidden.
      operationId: deleteDevice
      security:
      - ApiKeyAuth: []
      parameters:
      - name: deviceId
        description: Device Identifier
        in: path
        required: true
        schema:
          type: string
          example: 0CA2F400005CDFA3
      responses:
        200:
          description: Indicates that the request has succeeded. A device entry will be returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: deleted
        400:
          description: Bad request. The request has incorrect syntax and should not repeat without modifications. Check parameter settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        403:
          description: Unauthorized request. The client does not have access rights to the content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        404:
          description: Not Found. The provided deviceId does not match a device.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Device not found
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerServiceApiV2Function.Arn}/invocations
      tags:
      - Upload
components:
  schemas:
    BadRequestResponse:
      description: Response for the Whitelist/Pair CADs Api HTTP Bad Request error.
      type: object
      properties:
        errors:
          allOf:
          - $ref: '#/components/schemas/ListBadRequestDto'
          - description: List of errors.
    AMRDevice:
      allOf:
      - type: object
        properties:
          hanId:
            description: This is the property identifier. Will be generated when a new device is added. This field shall not be specified for create or update operations. Shall only be defined on read operations.
            type: string
            example: A0DA9479AF7E2F486C37B0E23ADFEF4A1D6954214E249A3E9EB1D2EB711C40E7
      - $ref: '#/components/schemas/UploadDevice'
    ListBadRequestDto:
      type: array
      items:
        $ref: '#/components/schemas/BadRequestErrorDto'
    BadRequestErrorDto:
      description: Represents the Bad Request error element.
      type: object
      properties:
        code:
          format: int32
          description: HTTP status code.
          type: integer
          example: 400
        message:
          description: Error message.
          type: string
    UploadDevice:
      type: object
      required:
      - deviceId
      - deviceManufacturer
      - importMPxN
      - smso
      properties:
        commissionedDate:
          description: 'The date in which the device was commissioned in UTC ISO8601 format (e.g.: 2023-01-24T05:29:36Z). If no time of the day is provided, it will default to midnight (2023-01-24Z).'
          type: string
          format: date
          example: '2023-01-24T05:29:36Z'
        deviceId:
          description: Unique Identifier that can identify the device to the user. It will be the MAC address in the case of a SMETS device, and it will be the meter serial number in the case of an AMR device.
          type: string
          example: 0CA2F400005CDFA3
        deviceManufacturer:
          description: Identifies the meter manufacturer name.
          type: string
          example: MyBrand
        deviceModel:
          description: Identifies the meter manufacturer model.
          type: string
          example: AA.BB.CC
        deviceStatus:
          description: The status of the meter.
          default: UNDEFINED
          type: string
          enum:
          - PENDING
          - WHITELISTED
          - INSTALLED_NOT_COMMISSIONED
          - COMMISSIONED
          - DECOMMISSIONED
          - WITHDRAWN
          - SUSPENDED
          - RECOVERY
          - RECOVERED
          - UNDEFINED
          example: COMMISSIONED
        deviceType:
          description: 'Device type enum. Should follow SMETS standards (e.g.: ESME, GSME, ESME_EXPORT).'
          type: string
          enum:
          - ESME
          - GSME
          - ESME_EXPORT
          example: ESME
        exportMPAN:
          description: Meter Point Access Number for export.
          type: string
          pattern: '[0-9]{13}||[0-9]{9}'
          example: 9876580000483
        firmwareVersion:
          description: The firmware version of the meter.
          type: string
          example: 1100EEFF
        importMPxN:
          description: Meter Point Identifier Number for import.
          type: string
          pattern: '[0-9]{13}||[0-9]{9}'
          example: 9876580000483
        postCode:
          description: The post code where the meter is installed.
          type: string
          example: SW1A 1AA
        address:
          description: The address where the meter is installed.
          type: string
          maxLength: 30
          example: Someones street,7H,York
        smso:
          description: This identifies the SMSO managing the meter. In order to protect the data.n3rgy automated reads from existing SMSOs (Secure, DCC) these values will be forbidden when importing devices through the GUA interface. Thus any values not in ('Secure', 'DCC') will be allowed.
          type: string
          example: AMR
    ForbiddenResponse:
      description: AWS authentication invalid.
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
                description: response status's code
                example: 403
              message:
                type: string
                description: error message
                example: User is not authorized to access this resource with an explicit deny.
    MeteredValues:
      type: object
      required:
      - timestamp
      properties:
        timestamp:
          description: Timestamp of the reading in the ISO8601 format.
          type: string
          format: date
          example: '2020-11-10T17:07:01.580Z'
        primaryValue:
          description: The consumption/production reading of the meter. It should be a decimal with a decimal point.
          type: number
          format: double
          example: 0.25
        secondaryValue:
          description: In hybrid meters should be filled with the second element consumption/production. It should be a decimal with a decimal point.
          type: number
          format: double
          example: 0.25
        additionalInformation:
          description: 'A textual information that may be relevant for the given timestamp. Only a set of values are acceptable. The values will be translated into: VALID_VALUE = "" INVALID_VALUE = "invalid value" VALUE_NOT_AVAILABLE_IN_SMSO = "value not available in SMSO" INVALID_TIMESTAMP = "invalid timestamp"'
          type: string
          enum:
          - VALID_VALUE
          - INVALID_VALUE
          - VALUE_NOT_AVAILABLE_IN_SMSO
          - INVALID_TIMESTAMP
          example: VALID_VALUE
        type:
          description: The type classification of the reading value
          type: string
          enum:
          - HALF_HOURLY
          - TOTAL_BY_PHASE
          - TOTAL
          - REVERSE
          - Q4
          - Q3
          - Q2
          - Q1
          - Q3-Q2
          - Q3+Q4
          - Q2-Q3
          - Q2+Q4
          - Q2+Q3
          - Q1-Q4
          - Q1+Q4
          - Q1+Q3
          - Q1+Q2
          - NET
          - LEADING
          - FORWARD
          - LAGGING
          example: TOTAL
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      x-amazon-apigateway-api-key-source: HEADER