openapi: 3.1.0
info:
  title: Gridflex API
  version: 1.0.0
  description: |
    Logical API documentation for Gridflex integrations.

    Production traffic is transported through Connxio using:
    `POST https://api.connxio.com/v2/messages/{integrationId}`.

    The `integrationId` value is environment- and customer-specific and is not
    normative in this specification.
servers:
  - url: https://api.connxio.com/v2
    description: Connxio transport host. Logical endpoint names below describe payload intent, not fixed runtime URLs.
tags:
  - name: Facilities
paths:
  /facilities:
    post:
      tags: [Facilities]
      operationId: createFacility
      summary: Create Facility
      description: |
        Creates a facility in Dataverse through the active facility create mapping flow.

        Runtime transport:
        `POST /messages/{integrationId}` in Connxio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFacilityRequest'
            examples:
              minimum:
                value:
                  deliveryAddressId: "50000029"
                  municipality: "4219"
                  streetName: "Vollebekkveien"
                  zipCode: "0598"
                  houseNumber: "4"
                  descriptionOfUsage: "Bolig"
                  junctionId: "05.1010"
              maximum:
                $ref: '#/components/examples/CreateFacilityMaximum'
      responses:
        '200':
          description: Logical create response after Dataverse response mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFacilityResponse'
  /facilities/search:
    post:
      tags: [Facilities]
      operationId: searchFacility
      summary: Search Facility
      description: |
        Searches for facilities using EAN, meter number, installation number, or related facilities on the same installation.

        Runtime transport:
        `POST /messages/{integrationId}` in Connxio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchFacilityRequest'
            examples:
              minimum:
                value:
                  objectId: "707057500000080041"
                  deliveryAddressId: null
                  placeOfConsumption: null
                  meterId: null
                  listAllRelated: false
              maximum:
                value:
                  objectId: null
                  deliveryAddressId: "50000023"
                  placeOfConsumption: "002"
                  meterId: "948135"
                  listAllRelated: true
      responses:
        '200':
          description: Facility search result mapped from Dataverse.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchFacilityResponse'
              examples:
                mappedResponse:
                  value:
                    deliveryAddressID: "50000069"
                    county: null
                    municipality: "3222"
                    zipCode: "1475"
                    city: "FINSTADJORDET"
                    geographicalAreaId: null
                    nodeId: "61058"
                    xCoordinate: null
                    yCoordinate: null
                    description: "Bolig"
                    placeOfConsumptionData:
                      - placeOfConsumptionId: "006"
                        placeOfConsumptionAlternativeId: ""
                        description: "Bolig"
                        streetNumber: null
                        streetName: null
                        houseNumber: null
                        houseLetter: null
                        landNumber: 0
                        titleNumber: 0
                        leaseNumber: 0
                        sectionNumber: 0
                        appartmentNumber: null
                        ssbNumber: null
                        meteringCode: null
                        placeOfConsumptionOwner: null
                        deliverypointData:
                          - deliveryPointNumber: 6
                            objectId: "707057500000000513"
                            operatingUnit: {}
                            measurable: null
                            remotelyRead: null
                            readingMaterial: null
                            gridAreaData:
                              gridAreaId: null
                              gridAreaName: null
                              gridAreaOfficialId: null
                            gridOwnerData: null
                            ratedTransformerRationPower: null
                            ratedTransformerRationVoltage: null
                            branchLineNumber: 6
                            inletLineNumber: 6
                            overloadProtectionNumber: 32
                            mainFeederNumber: 6
                            deliverypointId: null
                            customerData: null
                            salesOrderData: null
                            meterData:
                              - meterId: "6970631400850760"
                                setupTime: "2026-03-25T00:00:00+01:00"
                                meterFunction: null
                                meterStatus: null
                                meterMaster: "AMS 3f 230V"
                                metrologyId: null
                                meterBrand: null
                                meterBrandType: "AMS 3f 230V"
                                hourlyRead: null
                                revisionPeriod: null
                                meterPhase: null
                                meterVoltage1: null
                                counterData: null
                            meterTrafoData: null
                            equipmentData: null
                            mvsIntegration: null
                            subtypeConsumption: null
                            loadLimit: 20
                            dateConnected: null
                            placeOfMeter: null
                            counterData: null
                    branchLineData:
                      - branchLineNumber: 6
                        branchLineAirGround: null
                        materialType: null
                        numberOfCables: null
                        phase: 3
                        crossSection: null
                        topVerified: null
                        distributingSystem: "TNsystem"
                        voltage: 400
                        insulation: null
                        junctionData:
                          junctionId: "61058"
                          junctionDescription: null
                        inletLineData:
                          - inletLineNumber: 6
                            shortCircuitProtectionPhase: 0
                            shortCircuitProtectionAmpere: 32
                            overloadProtectionData:
                              - overloadProtectionNumber: null
                                overloadProtectionPhase: 3
                                overloadProtectionAmpere: 32
                                mainFeederData:
                                  - mainFeederNumber: 0
                                    mainFusePhase: 3
                                    mainFuseAmpere: 32
                                    placeOfConsumptionId: null
  /facilities/postnotification:
    post:
      tags: [Facilities]
      operationId: postNotification
      summary: PostNotification
      description: |
        Creates a Dataverse action from an incoming notification payload and updates facility data through orchestration.

        Runtime transport:
        `POST /messages/{integrationId}` in Connxio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostNotificationRequest'
            examples:
              minimum:
                value:
                  deliveryPoint:
                    objectId: "707057500079292550"
                  contractor:
                    name: "Example Contractor AS"
              maximum:
                $ref: '#/components/examples/PostNotificationMaximum'
      responses:
        '200':
          description: Logical notification response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostNotificationResponse'
  /facilities/work-orders:
    post:
      tags: [Facilities]
      operationId: createWorkOrder
      summary: Create Work Order
      description: |
        Creates a Dataverse action from work order payload and applies follow-up facility updates through orchestration.

        Runtime transport:
        `POST /messages/{integrationId}` in Connxio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkOrderRequest'
            examples:
              minimum:
                value:
                  WorkorderType: "UpdateData"
                  EANNumber: "707057500000010253"
              maximum:
                value:
                  StartOfOccurrence: "2025-10-19T11:59:00Z"
                  WorkorderType: "UpdateData"
                  EANNumber: "707057500000010253"
                  MeterNumber: "6970631400850760"
                  MeterConstant: 23
                  ShortCircuitProtection: 10
                  Phase: 3
                  Status: "Active"
                  Address:
                    AddressLine1: "Bergerveien"
                    BuildingNumber: 7
                    BuildingLetter: null
                    PostalCode: "1475"
                    City: "FINSTADJORDET"
                    Municipality:
                      MunicipalityNumber: "3222"
                      MunicipalityName: "Lorenskog"
                    Cadastre:
                      GNo: 100
                      BNo: 81
                      FNo: 0
                      SNo: null
                      PlotId: null
                      CadastralUnitId: null
      responses:
        '200':
          description: Accepted for orchestration.
  /facilities/han-port:
    post:
      tags: [Facilities]
      operationId: updateHanPort
      summary: Update HAN Port
      description: |
        Updates HAN port state for a facility.

        Runtime transport:
        `POST /messages/{integrationId}` in Connxio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHanPortRequest'
            examples:
              minimum:
                value:
                  EANNumber: "707057500078738707"
                  HANPortOpen: true
              maximum:
                value:
                  EANNumber: "707057500078738707"
                  HANPortOpen: true
      responses:
        '200':
          description: Accepted for orchestration.
