API और Webhooks: TenancyDesk को अपने सिस्टम के साथ एकीकृत करना

एंटरप्राइज़-ग्रेड REST API और रीयल-टाइम Webhooks TenancyDesk और आपके मौजूदा व्यावसायिक सिस्टम के बीच सहज एकीकरण सक्षम करते हैं। कस्टम वर्कफ़्लो बनाएं, डेटा सिंक स्वचालित करें, और शक्तिशाली एकीकरण बनाएं।

API अवलोकन

आर्किटेक्चर

RESTful API उद्योग मानकों का पालन करता है:

• संसाधन-आधारित URLs (/deals, /parties, /documents)
• HTTP मेथड्स: GET, POST, PUT, PATCH, DELETE
• JSON अनुरोध/प्रतिक्रिया बॉडी
• मानक HTTP स्टेटस कोड
• OpenAPI 3.0 स्पेसिफिकेशन उपलब्ध

बेस URL: https://api.tenancydesk.com/v1/

API दस्तावेज़ीकरण: https://docs.tenancydesk.com/api (इंटरैक्टिव Swagger UI)

---

प्रमाणीकरण

API Keys (अनुशंसित)

API key जनरेट करें:

1. सेटिंग्स → एकीकरण → API Keys
2. नई API Key जनरेट करें पर क्लिक करें
3. नाम: "Production Integration" (वर्णनात्मक)
4. स्कोप: अनुमतियां चुनें (read:deals, write:parties, आदि)
5. तुरंत key कॉपी करें (केवल एक बार दिखाई देती है)

प्रमाणीकरण हेडर:

curl -H "Authorization: Bearer sk_live_abc123xyz..." \
  https://api.tenancydesk.com/v1/deals

सुरक्षा:

• सुरक्षित रूप से स्टोर करें (environment variables, कोड में नहीं)
• हर 90 दिन में रोटेट करें
• dev/staging/prod के लिए अलग-अलग keys उपयोग करें
• समझौता होने पर तुरंत रिवोक करें

JWT Bearer Tokens (OAuth 2.0 - Enterprise)

उपयोगकर्ता-संदर्भ ऑपरेशन के लिए:

1. OAuth फ्लो के माध्यम से एक्सेस टोकन प्राप्त करें
2. Authorization हेडर में शामिल करें
3. टोकन समाप्ति: 1 घंटा (रिफ्रेश टोकन: 7 दिन)

कब उपयोग करें: ऐसे ऐप्स बनाते समय जहां उपयोगकर्ता अपने TenancyDesk खातों से प्रमाणित करते हैं

---

कोर API Endpoints

Deals API

सभी सौदों की सूची:

GET /v1/deals?status=active&limit=50&offset=0

