BX-Broker API Docs

Bitrix Broker Platform là hệ thống Microservice Gateway đa cổng (Multi-Tenant Broker) được thiết kế đặc biệt cho việc gom đệm batch, khống chế tần suất REST API limit và xử lý các tác vụ khối lượng lớn (Heavy Tasks) giữa các hệ thống bên ngoài / Bitrix Workflows với Bitrix24 CRM.

📊 Bảng thông số ước tính chịu tải theo cấu hình phần cứng Server:

API Proxy hàng đợi chính của hệ thống. Tiếp nhận các message chứa target_url và đẩy lên Bitrix REST API hoặc Webhook đối tác. Mặc định chế độ: async (xử lý nền bất đồng bộ). Ngoài ra hỗ trợ accumulate (gom batch 50 items/delay window) và sync (chờ phản hồi đồng bộ).

{
  "mode": "async",
  "delay": 30,
  "callback_url": "https://your-webhook.com/callback",
  "messages": [
    {
      "target_url": "crm.deal.add",
      "auth_mode": "oauth2",
      "body": {
        "fields": {
          "TITLE": "Cơ hội kinh doanh mới qua Proxy",
          "OPPORTUNITY": 5000,
          "CURRENCY_ID": "VND"
        }
      }
    }
  ]
}

{
  "success": true,
  "mode": "async",
  "domain": "demo.bitrix24.com",
  "jobId": "heavy_job_1786073800100",
  "totalMessages": 1,
  "totalChunks": 1,
  "subJobIds": ["heavy_job_1786073800100"],
  "message": "Job heavy_job_1786073800100 enqueued for background processing."
}

Endpoint tiếp nhận Outbound Webhooks tự động từ Bitrix24 theo mã Key duy nhất. Người dùng chỉ cần dán URL này vào Bitrix24 mà không cần cấu hình thêm tham số nào trong payload. Các thông số xử lý (Target Url, Chế độ async/sync/accumulate, Delay gom, Secret Token) đã được thiết lập và lưu trữ sẵn trong hệ thống Broker khi tạo Webhook Receiver.

https://your-broker-domain.com/api/v1/webhooks/083ac1f91fb8d4f9

{
  "success": true,
  "mode": "async",
  "domain": "demo.bitrix24.com",
  "webhook": "Đồng bộ Deal mới",
  "jobId": "job_1786073800100",
  "message": "Raw Bitrix webhook received & enqueued for async processing."
}

Quản lý các Portal và Webhook Receiver Endpoints trong hệ thống Broker. Yêu cầu Authorization: Bearer <admin_token>.

{
  "success": true,
  "portals": [
    {
      "domain": "eqvn.bitrix24.com",
      "name": "EQVN Demo Portal",
      "authMode": "oauth2",
      "oauthConnected": true,
      "errorNotifyUrl": "https://n8n.dtx.vn/webhook/bitrix-error-alert",
      "enabled": true,
      "webhooks": [
        {
          "id": "wh_6357b94ab19f",
          "key": "6357b94ab19fc00b44a40fe9",
          "name": "Nhận Webhook CRM Deal",
          "targetUrl": "https://n8n.dtx.vn/webhook/deal-update",
          "mode": "async",
          "enabled": true
        }
      ]
    }
  ]
}

Mô-đun mở rộng hỗ trợ đăng ký Event Handlers tự động trong Bitrix24 (CRM Events, Chatbot/ImBot, Telephony/Calls, SMS/Message Services, Tasks) và đăng ký Automation Rules / Robots / BizProc Activities trong quy trình tự động hóa của Bitrix24.

{
  "domain": "demo.bitrix24.com",
  "event": "ONIMBOTMESSAGEADD",
  "handlerUrl": "https://your-broker-domain.com/api/v1/webhooks/083ac1f91fb8d4f9"
}

{
  "domain": "eqvn.bitrix24.com",
  "code": "broker_deal_sync_robot",
  "name": "Robot Đồng Bộ CRM & SPA Sang ERP",
  "description": "Kích hoạt tự động trong CRM Stage Rules khi Deal/SPA đổi trạng thái",
  "handlerUrl": "https://bx-sync.dtx.vn/api/v1/webhooks/6357b94ab19fc00b44a40fe9",
  "authMode": "oauth2",
  "authUserId": 1,
  "filter": {
    "INCLUDE": [
      ["crm", "CCrmDocumentDeal"],
      ["crm", "CCrmDocumentLead"],
      ["crm", "crm.dynamic_128"],
      ["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_128"]
    ]
  },
  "properties": {
    "target_system": {
      "Name": "Hệ thống nhận",
      "Type": "string",
      "Required": "Y",
      "Default": "ERP System"
    }
  },
  "returnProperties": {
    "result_status": {
      "Name": "Trạng thái xử lý",
      "Type": "string"
    }
  }
}

API mở rộng chuyên dụng tạo đơn hàng cho **Bitrix CRM Deals**. Mặc định mode: "async".

{
  "mode": "accumulate",
  "delay": 30,
  "items": [
    {
      "workflow_id": "wf_deal_101",
      "document_id[2]": "DEAL_1234",
      "properties": {
        "orderTopic": "Đơn hàng Deal #1234",
        "amount": 1500,
        "currency": "VND",
        "createPayment": "Y"
      }
    }
  ]
}

{
  "success": true,
  "orderType": "deal",
  "mode": "accumulate",
  "domain": "demo.bitrix24.com",
  "totalOrders": 1,
  "delay": 30,
  "message": "Enqueued 1 DEAL order(s) into batch accumulator (Flush window: 30s or max 50 items)."
}

API mở rộng chuyên dụng tạo đơn hàng cho **Bitrix Smart Process Automation (SPA)**. Mặc định mode: "async".

{
  "mode": "accumulate",
  "delay": 30,
  "items": [
    {
      "workflow_id": "wf_spa_202",
      "document_id[2]": "DYNAMIC_1052_5001",
      "properties": {
        "orderTopic": "Đơn hàng SPA #5001",
        "amount": 2500,
        "createPayment": "Y"
      }
    }
  ]
}

{
  "success": true,
  "orderType": "spa",
  "mode": "accumulate",
  "domain": "demo.bitrix24.com",
  "totalOrders": 1,
  "delay": 30,
  "message": "Enqueued 1 SPA order(s) into batch accumulator (Flush window: 30s or max 50 items)."
}