ऑर्डर API आणि वेबहुक

तुमच्या ऑर्डर Shopify किंवा WooCommerce ऐवजी तुमच्या स्वतःच्या वेबसाइटवर किंवा ERP मध्ये असल्यास, तुमचे सॉफ्टवेअर त्या थेट तुमच्या Production Floor वर पाठवू शकते, आणि काम पुढे सरकत असताना Yantra Bhavan तुमच्या सॉफ्टवेअरला परत कळवू शकते: एखादी लाइन मॅप झाल्यावर, जॉबची स्थिती बदलल्यावर आणि ती शिप झाल्यावर.

ऑर्डर पाठवणे

तुमच्या सॉफ्टवेअरला ऑर्डर ॲक्सेस असलेले थर्ड-पार्टी क्रेडेन्शियल हवे. Owner किंवा Manager Integrations उघडतो, Connect → Third-party software निवडतो, आणि Can create orders वर टिक करतो. ती टिक नसलेले क्रेडेन्शियल कोटेशन वाचू शकते, पण ऑर्डर रूटवर नाकारले जाते. क्रेडेन्शियलचे ॲक्सेस टोकन कसे होते ते इंटिग्रेशन बनवणे मध्ये आहे. ऑर्डर इनटेकसाठी इंटिग्रेशन आणि Production Floor दोन्ही असलेला प्लान हवा.

curl -X POST "https://shriganesh.yantrabhavan.com/api/v1/integration/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 9b2f6c1e-3d4a-4f7b-8c55-0e1a2b3c4d5e" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "SO-10442",
    "number": "#10442",
    "version": 1760342400000,
    "dueAt": "2026-10-20T00:00:00Z",
    "lines": [
      { "lineId": "L1", "sku": "BRACKET-PLA-01",
        "title": "Mounting bracket, black PLA", "quantity": 4, "unitPrice": 120 }
    ]
  }'

• Idempotency-Key आवश्यक आहे: तुम्ही पाठवलेल्या प्रत्येक ऑर्डरसाठी एक नवीन यादृच्छिक मूल्य (एक UUID). विनंती टाइम आउट झाल्यास, ती त्याच की आणि बॉडीसह पुन्हा पाठवा — तुम्हाला मूळ उत्तर परत मिळेल आणि दुसरी ऑर्डर तयार होणार नाही. तीच की वेगळ्या बॉडीसह पाठवल्यास 422 सह नाकारली जाते. की 30 दिवस लक्षात ठेवल्या जातात.
• externalId हा तुमचा ऑर्डर आयडी आहे. तो (नवीन कीसह) पुन्हा पाठवल्यास नवीन ऑर्डर तयार न होता तीच ऑर्डर अपडेट होते. वाढत जाणारा version पाठवा — उदाहरणार्थ मिलिसेकंदांमधील तुमचा updated-at वेळ — जेणेकरून उशिरा पोहोचलेले जुने अपडेट दुर्लक्षित होईल. रद्द करण्यासाठी cancelled ला true सेट करा.
• नवीन ऑर्डरसाठी उत्तर 201 आणि अपडेटसाठी 200 असते, ज्यात ऑर्डरची इनटेक स्थिती आणि, प्रत्येक लाइनसाठी, ती मॅप झाली आहे का आणि तिचे कोणते जॉब आहेत हे असते. GET …/orders/ नंतर हीच रचना परत देतो.
• ऑर्डर तुमच्या Shopify आणि WooCommerce ऑर्डरच्या शेजारी Store orders मध्ये येते. ज्या लाइनच्या SKU साठी नियम आहे ती आपोआप फ्लोअरवर जाते; इतर प्रत्येक लाइन तुम्ही एकदा मॅप करण्याची वाट पाहते — तुमच्या ऑनलाइन स्टोअरच्या ऑर्डर पहा.

वेबहुक एंडपॉइंट जोडणे

Integrations मध्ये, Webhooks खाली, Owner किंवा Manager Yantra Bhavan ने कॉल करायचा URL जोडतो आणि हवे ते इव्हेंट निवडतो. URL मानक पोर्टवर https:// असावा आणि सार्वजनिक इंटरनेटपर्यंत पोहोचणारा असावा — खाजगी नेटवर्कमधील पत्ते नाकारले जातात, सेव्ह करताना आणि प्रत्येक डिलिव्हरीच्या वेळीही.

• quotation.requested — एका खरेदीदाराने तुमच्या दुकानाकडे कोटेशन मागितले.
• external_order.line_mapped — स्टोअर किंवा API ऑर्डर लाइनला प्रोसेस दिली गेली — SKU नियमाने किंवा हाताने.
• production_job.status_changed — एक प्रॉडक्शन जॉब एका स्थितीतून दुसऱ्या स्थितीत गेला (रांगेत, सुरू, पूर्ण…).
• shipment.created — तुमच्या एका ऑर्डरसाठी कॅरियर आणि ट्रॅकिंगसह शिपमेंट तयार झाले.

डिलिव्हरी कशी दिसते

