API और AI एजेंट एक्सेस

SimplyQuote एक REST API उपलब्ध कराता है ताकि आपके AI एजेंट, स्क्रिप्ट और इंटीग्रेशन आपकी ओर से आपके कोट और इनवॉइस के साथ काम कर सकें। एक्सेस स्कोप्ड, रद्द करने योग्य पर्सनल एक्सेस टोकन से नियंत्रित होता है।

1. API एक्सेस सक्षम करें

1. अपना सेटिंग्स पेज खोलें और लॉग इन करें
2. "API और AI एजेंट एक्सेस" सेक्शन तक स्क्रॉल करें।
3. टोकन का नाम दें, स्कोप चुनें और "टोकन बनाएं" पर क्लिक करें।
4. टोकन तुरंत कॉपी करें — सुरक्षा के लिए, यह केवल एक बार दिखाया जाता है।

2. अनुरोध भेजें

Authorization हेडर में टोकन को Bearer टोकन के रूप में भेजें:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. दस्तावेज़ बनाएं और अपडेट करें

कोट और इनवॉइस बनाने और अपडेट करने के लिए राइट स्कोप वाला वही टोकन उपयोग होता है। कुल राशि हमेशा आपके भेजे गए आइटम से सर्वर पर गणना होती है:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

सफलता प्रतिक्रिया (सूचियां समान, quotes/invoices के साथ total/page/limit/has_more):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

सूची और पेजिनेशन

सूची एंडपॉइंट updated_since (ISO 8601), page (डिफ़ॉल्ट 1), limit (डिफ़ॉल्ट 20, अधिकतम 100) और status (केस-असंवेदी; अज्ञात मान अनदेखे) स्वीकार करते हैं। प्रतिक्रियाओं में total, page, limit और has_more शामिल होते हैं।

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

बनाने और अपडेट करने के फ़ील्ड नियम

POST पर items अनिवार्य है: गैर-रिक्त ऐरे, प्रत्येक पंक्ति में गैर-रिक्त description, quantity > 0 (डिफ़ॉल्ट 1), unit_price >= 0 (डिफ़ॉल्ट 0)। tax_rate प्रतिशत है (0–100); बनाते समय tax_rate > 0 का अर्थ tax_enabled है। currency बड़े अक्षरों में संग्रहीत होती है। issue_date कोई भी मान्य तिथि स्वीकार करता है (YYYY-MM-DD में संग्रहीत)। कोट expiry_date और इनवॉइस due_date उपयोग करते हैं (दोनों उपनाम स्वीकार्य, null मिटाता है)। स्थिति: कोट draft|sent, इनवॉइस draft|sent|viewed|paid|cancelled — paid से paid_at दर्ज होता है। कुल राशि हमेशा सर्वर पर पुनर्गणना होती है।

4. AI एजेंट के साथ उपयोग करें

अपने एजेंट को बेस URL, अपना टोकन और नीचे दी गई एंडपॉइंट सूची दें। किसी भी टूल-कॉलिंग एजेंट (Claude, GPT, LangChain आदि) के लिए उदाहरण निर्देश:

आप मेरे SimplyQuote खाते तक पहुंच सकते हैं।
बेस URL: https://simplyquote.net
हर अनुरोध में हेडर भेजें: Authorization: Bearer sq_आपका_टोकन
उपलब्ध एंडपॉइंट: GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
सूचियां ?page, ?limit (अधिकतम 100), ?status, ?updated_since समर्थित करती हैं और { success:true, data:{ quotes|invoices, total, page, limit, has_more } } लौटाती हैं।
एकल GET मूल ऑब्जेक्ट लौटाते हैं। {id} UUID है, दस्तावेज़ संख्या नहीं।
दस्तावेज़ बनाने के लिए POST का उपयोग करें — items में हमेशा description, quantity और unit_price भेजें।

5. MCP से कनेक्ट करें (एजेंटों के लिए अनुशंसित)

SimplyQuote में /api/mcp पर बिल्ट-इन MCP (Model Context Protocol) सर्वर है (स्टेटलेस स्ट्रीमेबल HTTP, JSON-RPC 2.0)। रिमोट MCP सर्वर का समर्थन करने वाले एजेंट (Claude, ChatGPT, Cursor, VS Code आदि) आपके टोकन से सीधे कनेक्ट हो सकते हैं — प्रॉम्प्ट इंजीनियरिंग की ज़रूरत नहीं। उपलब्ध टूल:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

