Third-party integration onboarding flow

✅

Requirements:

• Third party should have a usergroup in zaptec portal
• Read through Zaptec API usage guidelines API Usage Guidelines and API Fair Use Policy

Onboarding flow Sequence

sequenceDiagram
  actor CP_Owner as CP Owner (end user)
  participant IntegratorApp as Integrator App (third party)
  participant ZaptecPortal as ZaptecPortal / App
  participant ZaptecBackend as Zaptec Backend
  Note over IntegratorApp, ZaptecBackend: Integrator already has a<br/>UserGroup +lookup_key
  IntegratorApp ->> IntegratorApp: Build access-request URL\n https://portal.zaptec.com/access/request/<lookup_key>[&params]
  IntegratorApp -->> CP_Owner: Send URL (e-mail,UI prompt)
  CP_Owner ->> ZaptecPortal: Open link
  ZaptecPortal ->> ZaptecBackend: Validate login
  ZaptecBackend -->> ZaptecPortal: Auth OK
  ZaptecPortal -->> CP_Owner: Display consent screen\n(partnerName ➜ UserGroup name)
  alt User approves
    CP_Owner -->> ZaptecPortal: Grant access
    ZaptecPortal ->> ZaptecBackend: Create share ➜ UserGroup ↔ installation
    ZaptecBackend -->> ZaptecPortal: success=true,installationId
    ZaptecPortal -->> CP_Owner: Receipt page or redirect returnUrl?success=true&installationId
    ZaptecPortal -->> IntegratorApp: Browser redirect (returnUrl)
    IntegratorApp ->> IntegratorApp: Store installation id
  else User rejects
    CP_Owner -->> ZaptecPortal: Deny access
    ZaptecPortal -->> CP_Owner: receipt or redirect?success=false
  end
  Note over IntegratorApp, ZaptecBackend: Required before any Zaptec API usage
  IntegratorApp -->> ZaptecBackend: OAuth2.0 authorisation of Integrator App
  ZaptecBackend -->> IntegratorApp: Access token issued
  alt success=true
    IntegratorApp ->> ZaptecBackend: GET /installations/{installationId}/hierarchy
    ZaptecBackend -->> IntegratorApp: Chargers list[serialNumber,…]
    alt Multiple chargers
      IntegratorApp -->> CP_Owner: Show charger picker
      CP_Owner -->> IntegratorApp: Select charger
    end
    IntegratorApp ->> IntegratorApp: Store chargerID for selected serialNumber
  end

Use this link to edit your flow based on Third Party Onboarding flow

Step 1: Retrieve the Lookup Key

• The lookup key is associated with a UserGroup in the Zaptec system.
• You can find it in the Details tab of a UserGroup entry within the Zaptec portal.
• If you don't have access to this section, please reach out to your Zaptec representative.

Step 2: Construct the Access Request URL

Use this format to create the access request link:

https://portal.zaptec.com/access/request/<lookup_key>

Replace <lookup_key> with your actual UserGroup's lookup key.

This URL prompts the user to authenticate and grant your UserGroup access to their installation.

Step 3: Share the URL with the User

• Send the generated URL to the end user.
• When the user clicks the link, they’ll be prompted to log in to their Zaptec account.
• After logging in, they'll see a permission request showing the name of your integration or UserGroup.
• Once the user approves the request, your UserGroup will be granted access to their installation.

What Granting Access Means

Once access is granted:

• ✅ All users in the UserGroup will be able to view charge history and installation details.
• ✅ They’ll be able to change installation settings.
• ✅ They can control and configure connected charging stations.

This access allows integration partners to fully manage and support the installation within their workflows or platforms.

⚠️

Note: Consent is granted at the installation level, not per charger. One installation may include multiple chargers. The redirect URL after consent includes the installationId, but not the specific charger involved.

Step 4: Customize the Request with URL Parameters

You can tailor the URL using optional query parameters:

📘

Before the user logs in, only the partnerName will be shown. After login, the actual UserGroup name will replace it in the interface.

Example Access Request URL

https://portal.zaptec.com/access/request/BSJG?partnerName=Integration&lang=en&returnUrl=https://yourapp.com/access-result&installationtype=1

Step 5: Handle the Redirect and Access Outcome

After the user completes the access request:

• If no returnUrl is set, they will be redirected to Zaptec's default receipt page:

  /access/receipt/:success?lookup

• If a returnUrl is provided, they’ll be redirected there with the following query parameters:
  • success=true|false
  • installationId=xxxxx (if access was granted)

📘

• This flow supports Zaptec Home and Zaptec Go installations.
• For Zaptec Go (or Home), the standard lookup-based URL works directly.
• For Zaptec Pro, you need to include the specific installationId as a parameter in the URL to target the correct installation, since Pro sites often have multiple chargers or shared access setups.

Step 6: Handling Installations with Multiple Chargers

After consent only installationId is returned. It is key reference point, and it encompasses all chargers under that installation. The Zaptec API does not return a specific charger ID at this point. To identify and link a specific charger, follow this flow:

a. Confirm User Connection

Once the user is redirected with success=true and the installationId, consider the user successfully connected at the installation level. You can now skip or hide any general connection screens in your app.

b. Retrieve Installation Details

Use the following endpoint to fetch a breakdown of the installation and its devices:

GET /installations/{installationId}/hierarchy

→ API Reference

This will return a list of all chargers associated with the installation.

c. Let the User Choose Their Charger

If multiple chargers are present, display a selection interface so the user can choose the charger they interacted with or want to link. Populate the options using the data returned from the hierarchy API.

d. Save the Serial Number

After the user selects their charger, extract the serial number from the corresponding object in the response and store it in the user’s profile within your system.

✅

## Additional Notes

• Users don’t get added to an installation. Instead, they grant access to your UserGroup, and all group members inherit the relevant permissions.

• The consent URL must includeinstallationId for Zaptec Pro installations due to their shared access and multiple charger setups.

• Use the installationtype parameter to specify installation type:

• 1 → Zaptec Go/Home (default)

• 0 → Zaptec Pro