components:
  examples:
    CreateFacilityMaximum:
      value:
        deliveryAddressId: "50000029"
        municipality: "4219"
        streetNumber: null
        streetName: "Vollebekkveien"
        matrikkelId: null
        geographicalArea: "Ost"
        deliveryAddressDescription: "Bolig"
        zipCode: "0598"
        houseNumber: "4"
        houseLetter: "C"
        gridArea: 0
        operatingUnitId: "1"
        descriptionOfUsage: "Bolig"
        numberOfPlacesOfConsumption: 1
        junctionId: "05.1010"
        junctionDescription: null
    PostNotificationMaximum:
      value:
        application:
          messageType: "Notificationofchangeofoverloadprotectionormainfuse"
          dateApplicationReceived: "2025-03-26T13:02:43.000Z"
          contractorReferenceNumber: "NM00095-25"
          contractorSignature: "Gunnar Trikker"
          contractorSignatureDate: "2025-03-26T13:02:43.000Z"
          workDescription: null
          gridCompanyMessageReferenceNumber: null
        contractor:
          name: "Gunnars El & Sol AS"
        deliveryAddress:
          deliveryAddressID: "100126316"
          geographicalAreaId: "Vest"
          zipCode: "4580"
          municipality: "4225"
          streetNumber: null
          streetName: "Hausvik"
          matrikkelId: null
          houseNumber: "78"
          xCoordinate: "27474.96420"
          yCoordinate: "6461777.6465"
          description: null
        placeOfConsumption:
          placeOfConsumptionId:
            deliveryAddressId: "100126316"
            placeOfConsumption: "001"
          municipality: "4225"
          houseNumber: "78"
          descriptionOfUsage: "Bolig"
          entrance: null
          floorNumber: null
          appartmentNumber: null
          landNumber: 9
          titleNumber: 18
          leaseNumber: null
          sectionNumber: null
        deliveryPoint:
          deliveryPointNumber: 1
          objectId: "707057500079292550"
          meterId: null
          annualConsumptionKWH: 0
          consumptionKW: 20
          loadLimit: 0
        branchLine:
          branchLineNumber: 1
          voltage: 400
          junctionId: "61058"
          branchLineType: "Aluminium"
          numberOfCables: 1
          phase: 4
          crossSection: 25
          distributingSystem: "TNsystem"
          distributingSubSystem: "CS"
          insulation: "TFXP"
        inletLine:
          inletLineNumber: 0
          shortCircuitProtectionPhase: 3
          shortCircuitProtectionAmpere: 32
        overloadProtection:
          overloadProtectionNumber: 0
          overloadProtectionPhase: 3
          overloadProtectionAmpere: 32
        mainFeeder:
          mainFeederNumber: 0
          mainFusePhase: "3"
          mainFuseAmpere: 32
  schemas:
    CreateFacilityRequest:
      type: object
      required:
        - deliveryAddressId
        - municipality
        - streetName
        - zipCode
        - houseNumber
        - descriptionOfUsage
        - junctionId
      properties:
        deliveryAddressId:
          type: string
        municipality:
          type: string
        streetNumber:
          type: [string, "null"]
        streetName:
          type: string
        matrikkelId:
          type: [string, "null"]
        geographicalArea:
          type: [string, "null"]
        deliveryAddressDescription:
          type: [string, "null"]
        zipCode:
          type: string
        houseNumber:
          type: [string, integer]
        houseLetter:
          type: [string, "null"]
        gridArea:
          type: [integer, "null"]
        operatingUnitId:
          type: [string, "null"]
        descriptionOfUsage:
          type: string
        numberOfPlacesOfConsumption:
          type: [integer, "null"]
        junctionId:
          type: string
        junctionDescription:
          type: [string, "null"]
    CreateFacilityResponse:
      type: object
      properties:
        deliveryAddressId:
          type: string
        assetDeliveryPointsResult:
          type: array
          items:
            type: object
            properties:
              objectId:
                type: string
              placeOfConsumptionId:
                type: string
              deliveryPointNumber:
                type: integer
    SearchFacilityRequest:
      type: object
      properties:
        objectId:
          type: [string, "null"]
          description: EAN number
        deliveryAddressId:
          type: [string, "null"]
          description: Installation number
        placeOfConsumption:
          type: [string, "null"]
          description: Facility number
        meterId:
          type: [string, "null"]
          description: Meter serial number
        listAllRelated:
          type: boolean
          default: false
    SearchFacilityResponse:
      type: object
      properties:
        deliveryAddressID:
          type: [string, "null"]
        county:
          type: [string, "null"]
        municipality:
          type: [string, "null"]
        zipCode:
          type: [string, "null"]
        city:
          type: [string, "null"]
        geographicalAreaId:
          type: [string, "null"]
        nodeId:
          type: [string, "null"]
        xCoordinate:
          type: [string, "null"]
        yCoordinate:
          type: [string, "null"]
        description:
          type: [string, "null"]
        placeOfConsumptionData:
          type: array
          items:
            type: object
            properties:
              placeOfConsumptionId:
                type: [string, "null"]
              placeOfConsumptionAlternativeId:
                type: [string, "null"]
              description:
                type: [string, "null"]
              streetNumber:
                type: [string, "null"]
              streetName:
                type: [string, "null"]
              houseNumber:
                type: [string, "null"]
              houseLetter:
                type: [string, "null"]
              landNumber:
                type: integer
              titleNumber:
                type: integer
              leaseNumber:
                type: integer
              sectionNumber:
                type: integer
              appartmentNumber:
                type: [string, "null"]
              ssbNumber:
                type: [string, "null"]
              meteringCode:
                type: [string, "null"]
              placeOfConsumptionOwner:
                type: [object, "null"]
              deliverypointData:
                type: array
                items:
                  type: object
                  properties:
                    deliveryPointNumber:
                      type: integer
                    objectId:
                      type: [string, "null"]
                      description: EAN number from Dataverse
                    operatingUnit:
                      type: [object, "null"]
                    measurable:
                      type: [boolean, "null"]
                    remotelyRead:
                      type: [boolean, "null"]
                    readingMaterial:
                      type: [string, "null"]
                    gridAreaData:
                      type: [object, "null"]
                      properties:
                        gridAreaId:
                          type: [integer, "null"]
                        gridAreaName:
                          type: [string, "null"]
                        gridAreaOfficialId:
                          type: [string, "null"]
                    gridOwnerData:
                      type: [object, "null"]
                    ratedTransformerRationPower:
                      type: [number, "null"]
                    ratedTransformerRationVoltage:
                      type: [number, "null"]
                    branchLineNumber:
                      type: integer
                    inletLineNumber:
                      type: integer
                    overloadProtectionNumber:
                      type: integer
                    mainFeederNumber:
                      type: integer
                    deliverypointId:
                      type: [integer, "null"]
                    customerData:
                      type: [object, "null"]
                    salesOrderData:
                      type: [object, "null"]
                    meterData:
                      type: array
                      items:
                        type: object
                        properties:
                          meterId:
                            type: [string, "null"]
                          setupTime:
                            type: [string, "null"]
                          meterFunction:
                            type: [string, "null"]
                          meterStatus:
                            type: [string, "null"]
                          meterMaster:
                            type: [string, "null"]
                          metrologyId:
                            type: [string, "null"]
                          meterBrand:
                            type: [string, "null"]
                          meterBrandType:
                            type: [string, "null"]
                          hourlyRead:
                            type: [boolean, "null"]
                          revisionPeriod:
                            type: [integer, "null"]
                          meterPhase:
                            type: [integer, "null"]
                          meterVoltage1:
                            type: [integer, "null"]
                          counterData:
                            type: [array, "null"]
                    meterTrafoData:
                      type: [array, "null"]
                    equipmentData:
                      type: [array, "null"]
                    mvsIntegration:
                      type: [boolean, "null"]
                    subtypeConsumption:
                      type: [string, "null"]
                    loadLimit:
                      type: integer
                    dateConnected:
                      type: [string, "null"]
                    placeOfMeter:
                      type: [string, "null"]
                    counterData:
                      type: [array, "null"]
        branchLineData:
          type: array
          items:
            type: object
            properties:
              branchLineNumber:
                type: integer
              branchLineAirGround:
                type: [string, "null"]
              materialType:
                type: [string, "null"]
              numberOfCables:
                type: [integer, "null"]
              phase:
                type: [integer, "null"]
              crossSection:
                type: [integer, "null"]
              topVerified:
                type: [boolean, "null"]
              distributingSystem:
                type: [string, "null"]
              voltage:
                type: integer
              insulation:
                type: [string, "null"]
              junctionData:
                type: [object, "null"]
                properties:
                  junctionId:
                    type: [string, "null"]
                  junctionDescription:
                    type: [string, "null"]
              inletLineData:
                type: array
                items:
                  type: object
                  properties:
                    inletLineNumber:
                      type: integer
                    shortCircuitProtectionPhase:
                      type: integer
                    shortCircuitProtectionAmpere:
                      type: integer
                    overloadProtectionData:
                      type: array
                      items:
                        type: object
                        properties:
                          overloadProtectionNumber:
                            type: [integer, "null"]
                          overloadProtectionPhase:
                            type: integer
                          overloadProtectionAmpere:
                            type: integer
                          mainFeederData:
                            type: array
                            items:
                              type: object
                              properties:
                                mainFeederNumber:
                                  type: integer
                                mainFusePhase:
                                  type: integer
                                mainFuseAmpere:
                                  type: integer
                                placeOfConsumptionId:
                                  type: [string, "null"]
    PostNotificationRequest:
      type: object
      required:
        - deliveryPoint
      properties:
        application:
          type: object
          additionalProperties: true
        contractor:
          type: object
          additionalProperties: true
        deliveryAddress:
          type: object
          additionalProperties: true
        placeOfConsumption:
          type: object
          additionalProperties: true
        deliveryPoint:
          type: object
          required:
            - objectId
          properties:
            objectId:
              type: string
          additionalProperties: true
        branchLine:
          type: object
          additionalProperties: true
        inletLine:
          type: object
          additionalProperties: true
        overloadProtection:
          type: object
          additionalProperties: true
        mainFeeder:
          type: object
          additionalProperties: true
    PostNotificationResponse:
      type: object
      properties:
        deliveryAddressId:
          type: [string, "null"]
        placeOfConsumptionId:
          type: [string, "null"]
        objectId:
          type: [string, "null"]
        gridCompanyReferenceNumber:
          type: [string, "null"]
    CreateWorkOrderRequest:
      type: object
      required:
        - WorkorderType
        - EANNumber
      properties:
        StartOfOccurrence:
          type: [string, "null"]
          format: date-time
        WorkorderType:
          type: string
        EANNumber:
          type: string
        MeterNumber:
          type: [string, "null"]
        WorkorderId:
          type: [string, "null"]
        MeterConstant:
          type: [number, "null"]
        ShortCircuitProtection:
          type: [number, "null"]
        Phase:
          type: [integer, "null"]
        Status:
          type: [string, "null"]
        Address:
          type: [object, "null"]
          additionalProperties: true
    UpdateHanPortRequest:
      type: object
      required:
        - EANNumber
        - HANPortOpen
      properties:
        EANNumber:
          type: string
        HANPortOpen:
          type: boolean
