# Business Connect

Business Connect is a specialized integration module built for **ERP developers, functional consultants, and integrators** working with enterprise resource planning systems. It's the power-user counterpart to the [standard External API](/emobiq-ai/readme/external-api.md) setup — instead of defining endpoints one at a time, Business Connect lets you authenticate against your ERP instance and **import the full API surface** in a single step.

{% hint style="info" %}
*Business Connect is designed for users who already understand their ERP's API model. If you're not familiar with concepts like tenants, endpoint versions, or OAuth scopes, work with your ERP administrator to gather the required credentials before continuing.*
{% endhint %}

***

### Supported ERPs

Business Connect currently supports the following ERP vendors:

* **Acumatica**
* **Microsoft Dynamics 365 Business Central**
* **Sage**

Each vendor exposes a different set of connection parameters — described in detail below.

***

### How It Differs from the Standard Setup

| Capability     | Standard External API                  | Business Connect                                         |
| -------------- | -------------------------------------- | -------------------------------------------------------- |
| API discovery  | Manual entry or OpenAPI schema upload  | Automatic import using ERP instance credentials          |
| Setup style    | Endpoint-by-endpoint configuration     | One-time vendor configuration, full API surface imported |
| Target user    | General developers / integrators       | ERP developers, functional consultants                   |
| Authentication | Basic, API Key, Bearer, JWT, OAuth 2.0 | Vendor-specific (OAuth 2.0, username/password)           |
| Best for       | Any third-party REST API               | Acumatica, Dynamics 365, Sage integrations               |

***

### The Business Connect Wizard

Business Connect runs as a 4-step wizard:

1. **Select the type of connector** — choose your ERP vendor (Acumatica, Dynamics 365, or Sage)
2. **Enter connector information** — provide instance URL, credentials, and authentication details
3. **Select function** — pick which endpoints to import
4. **Select collection to save** — choose where to file the imported endpoints

The sections below walk through each step.

***

### Step 1 & 2: Configuring the Connection

