OfficeRnD Partner Integration Guide

Overview

OfficeRnD offers a comprehensive platform for creating partner integrations. This guide walks you through the process of setting up and exposing an integration with OfficeRnD.

📘
Note
To have your integration listed as a partner integration, you must complete OfficeRnD's approval process.

Creating a Developer Application

The first step in creating a partner integration is to create a developer application in the OfficeRnD admin portal. During this process, you'll specify basic information about the integration.

❗️
Important
Integrating with OfficeRnD is based on the OAuth 2.0 authorization code flow.
An example Node.js application is available to demonstrate the integration process.

Required Information for OfficeRnD

After creating the developer application, you'll need to provide the following details:

Connect URL

The URL where users are redirected when establishing a connection between OfficeRnD and your platform:

Opened as a pop-up in the admin's browser
Should capture the 4 parameters sent from OfficeRnD
Can open a UI to facilitate the connection

Configuration URL

A URL for opening the integration's configuration settings, which can include various integration-specific options.

Healthcheck URL

A URL used to verify the integration's connection status:

Successful Connection Response

{
  "accountName": "_J&J Ltd"
}

Unsuccessful Connection Response

{
  "message": "Error description"
}

Additional Requirements

Sync URL (if applicable): For toggling synchronization between platforms
Multi-Location Support: Determine if multiple accounts can be connected to a single OfficeRnD account

📘
Note All requests to connect, configuration, healthcheck, and sync URLs are GET requests.

URL Configuration Parameters

Common query parameters for requests:

slug: Organization slug
locations: Location ID
signature: Integration secret

Step 1 - Connection Information

When a user clicks "Connect", you'll receive:

code: Exchangeable for an access token
org_slug: Organization slug
locations: Location IDs
integrationId: Integration ID

Step 2 - Generating an Access Token

Generate tokens using the OAuth 2.0 protocol:

curl --location --request POST 'https://identity.officernd.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=client_id' \
--data-urlencode 'client_secret=client_secret' \
--data-urlencode 'code=code' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://url.com/connect/return' \
--data-urlencode 'scope=flex.community.members.read flex.community.members.create flex.billing.payments.read flex.community.billing.payments.create'

📘
Note
scope defines specific permissions. Access tokens are valid for 1 hour, refresh tokens for 15 days.

Step 3 - Retrieving the Integration Secret

Retrieve the integration secret:

curl --location --request GET 'https://app.officernd.com/api/v2/organizations/{{org-slug}}/integrations/{{integrationId}}?appClientId={{client-id}}'

🚧
Warning
The client secret in Developer Tools is different from the request signature secret.

Step 4 - Verifying Payloads

OfficeRnD signs requests with a hash signature:

Payload Examples:

'{"slug":"test-slug","locations":"location-id1, location-id2"}.1648190384' - multi-location integration
'{"slug":"test-slug","locations":""}.1648190384' - all locations integration

Signature Format:

t=1602237976,signature=099618786b221c0bd88346a71e01c8deec60007c2db2ead5975284d4e957b8f5

Verification steps:

Extract timestamp and signature
Prepare payload for signing
Compute expected signature using HMAC SHA-256
Compare signatures

Step 5 - Subscribing to Webhooks

Subscribe to the "Integration.removed" webhook for disconnection handling.

Step 6 - Set Up Return URL

Configure the return URL:

https://app.officernd.com/connect/external-integration/return

After testing, contact [email protected] to make the integration available to other OfficeRnD customers.