ERM Shadow API Guidelines

Table of Contents

• Omnivoltaic Shadow API
• Requirements
• Usage
• Other Resources

Omnivoltaic Shadow API

This documentation shows how the Shadow API is designed to mirror the Omnivoltaic OTP API (same requests & expected responses) but with source data from the Enterprise Resource Management (ERM) web system.

The Shadow API functions as a proxy server that intelligently redirects users based on their account status when logging in:

• If a user has not been migrated, the Shadow API will automatically reroute their request to the legacy system.
• If a user has been successfully migrated to ERM, all their subsequent requests will be seamlessly redirected to the ERM system.

Request/Response Compatibility

All API requests should maintain the same request body and response structure. However, clients might experience differences in productID: in the Legacy system, product IDs are integers; in ERM they are strings.

Requirements

1. Distributors should have an account on the Enterprise Resource Management (ERM) web application.
2. Distributor data must be migrated from the Legacy (B2B) account to ERM.

Usage

To migrate to the new API endpoints, clients must change the URL from https://api.omnivoltaic.com to https://erm-shadow-api.omnivoltaic.com and continue using the base URL https://api.omnivoltaic.com/ in the codebase.

All other endpoints have similar names. For example:

• ERM login: https://erm-shadow-api.omnivoltaic.com/user/login
• Legacy endpoint: https://api.omnivoltaic.com/user/login

Afterwards, the client will no longer have access to the B2B legacy system. This ensures a seamless transition to the updated endpoints.

ID Migration

Upon successful migration and password reset, developers can choose between using legacy product/item IDs (int type) or updating them with ERM IDs (string type). We strongly recommend updating to ERM IDs, as they will be used exclusively for new product additions. ERM IDs can be found in the ERM UI under the "items" page, or via CSV files provided by Omnivoltaic during migration.

Response Format

Login request:

{
  "username": "",
  "password": ""
}

Expected response:

{
  "accessToken": "",
  "user_role": ""
}

Type Exception

We have an exception on the response where you would expect string instead of int type. For example, when listing assigned items, you get the same object JSON but unlike the Legacy API, assignedItemsID, productItemID, and distributorID will be strings, not int type.

Example assigned items response:

{
  "total": 9,
  "results": [
    {
      "assignedItemsID": "507f1f77bcf86cd799439011",
      "productItemID": "61800dc4bf5a3fe75eeb5d37",
      "distributorID": "618e2c9434c1b72953dad999",
      "itemAssignDate": "2021-11-01T16:00:51.750Z"
    }
  ]
}

Deprecated Endpoints

The following endpoints have been deprecated and are no longer supported:

• https://{{domain}}/otp/commitOtp
• https://{{domain}}/Otp/generateOtp

Use daysCode, freeCode, or resetCode instead.

Other Resources

The API utilizes https://prod-federated-graphql-api.omnivoltaic.com/graphql for GraphQL, which developers can use to access more functionalities.