{% tabs %}
{% tab title="Acumatica" %}
Acumatica exposes its data through **contract-based REST endpoints**, where each endpoint is a versioned, named bundle of entities (e.g., the built-in `Default` endpoint, or any custom endpoint you've extended in the Web Service Endpoints screen, `SM207060`). Business Connect authenticates against the Acumatica instance's built-in identity server and pulls in the entity schema for the endpoint you select.

**ERP context:**

* Each Acumatica tenant runs its own identity server at `Base URL + /identity/connect/token`
* The combination of **Endpoint Name + Endpoint Version** determines which entities (e.g., `Customer`, `SalesOrder`, `Bill`) are exposed and what fields they carry
* Multi-tenant Acumatica instances require the **Tenant Name** (called *Company* in Acumatica's UI) so the token is scoped to the right database

**Required fields:**

* **Base URL** *(required)* — your Acumatica instance URL\
  e.g., `https://your-company.acumatica.com`
* **Endpoint Version** *(required)* — the contract-based endpoint version configured under *Web Service Endpoints*\
  e.g., `22.200.001`
* **Endpoint Name** *(required)* — the endpoint to expose\
  e.g., `Default`
* **Tenant Name** *(optional)* — the Acumatica tenant/company; required for multi-tenant instances\
  e.g., `Company`

**Authentication Type:** `OAuth 2.0` or `No Auth`

{% hint style="info" %}
*Use `No Auth` only for endpoints intentionally exposed without authentication (rare, typically internal sandboxes). Production Acumatica instances should always use OAuth 2.0.*
{% endhint %}

When using **OAuth 2.0**, only the **Password Credentials** grant type is supported. Provide:

* **Access Token URL** — defaults to `Base URL + /identity/connect/token`
* **Username** *(required)* — Acumatica user (the same login used in the Acumatica UI)
* **Password** *(required)* — Acumatica user password
* **Client ID** *(required)* — Client ID from the Acumatica *Connected Applications* record (`SM303010`)\
  e.g., `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
* **Client Secret** *(required)* — Client Secret generated alongside the Client ID
* **Scope** *(required)* — OAuth scopes\
  e.g., `api offline_access` (use `offline_access` if you need refresh token support)

{% hint style="info" %}
*Register the Connected Application in Acumatica under **System → Integration → Connected Applications**, choose the **Resource Owner Password Credentials** flow, and assign it to the Acumatica user whose credentials you'll enter here.*
{% endhint %}
{% endtab %}

{% tab title="Dynamics 365" %}
Microsoft Dynamics 365 Business Central exposes data through two API surfaces: the **standard REST API** (Microsoft's published, versioned API at `/api/v2.0/...`) and **OData v4** (the underlying protocol used by published pages and queries). Business Connect lets you target either, and authenticates through Microsoft Entra ID (Azure AD).

**ERP context:**

* Business Central is multi-tenanted on Microsoft Entra — the **Tenant ID** identifies your Entra tenant, and the **Environment** identifies the Business Central environment within it (e.g., `Production`, `Sandbox`)
* Each environment can host multiple **Companies** (Business Central's term for a chart-of-accounts / legal-entity boundary). Leave it blank to import companies; specify one to scope the import
* Service-to-service integrations should use **client credentials** with an Azure App Registration that has been granted the `API.ReadWrite.All` permission (or equivalent) on the Business Central API

**Required fields:**

* **API Base URL** *(required)*\
  e.g., `https://api.businesscentral.dynamics.com`
* **Business Central instance version** *(required)* — the API version path segment\
  e.g., `v2.0`
* **Tenant ID** *(required)* — your Microsoft Entra tenant GUID\
  e.g., `11111111-2222-3333-4444-555555555555`
* **Environment** *(required)* — Business Central environment name\
  e.g., `Production`
* **Company** *(optional)* — Business Central company display name\
  e.g., `CRONUS USA, Inc.`

**API Type:** `API` (Microsoft's standard REST API) or `OData v4`

{% hint style="info" %}
*Choose **API** for the official, version-stable Business Central REST endpoints (recommended for most integrations). Choose **OData v4** when you need to call published pages, queries, or AL-extended endpoints that aren't surfaced through the standard API.*
{% endhint %}

**Authentication Type:** `Client Credentials` (OAuth 2.0) or `No Auth`

When using **Client Credentials**, provide:

* **Access Token URL** *(required)*\
  e.g., `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
* **Client ID** *(required)* — Azure App Registration (Application) ID
* **Client Secret** *(required)* — secret generated under *Certificates & secrets* in the App Registration
* **Scope** *(required)*\
  e.g., `https://api.businesscentral.dynamics.com/.default`

{% hint style="warning" %}
*Replace `{tenant-id}` in the Access Token URL with the actual Tenant ID GUID. The Azure App Registration must have the **Dynamics 365 Business Central** API permission granted **with admin consent**, and the same App ID must be registered as an admin user inside Business Central (Users → New → S2S Authentication).*
{% endhint %}
{% endtab %}

{% tab title="Sage" %}
Business Connect supports Sage's REST APIs (e.g., Sage 200, Sage X3, Sage Intacct via partner endpoints) where the API is reached through a tenant- and company-scoped base path. Sage authenticates with username/password over HTTPS — there is no OAuth flow on the Business Connect path today.

**ERP context:**

* Sage's API is namespaced by **Tenant** (your Sage subscription) and **Company** (the legal entity / dataset within that tenant)
* The **Base Path** identifies the Sage module being targeted (e.g., `/accounts` for the financials module). Different modules expose different entity sets
* The **API Version** is part of the URL contract — keep it pinned to a known-good version to avoid breaking changes when Sage rolls out updates

**Required fields:**

* **API Base URL** *(required)*\
  e.g., `https://api.sage.com`
* **API Version** *(required)*\
  e.g., `3.1`
* **Base Path** *(required)* — the Sage module path\
  e.g., `/accounts`
* **Tenant Name** *(required)* — your Sage tenant identifier\
  e.g., `your-tenant-name`
* **Company** *(required)* — Sage company / dataset identifier\
  e.g., `your-company-id`

**Authentication Type:** `Basic Auth` or `No Auth`

When using **Basic Auth**, provide:

* **Username** *(required)*
* **Password** *(required)*

{% hint style="info" %}
*Use a dedicated API/integration user in Sage rather than a named human user — Sage tracks API activity against the login used, and tying it to a service account makes audit and rotation easier.*
{% endhint %}
{% endtab %}
{% endtabs %}

***

### Step 3: Selecting the Endpoints to Import

Once the connection is validated, Business Connect queries the ERP instance and lists every available endpoint. ERP APIs are large — Acumatica's `Default` endpoint alone can expose hundreds of entities, and a fully extended Dynamics 365 environment can surface thousands of endpoints. **Step 3 is where you cut that list down to only what your application actually uses.**

{% hint style="warning" %}
*Business Connect can technically import hundreds of endpoints — close to unlimited — but doing so is **strongly discouraged**. Every imported endpoint adds context the AI must reason over during app generation, which directly increases generation cost and latency. Most applications only use a small fraction of the ERP's surface area; import only those.*
{% endhint %}

#### How the selection screen works

* **Grouped by HTTP method, then by name** — endpoints are organized first by type (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) and then alphabetically by endpoint name, making it easy to scan related operations together (e.g., all `GET` reads, all `POST` creates)
* **Per-endpoint checkboxes** — tick the checkbox beside any endpoint to include it in the import
* **Search bar** — filter the list by name to quickly locate the entities you need (e.g., `Customer`, `SalesOrder`, `Item`)
* **Select All / Deselect All** — bulk-toggle the entire (or filtered) list when you need to start from a clean slate or include everything in a small endpoint group

#### Selection guidance

{% hint style="success" %}

* Start by **deselecting all**, then add back only the endpoints your app needs
* Pick endpoints based on the **user stories** the app will support (e.g., "list customers", "create sales order") — not "everything related to sales"
* Prefer **`GET` reads first** — only add `POST`/`PUT`/`PATCH`/`DELETE` for entities the app will actually write to
* If you're unsure whether an endpoint is needed, leave it out — you can always rerun Business Connect later to add more
  {% endhint %}

***

### Step 4: Choosing the Collection

In the final step, pick the **collection** the selected endpoints will be saved into. Collections are the same containers used by the rest of the [External API](/emobiq-ai/readme/external-api.md) flow — you can:

* Save into an **existing collection** to keep all endpoints for one ERP under a single connector
* Create a **new collection** for a clean separation (e.g., one collection per ERP module, or one per app)

Once saved, the imported endpoints behave exactly like any other External API function — they appear in the AI's available toolset during app generation, can be combined with custom External API connections, and can be edited or extended after import.

***

### Tips

{% hint style="success" %}

* Confirm your ERP credentials work outside eMOBIQ AI first (e.g., via the vendor's own API explorer or Postman)
* Use a service account rather than a personal account where possible — credentials persist with the connection
* Keep Client Secrets in a secrets manager and rotate them on the schedule mandated by your ERP vendor
* For OAuth-based ERPs (Acumatica, Dynamics 365), make sure the registered application allows the grant type you select and includes the scopes Business Connect needs
  {% endhint %}

***

### Related

* [External API](/emobiq-ai/readme/external-api.md) — the general-purpose API setup
* [OAuth 2.0](/emobiq-ai/readme/external-api/oauth-2.0.md) — OAuth grant types reference
* [EZ-Connect](/emobiq-ai/readme/external-api/ez-connect.md) — natural-language API setup for prototyping


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.emobiq.com/emobiq-ai/readme/external-api/business-connect.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.