Response 200:
{
  "data": [
    {
      "id": "deal_abc123",
      "property_address": "Unit 1205, Churchill Tower, Business Bay",
      "tenant_name": "राजेश कुमार",
      "annual_rent": 85000,
      "status": "active",
      "ejari_number": "12345678",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 127,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

सौदा बनाएं:

POST /v1/deals
Content-Type: application/json

{
  "property_address": "Unit 1205, Churchill Tower",
  "tenant": {
    "name": "राजेश कुमार",
    "emirates_id": "784-1988-1234567-1",
    "mobile": "+971501234567"
  },
  "annual_rent": 85000,
  "start_date": "2025-02-01",
  "payment_schedule": "4_cheques"
}

Response 201:
{
  "data": {
    "id": "deal_abc123",
    "status": "draft",
    ...
  }
}

सौदे का विवरण प्राप्त करें:

GET /v1/deals/{deal_id}

Response 200: नेस्टेड parties, documents, payments के साथ पूर्ण सौदा ऑब्जेक्ट

सौदा अपडेट करें:

PATCH /v1/deals/{deal_id}

{
  "annual_rent": 90000,
  "status": "active"
}

Parties API

किरायेदार बनाएं:

POST /v1/parties/tenants

{
  "name": "प्रिया शर्मा",
  "emirates_id": "784-1990-2345678-2",
  "mobile": "+971509876543",
  "email": "priya@email.com"
}

पार्टियां खोजें:

GET /v1/parties?search=राजेश&type=tenant&limit=20

Documents API

दस्तावेज़ अपलोड करें:

POST /v1/deals/{deal_id}/documents
Content-Type: multipart/form-data

file: @emirates-id-front.pdf
category: tenant_emirates_id

Response 201:
{
  "data": {
    "id": "doc_xyz789",
    "category": "tenant_emirates_id",
    "filename": "emirates-id-front.pdf",
    "extracted_data": {
      "name": "राजेश कुमार",
      "id_number": "784-1988-1234567-1",
      "expiry_date": "2028-12-31"
    },
    "verification_status": "verified"
  }
}

Payments API

भुगतान अनुसूची सूचीबद्ध करें:

GET /v1/deals/{deal_id}/payments

Response: देय तिथियों, राशियों, स्थिति के साथ भुगतान किस्तों की सरणी

भुगतान को प्राप्त के रूप में चिह्नित करें:

PATCH /v1/payments/{payment_id}

{
  "status": "paid",
  "paid_date": "2025-02-01",
  "transaction_ref": "CHQ-12345"
}

---

रेट लिमिट्स

API एक्सेस केवल Enterprise प्लान पर उपलब्ध है। डिफ़ॉल्ट रेट लिमिट:

रेट लिमिट हेडर्स (हर प्रतिक्रिया में लौटाए जाते हैं):

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640000000

429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "रेट लिमिट पार हो गई। 60 सेकंड बाद पुनः प्रयास करें।",
    "retry_after": 60
  }
}

सर्वोत्तम प्रथा: 429 प्राप्त होने पर एक्सपोनेंशियल बैकऑफ़ लागू करें

---

Webhooks

अवलोकन

रीयल-टाइम नोटिफिकेशन जब TenancyDesk में इवेंट होते हैं। कोई पोलिंग आवश्यक नहीं।

डिलीवरी गारंटी: स्वचालित पुनः प्रयास के साथ कम से कम एक बार डिलीवरी

सिग्नेचर वेरिफिकेशन: सुरक्षा के लिए HMAC-SHA256

Webhook सेटअप

1. Webhook endpoint बनाएं (आपका सर्वर):

# Flask उदाहरण
from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    # सिग्नेचर सत्यापित करें
    signature = request.headers.get('X-TenancyDesk-Signature')
    payload = request.data

    # अपेक्षित सिग्नेचर की गणना करें
    secret = 'your_webhook_secret'
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if signature != expected:
        return 'अमान्य सिग्नेचर', 401

    # इवेंट प्रोसेस करें
    event = request.json
    if event['type'] == 'payment.overdue':
        send_reminder(event['data'])

    return 'OK', 200

2. TenancyDesk में Webhook रजिस्टर करें:

POST /v1/webhooks

{
  "url": "https://your-domain.com/webhook",
  "events": ["payment.overdue", "deal.status_changed"],
  "description": "भुगतान रिमाइंडर के लिए प्रोडक्शन webhook"
}

Response 201:
{
  "data": {
    "id": "wh_abc123",
    "url": "https://your-domain.com/webhook",
    "secret": "whsec_xyz789...",  // सिग्नेचर वेरिफिकेशन के लिए उपयोग करें
    "events": ["payment.overdue", "deal.status_changed"],
    "status": "active"
  }
}

Webhook इवेंट्स

TenancyDesk छह श्रेणियों में 21 इवेंट प्रकार भेजता है।

सौदा इवेंट्स (5):

• deal.created - नया सौदा बनाया गया
• deal.updated - सौदे का विवरण बदला
• deal.status_changed - सौदे की स्थिति बदली (जैसे Active में जाना)
• deal.completed - सौदा पूर्ण हुआ
• deal.cancelled - सौदा रद्द हुआ

भुगतान इवेंट्स (4):

• payment.created - भुगतान शेड्यूल प्रविष्टि बनाई गई
• payment.received - भुगतान paid के रूप में चिह्नित
• payment.overdue - भुगतान की देय तिथि चूक गई
• payment.bounced - चेक बाउंस हुआ

दस्तावेज़ इवेंट्स (4):

• document.uploaded - नया दस्तावेज़ जोड़ा गया
• document.verified - दस्तावेज़ सत्यापित
• document.rejected - वेरिफिकेशन विफल
• document.expiring - दस्तावेज़ जल्द समाप्त हो रहा

पक्ष इवेंट्स (3):

• party.created - पक्ष जोड़ा गया (किरायेदार या मालिक)
• party.updated - पक्ष का विवरण बदला
• party.kyc_completed - पक्ष KYC पूर्ण

कार्य इवेंट्स (3):

• task.created - कार्य बनाया गया
• task.completed - कार्य पूर्ण हुआ
• task.overdue - कार्य देय तिथि से चूका

कंप्लायंस इवेंट्स (2):

• compliance.issue_created - कंप्लायंस समस्या मिली
• compliance.issue_resolved - कंप्लायंस समस्या हल हुई

Ejari/Tawtheeq पंजीकरण के लिए कोई समर्पित webhook इवेंट नहीं है — TenancyDesk सीधे DLD के साथ एकीकृत नहीं होता। जब आपकी टीम पंजीकरण संख्या दर्ज करती है या किसी डील की पंजीकरण स्थिति अपडेट करती है, तो वह बदलाव ऊपर दिए गए deal.updated इवेंट के माध्यम से डिलीवर होता है।

Webhook पेलोड स्ट्रक्चर

मानक एनवेलप:

{
  "id": "evt_abc123",
  "type": "payment.overdue",
  "created_at": "2025-12-26T10:30:00Z",
  "data": {
    "deal_id": "deal_xyz789",
    "payment_id": "pay_123",
    "tenant_name": "राजेश कुमार",
    "amount": 21250,
    "due_date": "2025-01-01",
    "cheque_number": "CHQ-001"
  },
  "company_id": "comp_abc"
}

रिट्राई लॉजिक

TenancyDesk Hook0 उद्योग मानक का पालन करता है:

तेज़ रिट्राई (पहले 10 प्रयास):

• प्रयास 1: तुरंत
• प्रयास 2: 5 सेकंड
• प्रयास 3: 25 सेकंड
• प्रयास 4: 125 सेकंड (2 मिनट)
• प्रयास 5-10: 5 मिनट तक एक्सपोनेंशियल बैकऑफ़

धीमी रिट्राई (प्रयास 11-60):

• हर 1 घंटे
• कुल 60 प्रयास तक (2.5 दिन)

छोड़ने के बाद: 60 विफल प्रयास

आपके endpoint को चाहिए:

• 5 सेकंड के भीतर प्रतिक्रिया दें
• 200-299 स्टेटस कोड लौटाएं
• असिंक्रोनस रूप से प्रोसेस करें (प्रतिक्रिया ब्लॉक न करें)

सुरक्षा

Webhook सिग्नेचर वेरिफिकेशन (HMAC-SHA256):

हेडर: X-TenancyDesk-Signature

अपेक्षित सिग्नेचर की गणना करें:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# उपयोग
if not verify_webhook(request.body, request.headers['X-TenancyDesk-Signature'], webhook_secret):
    return 'अनधिकृत', 401

सुरक्षा सर्वोत्तम प्रथाएं:

• हमेशा सिग्नेचर सत्यापित करें
• केवल HTTPS उपयोग करें (HTTP होने पर webhooks अस्वीकृत)
• आइडेम्पोटेंसी लागू करें (समान इवेंट दो बार डिलीवर हो सकता है)
• डीबगिंग के लिए सभी webhook प्रयास लॉग करें

---

सामान्य एकीकरण पैटर्न

पैटर्न 1: सौदों को CRM में सिंक करें

उपयोग केस: हर TenancyDesk सौदा स्वचालित रूप से Zoho CRM में बनता है

कार्यान्वयन:

1. deal.created webhook की सदस्यता लें
2. प्राप्त होने पर, Zoho CRM API कॉल करें:

   # TenancyDesk webhook हैंडलर
   if event['type'] == 'deal.created':
       deal = event['data']
       zoho.create_lead({
           'name': deal['tenant_name'],
           'value': deal['annual_rent'],
           'source': 'TenancyDesk'
       })
   

पैटर्न 2: अकाउंटिंग स्वचालित करें

उपयोग केस: भुगतान प्राप्त → QuickBooks में इनवॉइस बनाएं

कार्यान्वयन:

1. payment.received की सदस्यता लें
2. इनवॉइस बनाने के लिए QuickBooks API कॉल करें
3. QB इनवॉइस ID के साथ सौदा अपडेट करें

पैटर्न 3: कस्टम डैशबोर्ड

उपयोग केस: रीयल-टाइम एनालिटिक्स डैशबोर्ड

कार्यान्वयन:

1. हर 5 मिनट /deals endpoint पोल करें
2. डेटा एग्रीगेट करें (स्टेज द्वारा सौदे, राजस्व)
3. कस्टम डैशबोर्ड में प्रदर्शित करें

---

त्रुटि हैंडलिंग

HTTP स्टेटस कोड:

• 200 OK - सफलता
• 201 Created - संसाधन बनाया गया
• 400 Bad Request - अमान्य पैरामीटर
• 401 Unauthorized - अमान्य/गायब API key
• 403 Forbidden - अपर्याप्त अनुमतियां
• 404 Not Found - संसाधन मौजूद नहीं
• 422 Unprocessable Entity - वैलिडेशन विफल
• 429 Too Many Requests - रेट लिमिट पार
• 500 Internal Server Error - सर्वर समस्या (पुनः प्रयास करें)

त्रुटि प्रतिक्रिया फॉर्मेट:

{
  "error": {
    "code": "validation_failed",
    "message": "वार्षिक किराया 0 से अधिक होना चाहिए",
    "field": "annual_rent",
    "docs_url": "https://docs.tenancydesk.com/api/errors#validation"
  }
}

त्रुटियों को संभालना:

response = requests.post(url, headers=headers, json=data)

if response.status_code == 422:
    error = response.json()['error']
    print(f"वैलिडेशन विफल {error['field']} पर: {error['message']}")
elif response.status_code == 429:
    retry_after = int(response.headers['Retry-After'])
    time.sleep(retry_after)
    # अनुरोध पुनः प्रयास करें
elif response.status_code >= 500:
    # एक्सपोनेंशियल बैकऑफ़ रिट्राई
    pass

---

सर्वोत्तम प्रथाएं

प्रोडक्शन-तैयार एकीकरण:

1. त्रुटि हैंडलिंग: सभी HTTP त्रुटियां पकड़ें, रिट्राई लॉजिक लागू करें
2. आइडेम्पोटेंसी: POST अनुरोधों के लिए Idempotency-Key हेडर उपयोग करें
3. रेट लिमिटिंग: रेट लिमिट का सम्मान करें, बैकऑफ़ लागू करें
4. Webhook सुरक्षा: हमेशा HMAC सिग्नेचर सत्यापित करें
5. लॉगिंग: डीबगिंग के लिए सभी API कॉल लॉग करें
6. मॉनिटरिंग: API लेटेंसी और एरर रेट ट्रैक करें
7. वर्जनिंग: विशिष्ट वर्जन पिन करते समय API वर्जन हेडर उपयोग करें

प्रोडक्शन-ग्रेड अनुरोध उदाहरण:

import requests
import time

def create_deal_with_retry(deal_data, max_retries=3):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
        'Idempotency-Key': f'deal_{uuid4()}',
        'X-API-Version': '2025-12-01'
    }

    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://api.tenancydesk.com/v1/deals',
                headers=headers,
                json=deal_data,
                timeout=10
            )

            if response.status_code == 201:
                return response.json()['data']
            elif response.status_code == 429:
                wait = int(response.headers.get('Retry-After', 60))
                time.sleep(wait)
                continue
            elif response.status_code >= 500:
                time.sleep(2 ** attempt)  # एक्सपोनेंशियल बैकऑफ़
                continue
            else:
                response.raise_for_status()

        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("अधिकतम रिट्राई सीमा पार")

---

मज़बूत एकीकरण बनाएं जो आपके व्यवसाय के साथ स्केल हों। TenancyDesk API को स्थापित क्लाउड इंफ्रास्ट्रक्चर पर प्रोडक्शन-ग्रेड एकीकरण के लिए डिज़ाइन किया गया है।