सामग्री पर जाएँ
मुफ़्त में शुरू करें
← All articles
Setup

डेवलपर संदर्भ: REST API और MCP

संपूर्ण Sellio API संदर्भ: API-key प्रमाणीकरण, फ़ील्ड खोज, REST एंडपॉइंट, त्रुटि प्रारूप, रेट लिमिट, और AI एजेंट के लिए MCP सर्वर।

HTTP के माध्यम से Sellio को इंटीग्रेट करें या MCP के माध्यम से अपने AI एजेंट को जोड़ें। किसी भी तरह से, यह वही key, वही tenant स्कोप और वही रेट लिमिट है। किसी भी ऑब्जेक्ट के फ़ील्ड खोजें और मिनटों में रिकॉर्ड पढ़ना और लिखना शुरू करें।

💡 www.selliocrm.com/developers पर एक सार्वजनिक डेवलपर पोर्टल भी है, इसी संदर्भ, आउटबाउंड वेबहुक, डाउनलोड करने के लिए OpenAPI स्पेक और एक Postman कलेक्शन के साथ।

प्रमाणीकरण

हर अनुरोध Authorization: Bearer हेडर में एक API key ले जाता है। वह key स्वामी tenant की पहचान करती है, इसलिए सब कुछ स्वचालित रूप से उसी तक सीमित हो जाता है। ब्राउज़र में key को कभी उजागर न करें; इसे केवल सर्वर-साइड पर उपयोग करें। आप Settings → API & developers में keys जनरेट और रद्द करते हैं।

curl -H "Authorization: Bearer sk_live_..." \
  https://www.selliocrm.com/api/v1/objects

Key स्कोप

जब आप Settings → API & developers में key जनरेट करते हैं तो आप इसका स्कोप चुनते हैं। प्रत्येक इंटीग्रेशन को केवल वह एक्सेस दें जिसकी उसे आवश्यकता है। सीमाएँ REST और MCP दोनों में एक ही तरह लागू होती हैं, क्योंकि दोनों सतहें एक ही key और एक ही नियंत्रण का उपयोग करती हैं।

  • केवल पढ़ना: key डेटा पढ़ती है लेकिन बना, संपादित या हटा नहीं सकती। यह REST में POST, PATCH और DELETE को और MCP में create_record, update_record और delete_record टूल को अवरुद्ध करती है। लिखने या हटाने के प्रयासों को { "error": "errors.apiKeyReadOnly" } के साथ 403 मिलता है।
  • ऑब्जेक्ट तक सीमित: वे ऑब्जेक्ट चुनें जिन्हें key एक्सेस कर सकती है। सूची से बाहर का कोई भी ऑब्जेक्ट { "error": "errors.apiKeyObjectDenied" } के साथ 403 लौटाता है। ऑब्जेक्ट सूची (GET /api/v1/objects और list_objects टूल) पहले से ही स्कोप के अनुसार फ़िल्टर होकर आती है, और गतिविधियाँ (/api/v1/activities) activity ऑब्जेक्ट के रूप में गिनी जाती हैं: key उन तक तभी पहुँचती है जब activity स्कोप में हो।
  • हटाने की अनुमति: डिफ़ॉल्ट रूप से एक key कभी नहीं हटाती, भले ही लेखन सक्षम हो। key जनरेट करते समय आप DELETE /api/v1/{object}/{id} और delete_record MCP टूल को सक्षम करने के लिए हटाना चालू कर सकते हैं। उस स्कोप के बिना, हटाना { "error": "errors.apiKeyDeleteDenied" } के साथ 403 लौटाता है। हटाना सॉफ्ट होता है: रिकॉर्ड ट्रैश में जाते हैं और पुनर्स्थापित किए जा सकते हैं।

बिना स्कोप सेट की गई key (डिफ़ॉल्ट) के पास पहले की तरह सभी ऑब्जेक्ट पर पूर्ण पढ़ने और लिखने की एक्सेस होती है। इस बदलाव से पहले बनाई गई keys तब तक पूर्ण एक्सेस बनाए रखती हैं जब तक आप एक नई स्कोप्ड key जनरेट नहीं करते।

OAuth और कनेक्टेड ऐप्स

