ఆర్డర్ 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 ప్రతి ప్రయత్నాన్ని దాని స్టేటస్ కోడ్ మరియు ఎర్రర్‌తో చూపుతుంది.