प्रत्येक इव्हेंट एक JSON POST असतो. बॉडीमध्ये आयडी, स्थिती आणि ट्रॅकिंग असते — तुमच्या खरेदीदाराचे संपर्क तपशील कधीच नाहीत. ऑर्डर तुमच्या सिस्टममधून आली असल्यास, external_id आणि line_id हे तुमचेच आयडी असतात, त्यामुळे तुम्ही शोध न घेता जुळवू शकता.

{
  "id": "0d6f2b1e-7c1a-4b8e-9a51-3f2e4d5c6b7a",
  "type": "production_job.status_changed",
  "created_at": "2026-10-13T09:30:00.000Z",
  "shop_id": "…",
  "data": {
    "job_id": "…", "from": "READY", "to": "IN_PROGRESS",
    "order_id": "…", "order_item_id": "…", "source": "API",
    "external_id": "SO-10442", "line_id": "L1"
  }
}

• X-YB-Event-Id — इव्हेंट आयडी, बॉडीमधील id सारखाच.
• X-YB-Event-Type — इव्हेंटचा प्रकार.
• X-YB-Timestamp — ते कधी साइन झाले, Unix सेकंदांमध्ये.
• X-YB-Signature — v1= नंतर टाइमस्टॅम्प, एक पूर्णविराम (.) आणि रॉ बॉडी यांचा hex HMAC-SHA256, ज्याची की तुमचे संपूर्ण whsec_ सीक्रेट आहे.

डिलिव्हरी तपासणे

कोणत्याही डिलिव्हरीवर विश्वास ठेवण्यापूर्वी ती तपासा. चार नियम, सर्व खालील स्निपेटमध्ये:

1. सिग्नेचर रॉ रिक्वेस्ट बॉडीवर, बाइट-दर-बाइट, तयार करा. JSON पार्स करून पुन्हा सीरियलाइझ केल्यास ती बदलते, आणि सिग्नेचर जुळणार नाही.
2. सिग्नेचरची तुलना कॉन्स्टंट टाइममध्ये करा (crypto.timingSafeEqual, hash_equals, hmac.compare_digest), कधीही == किंवा === ने नाही.
3. तुमच्या घड्याळापासून पाच मिनिटांपेक्षा जास्त फरक असलेला टाइमस्टॅम्प नाकारा, जेणेकरून पकडलेली डिलिव्हरी नंतर पुन्हा चालवता येणार नाही.
4. तुम्ही हाताळलेले इव्हेंट आयडी लक्षात ठेवा आणि पुनरावृत्ती वगळा. रीट्रायमध्ये तोच आयडी असतो, आणि क्वचित एक इव्हेंट दोनदा येतो.

Node.js

const crypto = require('node:crypto');

// Express: app.post('/yb-webhooks', express.raw({ type: 'application/json' }), handler)
// req.body must be the RAW bytes — re-serialised JSON will not verify.
function verifyYantraBhavan(secret, req) {
  const timestamp = req.get('X-YB-Timestamp') || '';
  const signature = req.get('X-YB-Signature') || '';
  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected =
    'v1=' +
    crypto.createHmac('sha256', secret)
      .update(timestamp + '.')
      .update(req.body)
      .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

PHP

<?php
$secret    = getenv('YB_WEBHOOK_SECRET');           // the whole whsec_… value
$payload   = file_get_contents('php://input');      // raw body
$timestamp = $_SERVER['HTTP_X_YB_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_YB_SIGNATURE'] ?? '';

if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit;
}
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(400);
    exit;
}
http_response_code(204);   // accept now, do the work afterwards

Python

import hashlib
import hmac
import time

def verify_yantra_bhavan(secret: str, headers, raw_body: bytes) -> bool:
    timestamp = headers.get("X-YB-Timestamp", "")
    signature = headers.get("X-YB-Signature", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    mac = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest("v1=" + mac, signature)

# Flask: verify_yantra_bhavan(secret, request.headers, request.get_data())

रीट्राय, आणि एंडपॉइंट कधी बंद केला जातो

10 सेकंदांच्या आत कोणत्याही 2xx ने उत्तर द्या आणि वेळखाऊ काम नंतर करा. इतर काहीही — एरर स्टेटस, टाइमआउट, रीडायरेक्ट — अपयश मानले जाते, आणि तो इव्हेंट आठ वेळांपर्यंत पुन्हा पाठवला जातो, मध्ये 1, 2, 4 … 64 मिनिटे थांबून (एकूण सुमारे दोन तास).

एखादा एंडपॉइंट 24 तास सतत अयशस्वी होत राहिल्यास, तो बंद केला जातो आणि दुकानाच्या मालकाला ईमेल येतो. Integrations मध्ये तो Disabled दिसतो; रिसीव्हर दुरुस्त करा, तपासण्यासाठी Send test event वापरा, मग Re-enable करा. तो बंद असतानाचे इव्हेंट पुन्हा पाठवले जात नाहीत — राहिलेले मिळवण्यासाठी GET …/orders/ वापरा. Recent deliveries मध्ये प्रत्येक प्रयत्न त्याच्या स्टेटस कोड आणि एररसह दिसतो.