जब किसी थर्ड-पार्टी सिस्टम को उपयोगकर्ता की ओर से इंटीग्रेट करने की आवश्यकता हो (ग्राहक द्वारा व्यवस्थापक key पेस्ट किए बिना), तो PKCE के साथ OAuth 2.0 Authorization Code फ़्लो का उपयोग करें। उपयोगकर्ता अनुरोधित स्कोप के साथ एक सहमति स्क्रीन देखता है, स्वीकृत करता है, और ऐप को एक एक्सेस टोकन प्राप्त होता है जो केवल वही कर सकता है जिसकी सहमति दी गई थी। ऐप्स क्यूरेट किए गए होते हैं: डेवलपर client_id और client_secret पाने के लिए ऐप को रजिस्टर और प्रकाशित करता है।

  • उपयोगकर्ता को client_id, redirect_uri (ऐप allowlist के विरुद्ध सटीक मिलान), scope, state और PKCE (code_challenge_method=S256 के साथ code_challenge) के साथ GET /api/oauth/authorize पर रीडायरेक्ट करें। PKCE आवश्यक है।
  • लॉग-इन उपयोगकर्ता सहमति स्क्रीन पर स्वीकृत करता है और CRM code और वही state के साथ वापस रीडायरेक्ट करता है।
  • अपने सर्वर पर, POST /api/oauth/token (grant_type=authorization_code, code_verifier, client_id, client_secret और redirect_uri के साथ) पर code का आदान-प्रदान करके एक एक्सेस टोकन (Bearer, लगभग 1 घंटा) और एक refresh टोकन प्राप्त करें।
  • सहमति तक सीमित Authorization: Bearer at_... के साथ v1 API और MCP सर्वर को कॉल करें। grant_type=refresh_token के साथ नवीनीकरण करें; refresh घुमाया जाता है (उपयोग पर पुराना समाप्त हो जाता है) और पुन: उपयोग परिवार को रद्द कर देता है। POST /api/oauth/revoke पर रद्द करें।
# 1) Consent (the user approves → redirect_uri?code=...&state=...)
GET https://www.selliocrm.com/api/oauth/authorize?response_type=code&client_id=app_...&redirect_uri=https://your-app/callback&scope=records:read%20activities:read&state=abc&code_challenge=...&code_challenge_method=S256

# 2) Exchange the code for tokens (server-side)
curl -X POST https://www.selliocrm.com/api/oauth/token \
  -d grant_type=authorization_code -d code=<authcode> -d code_verifier=<verifier> \
  -d client_id=app_... -d client_secret=secret_... -d redirect_uri=https://your-app/callback

# → { "access_token": "at_...", "token_type": "Bearer", "expires_in": 3600,
#     "refresh_token": "rt_...", "scope": "records:read activities:read" }

OAuth स्कोप: records:read और records:write (सभी ऑब्जेक्ट); records:read:contact और records:write:opportunity (प्रति ऑब्जेक्ट); activities:read और activities:write; objects:read (खोज)। ये keys के समान पढ़ने, लिखने और प्रति-ऑब्जेक्ट प्रवर्तन से मैप होते हैं।

एम्बेडेड विजेट (iframe)

आपका ऐप अपनी खुद की स्क्रीन (एक विजेट) को किसी रिकॉर्ड विवरण पर या डैशबोर्ड पर एम्बेड कर सकता है। विजेट एक sandboxed iframe में चलता है, जो ऐप allowlist पर आपके अपने origin से परोसा जाता है, और widgets:embed स्कोप का अनुरोध करता है। tenant व्यवस्थापक Apps → Installed के अंतर्गत चुनता है कि प्रत्येक विजेट कहाँ दिखाई देता है।

होस्ट विजेट को केवल UI संदर्भ postMessage (sellio:widget:context, संस्करण 1) के माध्यम से भेजता है: recordId, objectApiName, locale, theme और installId। उस संदेश में कोई व्यावसायिक डेटा, टोकन या सीक्रेट नहीं जाता। डेटा पढ़ने या लिखने के लिए, विजेट अपने खुद के टोकन (इंस्टॉल पर दी गई स्कोप) के साथ OAuth API का उपयोग करता है। विजेट केवल sellio:widget:ready (संदर्भ फिर से प्राप्त करने के लिए) और { height } के साथ sellio:widget:resize (अपनी ऊँचाई फिट करने के लिए, सीमित) का जवाब दे सकता है; कोई भी अन्य संदेश अनदेखा किया जाता है।

सुरक्षा: iframe sandboxed और cross-origin है, इसलिए विजेट होस्ट DOM या कुकीज़ तक नहीं पहुँच सकता। होस्ट हर postMessage पर सटीक origin को सत्यापित करता है और embedUrl की हमेशा ऐप allowlist के विरुद्ध जाँच होती है। अपने विजेट में, संदेश केवल तभी स्वीकार करें जब event.origin होस्ट origin हो।

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.selliocrm.com') return; // host only
  const msg = event.data;
  if (!msg || msg.version !== 1) return;
  if (msg.type === 'sellio:widget:context') {
    const { recordId, objectApiName, locale, theme } = msg.payload;
    // data: use the OAuth API with YOUR token (never comes over postMessage)
  }
});
parent.postMessage({ type: 'sellio:widget:ready', version: 1 }, 'https://www.selliocrm.com');