टूल कॉल का उदाहरण (JSON-RPC 2.0 — बैच अनुरोध अस्वीकृत, सूचनाओं पर 202, GET पर 405):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

हर टूल कॉल को आपके टोकन के स्कोप के अनुसार जांचा जाता है — केवल-पढ़ने वाला टोकन सूची और पुनर्प्राप्ति कर सकता है, जबकि कोट या इनवॉइस बनाने के लिए संबंधित राइट स्कोप चाहिए।

एंडपॉइंट

स्कोप

• quotes:read — आपके कोट पढ़ें
• invoices:read — आपके इनवॉइस पढ़ें
• clients:read — आरक्षित — अभी कोई अलग क्लाइंट एंडपॉइंट नहीं है (क्लाइंट जानकारी कोट/इनवॉइस पर होती है)
• quotes:write — कोट बनाएं और अपडेट करें
• invoices:write — इनवॉइस बनाएं और अपडेट करें
• clients:write — आरक्षित — अभी कोई अलग क्लाइंट एंडपॉइंट नहीं है (कोट/इनवॉइस सहेजने पर क्लाइंट जानकारी स्वतः बनती/अपडेट होती है)

प्रतिक्रिया प्रारूप और त्रुटियां

REST एंडपॉइंट दो प्रारूपों का उपयोग करते हैं — प्रत्येक मामले में लागू प्रारूप देखें:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

एकल GET उपरोक्त मूल ऑब्जेक्ट लौटाते हैं (बिना आवरण), साथ में फ्लैट { error, message } त्रुटियां — जैसे अज्ञात id पर 404। सूचियां और POST/PATCH हमेशा आवरण का उपयोग करते हैं।

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — सफलता पर true, विफलता पर false
• data — सफलता पर डेटा
• error — विफलता पर त्रुटि कोड, संदेश और वैकल्पिक विवरण

सबसे सामान्य त्रुटि कोड:

• UNAUTHORIZED — टोकन गायब, अमान्य या समाप्त (HTTP 401)
• FORBIDDEN — टोकन में आवश्यक स्कोप नहीं है (HTTP 403)
• VALIDATION_ERROR — अनुरोध बॉडी सत्यापन में विफल (HTTP 400)
• NOT_FOUND — अनुरोधित दस्तावेज़ मौजूद नहीं है (HTTP 404)
• DATABASE_ERROR — अनुरोध संसाधित करते समय स्टोरेज त्रुटि (HTTP 500)
• RATE_LIMIT — बहुत अधिक अनुरोध — बाद में पुनः प्रयास करें (HTTP 429)

वेबहुक, OAuth और पूर्ण संदर्भ

वेबहुक: GET/POST/PATCH/DELETE /api/v1/webhooks से सदस्यताएं प्रबंधित करें (कोई भी मान्य टोकन, कोई विशेष स्कोप नहीं)। url सार्वजनिक HTTPS एंडपॉइंट होना चाहिए। सीक्रेट केवल निर्माण पर मिलता है — X-SimplyQuote-Signature (HMAC-SHA256) हेडर से डिलीवरी सत्यापित करें।

भागीदार ऐप पर्सनल टोकन के बजाय OAuth 2.0 (/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke) उपयोग करते हैं। विवरण docs/API.md में और /api/v1/openapi.json पर मशीन-रीडेबल विनिर्देश में देखें।

सुरक्षा नोट्स

• टोकन हैश करके संग्रहीत होते हैं — SimplyQuote कभी भी मूल टोकन नहीं रखता।
• केवल वही स्कोप दें जो आपके एजेंट को चाहिए; आमतौर पर केवल-पढ़ने वाले स्कोप पर्याप्त होते हैं।
• एक्सेस तुरंत बंद करने के लिए सेटिंग्स से कभी भी टोकन रद्द करें।
• एजेंटों के लिए मशीन-रीडेबल विनिर्देश यहां उपलब्ध है: /api/v1/openapi.json