---
title: Panduan Endpoint REST API XAPI untuk Konfigurasi 3CX
description: "Dokumentasi ini memberikan panduan lengkap mengenai spesifikasi endpoint [REST API](https://id.wikipedia.org/wiki/REST) untuk konfigurasi sistem PBX 3CX. API ini memungkinkan Anda untuk mengelola otentikasi, departemen, pengguna, sistem ekstensi, dan pengecekan versi sistem secara terprogram. ## 🔗 Base URL & Environment Semua permintaan…"
url: "https://solusipbx.id/pusat-bantuan/panduan-endpoint-rest-api-untuk-konfigurasi-3cx/"
updated: "2026-07-09"
category: Developer
---

# Panduan Endpoint REST API XAPI untuk Konfigurasi 3CX

Dokumentasi ini memberikan panduan lengkap mengenai spesifikasi endpoint [REST API](https://id.wikipedia.org/wiki/REST) untuk konfigurasi sistem PBX 3CX. API ini memungkinkan Anda untuk mengelola otentikasi, departemen, pengguna, sistem ekstensi, dan pengecekan versi sistem secara terprogram.

## 🔗 Base URL & Environment

Semua permintaan API ditujukan ke FQDN (Fully Qualified Domain Name) dari instance 3CX Anda:

`https://{{PBX_FQDN}}`

## 📑 Daftar Isi (Table of Contents)

1. Authentication / Authorization
2. Departemetns Management
3. Users Management
4. System & Utilities
5. Active Calls
6. Reports & Call History
7. Trunk & Routing
8. Phonebok & Contact
9. System Settings & Utility
10. Event Logs

## 1. Authentication / Authorization

### Endpoint: Get Token

Mengimplementasikan otentikasi dan memberikan `access_token` berdasarkan peran (role) yang sesuai.

- **HTTP Method:** `POST`
- **URL Endpoint:** `https://{{PBX_FQDN}}/connect/token`
- **Authentication:** Wajib (Basic Authentication)
- **Content-Type:** `application/x-www-form-urlencoded`

#### Request Body

| **Parameter** | **Tipe** | **Keterangan** |
| --- | --- | --- |
| `client_id` | String (Required) | Nilai tetap: `server_principal_id`. |
| `client_secret` | String (Required) | Kunci rahasia (*secret key*) yang didapatkan setelah mengatur Service Principal. |
| `grant_type` | String (Required) | Nilai tetap: `client_credentials`. |

#### Response Contoh (200 OK)

    JSON

```
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": null
}
}
```

#### Error Response (401 Unauthorized)

    JSON

```
{
  "error": "unauthorized",
  "error_description": "The request requires valid user authentication."
}
```

> 💡 **Tip BetterDocs:** `access_token` ini berlaku selama 3600 detik (1 jam). Anda wajib melakukan otentikasi ulang setelah token kedaluwarsa.

## 2. Departments Management

### Endpoint: Check if Department Exists

Memeriksa apakah departemen dengan nama tertentu sudah terdaftar di sistem 3CX untuk menghindari duplikasi sebelum membuat baru.

- **HTTP Method:** `GET`
- **URL Endpoint:** `https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '{Nama_Departemen}'`
- **Contoh URL:** `https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '3CX Test'`

#### Response Contoh - Jika Departemen Ditemukan (200 OK)

    JSON

```
{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
  "value": [
    {
      "Name": "DEFAULT",
      "IsDefault": true,
      "HasMembers": true,
      "Number": "GRP0000",
      "Id": 28
    }
  ]
}
```

### Endpoint: Create a Department

Membuat departemen baru di dalam sistem 3CX dengan konfigurasi bahasa, zona waktu, dan batas nomor layanan panggilan.

- **HTTP Method:** `POST`
- **URL Endpoint:** `https://{{PBX_FQDN}}/xapi/v1/Groups`
- **Content-Type:** `application/json`

#### Request Body Contoh

    JSON

```
{
  "AllowCallService": true,
  "Id": 0,
  "Language": "EN",
  "Name": "3CX Test",
  "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",
  "Props": {
    "LiveChatMaxCount": 20,
    "PersonalContactsMaxCount": 500,
    "PromptsMaxCount": 10,
    "SystemNumberFrom": "300",
    "SystemNumberTo": "319",
    "TrunkNumberFrom": "340",
    "TrunkNumberTo": "345",
    "UserNumberFrom": "320",
    "UserNumberTo": "339"
  },
  "TimeZoneId": "51",
  "DisableCustomPrompt": true
}
```

#### Response Contoh (201 Created)

Membawa header `Location` yang berisi URL ke entitas departemen yang baru dibuat.

    JSON

```
{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups/$entity",
  "Name": "3CX Test",
  "Id": 35,
  "Language": "EN",
  "Props": {
    "LiveChatMaxCount": 20,
    "PersonalContactsMaxCount": 500,
    "PromptsMaxCount": 10
  },
  "TimeZoneId": "51"
}
```

#### Error Response - Nama Duplikat (400 Bad Request)

    JSON

```
{
  "error": {
    "message": "Name:nWARNINGS.XAPI.DUPLICATE",
    "details": [
      {
        "target": "Name",
        "message": "WARNINGS.XAPI.DUPLICATE"
      }
    ]
  }
}
```

### Endpoint: Update Department Details

Mengubah properti atau detail pengaturan dari departemen yang sudah ada.

- **HTTP Method:** `PATCH`
- **URL Endpoint:** `https://{{PBX_FQDN}}/xapi/v1/Groups({Id_Departemen})`
- **Contoh URL:** `https://{{PBX_FQDN}}/xapi/v1/Groups(123)`

#### Request Body Contoh

    JSON

```
{
  "Id": 123,
  "Name": "3CX Test Modif",
  "Props": {
    "LiveChatMaxCount": 25,
    "PersonalContactsMaxCount": 600
  }
}
```

- **Response Sukses:** `204 No Content` (Tanpa body respon).

### Endpoint: Delete a Department

Menghapus departemen dari sistem 3CX secara permanen berdasarkan ID yang ditentukan.

- **HTTP Method:** `POST`
- **URL Endpoint:** `https://{{PBX_FQDN}}/xapi/v1/Groups/Pbx.DeleteCompanyById`

#### Request Body

    JSON

```
{
  "id": 123
}
```

- **Response Sukses:** `204 No Content`
- **Response Gagal (404 Not Found):** `{"error": "Department not found"}`

## 3. Users Management

### Endpoint: Get List of Users

Mengambil data seluruh pengguna terdaftar, lengkap dengan ID, nama, nomor ekstensi, email, dan keanggotaan grup/departemen mereka.

- **HTTP Method:** `GET`
- **URL Endpoint:** `https://{{PBX_FQDN}}/xapi/v1/Users`

#### Query Parameters (Opsional untuk Pagination & Filter)

- `$top`: Membatasi jumlah user yang dikembalikan (Default: 100).
- `$skip`: Melompati sejumlah data untuk keperluan pagination (Default: 0).
- `$orderby`: Mengurutkan data (Contoh: diurutkan berdasarkan `Number`).
- `$select`: Memilih kolom spesifik (Contoh: `Id,FirstName,LastName,Number,EmailAddress`).

## 4. System & Utilities

### Endpoint: Get Default Group Properties

Mengambil properti bawaan dari grup bernama "DEFAULT" guna melihat konfigurasi dasar sistem dan perutean panggilan (*call routing*).

- **HTTP Method:** `GET`
- **URL Endpoint:** `https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq 'DEFAULT'`

#### Response Contoh (200 OK)

    JSON

```
{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
  "value": [
    {
      "Name": "DEFAULT",
      "IsDefault": true,
      "HasMembers": true,
      "Number": "GRP0000",
      "Id": 95,
      "OfficeRoute": {
        "Route": { "Number": "101", "To": "Extension", "Name": "sysadmin" }
      },
      "OutOfOfficeRoute": {
        "Route": { "Number": "101", "To": "VoiceMail", "Name": "sysadmin" }
      }
    }
  ]
}
```

### Endpoint: Get 3CX Version & Connection Test

Endpoint utilitas untuk memeriksa status koneksi API sekaligus mengetahui versi sistem 3CX yang sedang berjalan.

- **HTTP Method:** `GET` (atau metode pengecekan standar)
- **Response Header Utama:**

  Perhatikan bagian Header saat sukses mendapat respons. Terdapat properti:

  `X-3CX-Version: 20.0.x.x` (Menandakan versi 3CX aktif).

*Dokumentasi ini disadur dari panduan resmi spesifikasi API 3CX.*

### 5. Active Calls

Endpoint ini digunakan untuk memantau panggilan yang sedang aktif secara real-time.

**Endpoint: Get Active Calls** Mengambil daftar semua panggilan yang sedang berlangsung di sistem 3CX.

- **HTTP Method**: GET
- **URL Endpoint**: https://{{PBX_FQDN}}/xapi/v1/ActiveCalls
- **Query Parameters** (Opsional):
  - $top: Jumlah maksimal data (default: 100)
  - $skip: Pagination (default: 0)
  - $orderby: Urutkan data (contoh: EstablishedAt desc)
  - $filter: Filter data (contoh: Callee eq '101')

**Response Contoh (200 OK)**

    JSON

```
{
  "@odata.context": "https://{{PBX_FQDN}}/xapi/v1/$metadata#ActiveCalls",
  "value": [
    {
      "Id": "12345",
      "Caller": "+6281234567890",
      "Callee": "101",
      "EstablishedAt": "2026-07-07T07:45:12Z",
      "Duration": 125,
      "Direction": "Inbound",
      "Queue": null,
      "Status": "Connected"
    }
  ]
}
```

Catatan: Endpoint ini sangat berguna untuk real-time monitoring (dashboard call center, wallboard, dll).

### 6. Reports & Call History

XAPI menyediakan beberapa endpoint khusus untuk mengambil data laporan dan riwayat panggilan.

**Endpoint: Call History View** Mengambil riwayat panggilan lengkap.

- **HTTP Method**: GET
- **URL Endpoint**: https://{{PBX_FQDN}}/xapi/v1/CallHistoryView
- **Query Parameters Penting**:
  - from & to (format ISO: 2026-07-01T00:00:00Z)
  - $top, $skip, $orderby, $filter

**Endpoint Lain untuk Reports** (contoh):

- /xapi/v1/ReportCallLogData/Pbx.GetCallLogData(...)
- /xapi/v1/ReportAbandonedQueueCalls/Pbx.GetAbandonedQueueCallsData(...)
- /xapi/v1/ReportQueuePerformanceOverview/...
- /xapi/v1/ReportAgentLoginHistory/...

**Contoh Penggunaan** (dengan query):

GET https://{{PBX_FQDN}}/xapi/v1/CallHistoryView?$top=100&$skip=0&from=2026-07-01T00:00:00Z&to=2026-07-07T23:59:59Z

Tips: Gunakan Developer Tools (F12) di Web Console 3CX saat membuka report untuk melihat query parameter yang tepat.

### 7. Trunks & Routing

**Endpoint: Get Trunks** Mengambil daftar SIP Trunks yang terdaftar.

- **HTTP Method**: GET
- **URL Endpoint**: https://{{PBX_FQDN}}/xapi/v1/Trunks
- **Endpoint: Inbound/Outbound Rules**

- /xapi/v1/InboundRules
- /xapi/v1/OutboundRules

**Contoh Create/Update Trunk** (POST/PATCH):

   JSON

```
{
  "Name": "SIP Provider",
  "Host": "sip.provider.com",
  "Port": 5060,
  "Type": "SIP",
  ...
} Catatan: Pengelolaan routing (DID, Caller ID rules) biasanya melalui endpoint terkait Routes atau DialPlans.
```

### 8. Phonebook & Contacts

**Endpoint: Global Phonebook**

- **GET** → https://{{PBX_FQDN}}/xapi/v1/Phonebook
- **POST** → Tambah kontak baru
- **PATCH** → Update kontak
- **DELETE** → Hapus kontak

**Contoh Request Body (Create Contact)**:

    JSON

```
{
  "FirstName": "John",
  "LastName": "Doe",
  "Number": "+628123456789",
  "Email": "john@example.com",
  "Company": "PT ABC"
}
```

Endpoint ini sangat berguna untuk **sinkronisasi kontak** dengan CRM.

### 9. System Settings & Utilities

**Endpoint: System Parameters** Mengambil dan mengubah pengaturan sistem secara umum.

- **GET**: https://{{PBX_FQDN}}/xapi/v1/SystemParameters
- **PATCH**: Update parameter tertentu (contoh: recording settings, security, dll).

**Endpoint Lain**:

- /xapi/v1/Defs → Mendapatkan definisi sistem (enums, options)
- /xapi/v1/Groups?$filter=Name eq 'DEFAULT' → Default Group Properties (sudah ada di dokumentasi kamu)

### 10. Event Logs

**Endpoint: Get Event Logs** Mengambil log sistem dan event.

- **HTTP Method**: GET
- **URL Endpoint**: https://{{PBX_FQDN}}/xapi/v1/EventLogs
- **Query Parameters**: $top, $skip, $filter (berdasarkan waktu, severity, dll), $orderby=Timestamp desc

 

**Response Contoh**:

    JSON

```
{
  "value": [
    {
      "Timestamp": "2026-07-07T07:50:00Z",
      "Severity": "Info",
      "Component": "CallManager",
      "Message": "Call established between 101 and +62812..."
    }
  ]
}
```

### Rekomendasi Tambahan

1. **Swagger Reference** Akses dokumentasi lengkap langsung dari PBX kamu: https://{{PBX_FQDN}}/xapi/v1/swagger.yaml
2.
3. **Best Practice**:
   - Selalu gunakan **System Owner** role untuk akses maksimal.
   - Implementasikan **refresh token logic** karena token expired setiap 1 jam.
   - Untuk report besar, gunakan pagination ($top + $skip) agar tidak timeout.
   - Gunakan **F12 Network tab** di 3CX Web Console untuk "spy" endpoint dan parameter yang digunakan sistem.