फ़ील्ड खोज

रिकॉर्ड बनाने या अपडेट करने से पहले, ऑब्जेक्ट के फ़ील्ड खोजें: क्या मौजूद है, क्या आवश्यक है, और कौन-से मान एक select स्वीकार करता है। कोई अनुमान नहीं, और किसी मौजूदा रिकॉर्ड की जाँच करने की आवश्यकता नहीं।

REST में, आपको ऑब्जेक्ट और उसके फ़ील्ड मिलते हैं, required, options (select के लिए) और targetObject (lookup के लिए) के साथ:

GET https://www.selliocrm.com/api/v1/objects/contact

# → {
#   "apiName": "contact",
#   "label": "Contact",
#   "fields": [
#     { "apiName": "name",  "label": "Name",   "type": "text",  "required": true },
#     { "apiName": "email", "label": "Email",  "type": "email", "required": false },
#     { "apiName": "source", "label": "Source", "type": "select", "required": true,
#       "options": [ { "value": "site", "label": "Website" },
#                    { "value": "referral", "label": "Referral" } ] },
#     { "apiName": "company", "label": "Company", "type": "lookup",
#       "required": false, "targetObject": "company" }
#   ]
# }

MCP में, describe_object टूल एजेंट को वही फ़ील्ड लौटाता है:

{ "method": "tools/call",
  "params": { "name": "describe_object", "arguments": { "object": "contact" } } }

REST API v1

किसी भी ऑब्जेक्ट के रिकॉर्ड, JSON भेजते और प्राप्त करते हुए। {object} apiName है (उदाहरण के लिए contact, lead, opportunity) और {id} रिकॉर्ड uuid है।

  • GET /api/v1/objects: tenant के ऑब्जेक्ट सूचीबद्ध करें।
  • GET /api/v1/objects/{object}: ऑब्जेक्ट फ़ील्ड (खोज)।
  • GET /api/v1/{object}: रिकॉर्ड सूचीबद्ध और खोजें।
  • GET /api/v1/{object}/{id}: एक रिकॉर्ड।
  • POST /api/v1/{object}: एक रिकॉर्ड बनाएँ।
  • POST /api/v1/{object}/bulk: थोक में बनाएँ (500 तक; प्रति आइटम आंशिक सफलता)।
  • PATCH /api/v1/{object}/{id}: फ़ील्ड अपडेट करें (आंशिक)।
  • PATCH /api/v1/{object}/bulk: थोक में अपडेट करें ({ updates: [{ id, ...fields }] })।
  • DELETE /api/v1/{object}/{id}: हटाएँ (सॉफ्ट, ट्रैश में जाता है; key पर delete स्कोप आवश्यक है)।

सूची पैरामीटर (GET): limit (1 से 500, डिफ़ॉल्ट 50), offset (पेजिनेशन ऑफसेट, डिफ़ॉल्ट 0; बिना पेजिनेशन के कुल total फ़ील्ड में होता है), search (नाम से खोज, उच्चारण और केस असंवेदनशील), order (क्रमबद्ध करने के लिए :asc या :desc के साथ फ़ील्ड) और filter। रिच फ़िल्टर: कई को logical AND के साथ जोड़ने के लिए filter=field:operator:value दोहराएँ (कोई OR नहीं; प्रति कॉल 12 तक)। ऑपरेटर: eq, neq, contains, gt, lt, gte, lte, empty, not_empty (empty और not_empty कोई मान नहीं लेते)। पुराना रूप filter=field:value (बिना ऑपरेटर) अभी भी सटीक समानता का अर्थ रखता है।

# List (limit, offset, search, filter, order)
curl -H "Authorization: Bearer sk_live_..." \
  "https://www.selliocrm.com/api/v1/opportunity?limit=20&order=updated_at:desc&filter=stage:won"

# Rich filters (logical AND: amount >= 1000 AND stage = won)
curl -H "Authorization: Bearer sk_live_..." \
  "https://www.selliocrm.com/api/v1/opportunity?filter=amount:gte:1000&filter=stage:eq:won"

# One record
curl -H "Authorization: Bearer sk_live_..." \
  https://www.selliocrm.com/api/v1/contact/8f3c...

# Create
curl -X POST -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana Souza","email":"ana@acme.com","source":"site"}' \
  https://www.selliocrm.com/api/v1/contact

