ಆರ್ಡರ್ 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 ನಿಮ್ಮ ಆರ್ಡರ್ ID. ಅದನ್ನು (ಹೊಸ ಕೀಯೊಂದಿಗೆ) ಮತ್ತೆ ಕಳುಹಿಸಿದರೆ ಹೊಸ ಆರ್ಡರ್ ರಚಿಸುವ ಬದಲು ಅದೇ ಆರ್ಡರ್ ಅಪ್‌ಡೇಟ್ ಆಗುತ್ತದೆ. ಏರುತ್ತಿರುವ 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. ಬಾಡಿಯಲ್ಲಿ ID ಗಳು, ಸ್ಥಿತಿಗಳು ಮತ್ತು ಟ್ರ್ಯಾಕಿಂಗ್ ಇರುತ್ತದೆ — ನಿಮ್ಮ ಖರೀದಿದಾರರ ಸಂಪರ್ಕ ವಿವರಗಳು ಎಂದಿಗೂ ಇರುವುದಿಲ್ಲ. ಆರ್ಡರ್ ನಿಮ್ಮ ಸಿಸ್ಟಮ್‌ನಿಂದ ಬಂದಿದ್ದರೆ, external_id ಮತ್ತು line_id ನಿಮ್ಮದೇ 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, ಬಾಡಿಯಲ್ಲಿನ 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. ನೀವು ನಿರ್ವಹಿಸಿದ ಈವೆಂಟ್ ID ಗಳನ್ನು ನೆನಪಿಟ್ಟುಕೊಂಡು ಪುನರಾವರ್ತನೆಗಳನ್ನು ಬಿಟ್ಟುಬಿಡಿ. ರೀಟ್ರೈನಲ್ಲಿ ಅದೇ ID ಇರುತ್ತದೆ, ಮತ್ತು ಅಪರೂಪಕ್ಕೆ ಒಂದು ಈವೆಂಟ್ ಎರಡು ಬಾರಿ ಬರುತ್ತದೆ.

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 ಪ್ರತಿ ಪ್ರಯತ್ನವನ್ನು ಅದರ ಸ್ಟೇಟಸ್ ಕೋಡ್ ಮತ್ತು ಎರರ್‌ನೊಂದಿಗೆ ಪಟ್ಟಿ ಮಾಡುತ್ತದೆ.