ஆர்டர் 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 ஒவ்வொரு முயற்சியையும் அதன் நிலைக் குறியீடு மற்றும் பிழையுடன் பட்டியலிடும்.