# Bulk create (partial success per item)
curl -X POST -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"records":[{"name":"Ana"},{"name":"Bruno"}]}' \
  https://www.selliocrm.com/api/v1/contact/bulk
# → { "results": [ { "index": 0, "ok": true, "id": "..." } ], "created": 1, "failed": 0 }

# Update (partial)
curl -X PATCH -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"source":"referral"}' \
  https://www.selliocrm.com/api/v1/contact/8f3c...

# Delete (soft, goes to the trash; requires the delete scope on the key)
curl -X DELETE -H "Authorization: Bearer sk_live_..." \
  https://www.selliocrm.com/api/v1/contact/8f3c...

त्रुटि प्रारूप

त्रुटियाँ मिलान करने वाले HTTP स्टेटस के साथ { "error": "message" } के रूप में JSON लौटाती हैं:

{ "error": "required field: source" }   # HTTP 400
  • 200 और 201: सफलता (बनाने पर 201)।
  • 400: सत्यापन या व्यावसायिक नियम।
  • 401: गायब या अमान्य key।
  • 403: ऑब्जेक्ट के लिए कोई अनुमति नहीं (RBAC), या key स्कोप द्वारा अवरुद्ध (केवल पढ़ना, स्कोप से बाहर का ऑब्जेक्ट, या हटाना सक्षम नहीं)।
  • 404: ऑब्जेक्ट या रिकॉर्ड नहीं मिला (एक मौजूद न रहने वाले id के DELETE/PATCH सहित)।
  • 429: रेट लिमिट पार हो गई (Retry-After हेडर देखें)।

MCP सर्वर (AI एजेंट)

Sellio एक नेटिव MCP (Model Context Protocol) सर्वर प्रदान करता है ताकि आपका AI एजेंट CRM को सुरक्षित रूप से पढ़ और लिख सके। यह वही API key, वही रेट लिमिट, वही सत्यापन और वही RBAC है। सर्वर URL https://www.selliocrm.com/api/mcp है।

  • list_objects: tenant के ऑब्जेक्ट सूचीबद्ध करें।
  • describe_object: किसी ऑब्जेक्ट के फ़ील्ड (required, प्रकार, options)।
  • list_records: रिकॉर्ड सूचीबद्ध और खोजें।
  • get_record: id द्वारा एक रिकॉर्ड।
  • create_record: एक रिकॉर्ड बनाएँ।
  • update_record: फ़ील्ड अपडेट करें।
  • delete_record: हटाएँ (सॉफ्ट, ट्रैश में जाता है); key पर delete स्कोप आवश्यक है।

जो क्लाइंट HTTP पर रिमोट MCP का समर्थन करते हैं वे Authorization: Bearer हेडर के साथ URL का उपयोग करते हैं। नेटिव रिमोट HTTP के बिना क्लाइंट पर, mcp-remote ब्रिज का उपयोग करें:

{
  "mcpServers": {
    "sellio-crm": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://www.selliocrm.com/api/mcp",
        "--header", "Authorization: Bearer sk_live_..."
      ]
    }
  }
}

रेट लिमिट

प्रत्येक key की प्रति-मिनट सीमा होती है (डिफ़ॉल्ट 120, कॉन्फ़िगर करने योग्य)। प्रतिक्रियाओं में X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset हेडर शामिल होते हैं। अधिकता पर, API Retry-After के साथ 429 लौटाता है।

ऑब्जेक्ट मॉडल

प्रत्येक tenant के पास मानक ऑब्जेक्ट (Contact, Company, Lead, Opportunity और अन्य) और कस्टम नो-कोड ऑब्जेक्ट होते हैं। इन सभी को GET /api/v1/objects से और प्रत्येक के फ़ील्ड को GET /api/v1/objects/{object} या describe_object से खोजें। स्कीमा हमेशा आपके tenant का होता है।

💡 Settings → API & developers में अपनी key जनरेट करें और मिनटों में अपनी पहली कॉल करें। रिकॉर्ड हटाना REST API और MCP के माध्यम से उपलब्ध है, लेकिन यह एक सॉफ्ट डिलीट है (ट्रैश में जाता है, प्रतिवर्ती) और केवल उन keys के साथ काम करता है जिन पर delete स्कोप सक्षम है, जो डिफ़ॉल्ट रूप से बंद है।

Open this article inside the system →

Read it and want to see it working?

The account is free and the whole manual is available inside the system, with an assistant that answers from this very content.

मुफ़्त खाता बनाएँ
डेवलपर संदर्भ: REST API और MCP · Sellio