Virtual Peaker Pairing Code Device Discovery - Utility Commissioned Installation API

openapi: 3.2.0
info:
  description: '# Introduction

    Welcome to the Gravity Connect API documentation for Device Partners (typically Device OEMs).'
  x-logo:
    url: ./assets/vp_logo.png
    backgroundColor: '#FFFFFF'
    altText: Virtual Peaker Logo
  version: 2.0.6
  title: Gravity Connect API (Device Partner) Pairing Code Device…
  license:
    name: BSD
servers:
- url: https://example.com
security:
- device_partner_api_auth:
  - device_partner_basic_auth
- device_partner_user_auth:
  - user_read
tags:
- name: Pairing Code Device Discovery - Utility Commissioned Installation
  description: 'The utility commissioned pairing code flow could work as follows:

    1.'
paths:
  /device/{DEVICE_UID}/user:
    get:
      summary: Describe device's user
      description: If a new device is added to Virtual Peaker via the Virtual Peaker's publish device enrollment endpoint. Virtual Peaker will use this endpoint to discover the user associated with the device.
      operationId: readDeviceUser
      tags:
      - Pairing Code Device Discovery - Utility Commissioned Installation
      security:
      - device_partner_api_auth:
        - basic_partner_read_write
      parameters:
      - $ref: '#/components/parameters/deviceUID'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetails'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Details'
  /houses:
    post:
      summary: Publish houses for installation
      description: In the use case where the device partner needs a list of houses to physically install devices, Virtual Peaker will publish the list of houses and corresponding pairing codes via this endpoint. Virtual Peaker will publish to this endpoint nightly with a list of all houses/devices to be installed (the same house will be published each night until it is installed). When the device is installed, the device partner will then use the publish device enrollment status.
      operationId: publishHouseList
      tags:
      - Pairing Code Device Discovery - Utility Commissioned Installation
      security:
      - device_partner_api_auth:
        - basic_partner_read_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: 'Array of addresses and pairing codes. NOTE: This array will include all houses with devices needing to be installed, not just new houses from that day.'
              items:
                type: object
                required:
                - serviceAddress
                - pairingCode
                properties:
                  devices:
                    type: array
                    description: Included if the device partner needs more details on which device (and how many) need installed. If not included, it's assumed the device partner can infer this information based on the program.
                    items:
                      type: object
                      properties:
                        kind:
                          $ref: '#/components/schemas/DeviceKindEnum'
                        type:
                          type: string
                          description: model name/number
                  pairingCode:
                    type: string
                    description: 'The current format is:

                      * 2 alphanumeric characters to denote the pairing code prefix representing the program

                      * 5 random numeric characters that VP uses to link the user to an existing device

                      * 1 check digit. This check digit will be generated following the Luhn algorithm to ensure the 5 digit number is valid. This validation can be performed on the device partner side to provide immediate feedback, but will also be done within our API.'
                    example: A1012344
                  serviceAddress:
                    $ref: '#/components/schemas/ServiceAddress'
      responses:
        '200':
          $ref: '#/components/responses/accepted'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Details'
components:
  schemas:
    DeviceKindEnum:
      type: string
      enum:
      - HWH
      - TSTAT
      - BATTERY
      - EVSE
      - V2G
      - STORAGE-HVAC
    Details:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A human readable response. Because there's no standard for what is included or how information should be formatted, this should not be parsed and utilized programmatically.
    UserDetails:
      type: object
      required:
      - userId
      properties:
        userId:
          type: string
          description: Unique identifier for the user within the device partner's platform
        accountNumber:
          type: string
          description: Utility customer identifier (if available)
        name:
          type: string
        email:
          type: string
        deviceUids:
          type: array
          items:
            type: string
        serviceAddress:
          $ref: '#/components/schemas/ServiceAddress'
    ServiceAddress:
      type: object
      required:
      - streetAddress
      - city
      - state
      - postalCode
      - country
      properties:
        streetAddress:
          type: string
        streetAddress2:
          type: string
        city:
          type: string
        state:
          type: string
          description: Within the US, passed as a 2 letter abbreviation
        postalCode:
          type: string
        country:
          type: string
          description: A 2 letter indication of country. Following [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
  parameters:
    deviceUID:
      name: DEVICE_UID
      in: path
      required: true
      description: The unique identifier for the target device within the partner's platform
      schema:
        type: string
  responses:
    unauthorized:
      description: The request was not properly authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Details'
    badRequest:
      description: Request was not properly formatted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Details'
    accepted:
      description: Message has been accepted for processing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Details'
  securitySchemes:
    device_partner_api_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://example.com/oauth/token
          scopes:
            basic_partner_read_write: conducts all actions on the partners behalf
    device_partner_user_auth:
      type: oauth2
      description: If using the OAuth onboarding method, this authentication method is used for the respective endpoints. Please the the FAQ for more details.
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            user_read: read details about new user
x-tagGroups:
- name: Base Implementation
  tags:
  - Devices
  - Commands
  - Energy Interval Endpoint
- name: Device Onboarding
  tags:
  - OAuth Device Discovery (Preferred)
  - Pairing Code Device Discovery - End User App
  - Pairing Code Device Discovery - Utility Commissioned Installation
  - Device Partner Driven Enrollment
- name: Group Management
  tags:
  - Group Management