# NetSapiens Marketplace Enablement Workflow and Requirements for Acrobits Cloud Softphone

## Overview

This document describes the setup requirements and integration contract needed to support Acrobits Cloud Softphone enablement on the NetSapiens Marketplace.

Marketplace enablement has three related workstreams:

1. Base platform technical setup for the NetSapiens environment.
2. Communication Service Provider (CSP) onboarding and commercial relationship establishment.
3. Optional domain-level messaging synchronization provisioning.

The base platform prerequisites are sufficient for Acrobits to enable NetSapiens OAuth login, SIP calling, NetSapiens contacts synchronization, CDR/call history synchronization, call park, and answering rules management.

Messaging synchronization is a separate optional path. It applies when the CSP wants NetSapiens messaging synchronized into the Acrobits platform, optionally including SMS synchronization through the NetSapiens platform.

## Enablement Sequence

1. A CSP operating a NetSapiens environment enables Acrobits Cloud Softphone from the NetSapiens Marketplace.
2. NetSapiens contacts Acrobits at contact@acrobits.cz with the technical prerequisites and CSP contact information.
3. Acrobits performs the initial technical setup and contacts the CSP for onboarding details.
4. Acrobits returns the Acrobits `cloudId`, `cloudId` API key, and Acrobits messaging server host to NetSapiens.
5. NetSapiens uses those returned values in its marketplace setup flow.
6. If messaging synchronization is enabled for a domain, NetSapiens provisions the domain through the Acrobits messaging callback endpoint using Office Manager credentials.

## Base Platform Prerequisites

### Configuration Prerequisites

NetSapiens provides the following values to Acrobits:

| Value | Description |
| --- | --- |
| Client ID | OAuth client ID issued for Acrobits Cloud Softphone access to the NetSapiens API. |
| Client Secret | OAuth client secret paired with the OAuth client ID. |
| NetSapiens portal URL | URL of the NetSapiens portal/API environment used for OAuth/API access. |
| Primary core hostname | NetSapiens primary SIP/core hostname, for example `core1.my.ucaas.tech`. |

The NetSapiens portal URL and primary core hostname are separate values and both are required for base platform enablement.

### Network Prerequisites

The NetSapiens API, and any NetSapiens endpoint that Acrobits services call, must accept HTTPS connections from the relevant Acrobits source IPs.

Use the Acrobits IP allowlist documentation as the source of truth:

https://doc.acrobits.net/cloudsoftphone/allowlist/#cloudsoftphone-services-ip-list

For base platform enablement, the relevant Acrobits service groups include:

- Web Login server
- App provisioning servers
- Dashboard application
- Acrobits validation/testing source IPs

For push notification support, allow the SIPIS IPs listed in the allowlist documentation for Cloud Softphone. CSP-hosted SIPIS is also supported if preferred; contact Acrobits for details.

If messaging synchronization is enabled, also allow the Acrobits messaging server source IPs listed as the messaging backend server in the allowlist documentation.

Acrobits will confirm the applicable service hosts and IP groups for the target region or deployment.

## CSP Onboarding Information

NetSapiens must provide enough CSP context for Acrobits to establish the onboarding and commercial relationship with the CSP responsible for the NetSapiens environment.

NetSapiens provides the following onboarding context to Acrobits:

| Value | Description |
| --- | --- |
| CSP company name | Legal or operating name of the communication service provider. |
| CSP contact name | Technical, business, or marketplace contact for the CSP. |
| CSP contact details | Contact email and phone number, if available. |

Acrobits collects the deeper onboarding details directly from the CSP, including preferred branding, desired feature set, and commercial or billing details if the CSP proceeds toward live production use.

Commercial and billing details may be finalized later and are not required for the initial technical setup or optional messaging provisioning.

## Acrobits Response Values

Acrobits completes the initial setup after receiving the technical prerequisites and CSP contact information. Acrobits then returns the values NetSapiens needs for the marketplace setup flow:

| Value | Description |
| --- | --- |
| Acrobits `cloudId` | Dedicated Acrobits `cloudId` for the NetSapiens environment. |
| `cloudId` API key | API key associated with the dedicated Acrobits `cloudId`. |
| Acrobits messaging server host | Hostname of the Acrobits messaging server used for messaging provisioning callbacks. |

These values are required for the messaging synchronization provisioning path. They can be stored during NetSapiens marketplace setup even if messaging synchronization is enabled later, or only for selected domains.

## Optional Messaging Synchronization Provisioning

Messaging synchronization provisioning is required only when NetSapiens messaging sync is enabled for a domain. It is not required for base platform enablement.

When messaging synchronization is enabled for a domain, NetSapiens calls the Acrobits domain provisioning endpoint. The provisioning call creates or confirms the NetSapiens domain on the Acrobits messaging server.

Office Manager credentials are needed only for the optional messaging synchronization provisioning flow. The Office Manager account is used by Acrobits to create and maintain domain-wide messaging subscriptions in NetSapiens.

### Messaging Provisioning Endpoint

```http
POST https://{acrobitsMessagingServerHost}/netsapiens/callbacks/{cloudId}/domains
```

### Path Parameters

| Parameter | Description |
| --- | --- |
| `acrobitsMessagingServerHost` | Acrobits messaging server host returned by Acrobits for the NetSapiens environment. |
| `cloudId` | Acrobits `cloudId` returned by Acrobits for the NetSapiens environment. |

Example host:

```text
api-us.messaging.acrobits.cz
```

The actual host may differ by region or deployment.

### Headers

```http
x-ntspns-api-key: <cloudId API key>
```

| Header | Description |
| --- | --- |
| `x-ntspns-api-key` | API key configured for the dedicated Acrobits `cloudId`. |

### Request Body

```json
{
  "domainName": "example.com",
  "officeManagerName": "integration-office-manager",
  "officeManagerPassword": "password"
}
```

| Field | Description |
| --- | --- |
| `domainName` | NetSapiens domain name to be provisioned for messaging synchronization. |
| `officeManagerName` | Username of the dedicated Office Manager account. |
| `officeManagerPassword` | Password of the dedicated Office Manager account. |

### Response Codes

The domain provisioning request is intended to be idempotent.

| Status code | Description |
| --- | --- |
| `201 Created` | Domain was successfully created on the Acrobits messaging server. |
| `200 OK` | Domain already existed on the Acrobits messaging server. |

## Security Recommendations

Secrets should be scoped and handled according to their role in the setup flow:

| Secret | Scope |
| --- | --- |
| NetSapiens OAuth client secret | Provided to Acrobits for base platform enablement. |
| Acrobits `cloudId` API key | Returned by Acrobits and used by NetSapiens when calling the messaging provisioning endpoint. |
| Office Manager password | Supplied only during optional domain messaging synchronization provisioning. |

Use a dedicated Office Manager service account for messaging synchronization provisioning to avoid disruption from normal user lifecycle changes.

The Acrobits `cloudId` API key must be treated as a secret and shared only between NetSapiens and Acrobits systems.