Lookups

Lookup qachon kerak#

Joriy buyurtma holati, mavjud bandlov yoki mijoz akkaunti uchun lookup ishlating. Barqaror qoidalar va mahsulot maʼlumotlarini Bilimda saqlang. Lookup faqat oʻqiydi: toʻlov, bekor qilish, band qilish yoki yozuvni oʻzgartirish uchun ishlatmang. Oddiy tanlov va tasdiqlash kartalari faqat tashrifchi xabarini yuboradi. Tasdiqlangan yozuvlar uchun Oʻzgartirish amallari, kalendar bandlovi uchun Cal.com bilan bandlashdan foydalaning. Faqat run bilan bogʻlangan tasdiqlash kartasi bu amallarga ruxsat beradi.

Amalni sozlash#

Agent → Amallarni oching. Tizimga kirgan mijozlarda kalit yarating, serverda saqlang va mijozni aniqlashni ulang. Lookupsda order_status kabi nom, qachon ishlatish tavsifi va ochiq HTTPS endpointini qoʻshing. Faqat kerakli kirishlarni, masalan order_id satrini eʼlon qiling. Model uni lookup_order_status sifatida koʻradi.

Yopiq yozuvlar uchun standart Tizimga kirgan mijoz talab qilinadini yoqilgan qoldiring. Oʻchirilsa customer: null kelishi mumkin; faqat anonim tashrifchiga mos maʼlumot qaytaring. Chat yoki suratdagi ID — kiritilgan qiymat, autentifikatsiyalangan shaxs emas.

Mavjud maydonlar avtomatik saqlanadi; sinashdan oldin saqlangan belgisini kuting. Lookupni yoqish/oʻchirish, tahrirlash yoki olib tashlash mumkin. Panel uchun kalit kerak. Birinchi bosqichda lookup boshqaruvi faqat dashboardda, ochiq API orqali mavjud emas.

Siz oladigan soʻrov#

Make Agent Fast sozlangan URLʼga JSON POST yuboradi. Quyidagi imzo qiymatlari namunaviy:

POST /agent/order-status HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>

{
  "version": 1,
  "action": "order_status",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

action — lookup_ prefiksisiz nom. requestId urinishni, siteId saytni bildiradi. input faqat eʼlon qilingan satr parametrlarini oladi. customer null yoki server tekshirgan { id, email?, name? }; model va tashrifchi kirishlari uni almashtira olmaydi. Dashboarddagi Sinov vakolatli egasi kiritgan namunaviy mijozdan foydalanadi.

Imzoni tekshirish#

Imzo agent maxfiy kaliti bilan HMAC-SHA256 hisoblangan kichik harfli hex qiymat va v1= prefiksidan iborat. Aynan "maf-webhook-v1:" + timestamp + "." + rawBodyni tekshiring. Qabul qilingan baytlarni saqlang; JSONʼni oʻqib qayta yozish imzoni oʻzgartirishi mumkin. Bu funksiya serverdagi standart Requestni qabul qiladi, besh daqiqalik vaqt chegarasi va saytni tekshiradi:

import { createHmac, timingSafeEqual } from "node:crypto";

export async function verifyLookupRequest(request, expectedSiteId) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const timestamp = request.headers.get("x-maf-timestamp");
  const signature = request.headers.get("x-maf-signature");
  const now = Math.floor(Date.now() / 1000);
  if (!timestamp || !/^\d+$/.test(timestamp) ||
      !Number.isSafeInteger(Number(timestamp)) ||
      Math.abs(now - Number(timestamp)) > 300) {
    throw new Error("Invalid timestamp");
  }
  if (!signature || !/^v1=[a-f0-9]{64}$/.test(signature)) {
    throw new Error("Invalid signature");
  }
  const rawBody = Buffer.from(await request.arrayBuffer());
  const expected = createHmac("sha256", secret)
    .update(`maf-webhook-v1:${timestamp}.`)
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), "hex");
  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
    throw new Error("Invalid signature");
  }
  const body = JSON.parse(rawBody.toString("utf8"));
  if (body?.version !== 1 || body.siteId !== expectedSiteId) {
    throw new Error("Invalid lookup scope");
  }
  return body;
}

Body parser soʻrovni oʻqishidan oldin chaqiring. Xatolarni rad eting, amal nomi va kirish tuzilmasini tekshiring; yopiq maʼlumotdan oldin body.customer.id bilan egalikni tekshiring. Masalan, A128ni faqat buyurtma IDʼi boʻyicha emas, shu mijoz buyurtmalari ichidan qidiring. input.customer_id, chatdagi email yoki suratni ruxsat deb qabul qilmang. Yopiq endpoint null boʻlmagan mijozni talab qilsin. Serverda kiruvchi body hajmini cheklang. Takroriy soʻrovlarni rad etish kerak boʻlsa, vaqt oynasida requestIdni ham kuzating; vaqt tekshiruvi shu oraliqdagi takrorni toʻxtatmaydi.

HTTPS ishlating va POST boʻlsa ham faqat oʻqishga ruxsat bering. Kalit almashtirilganda shaxs tokenini imzolovchi server va lookup tekshiruvchisini birga yangilang.

Javob qaytarish#

2xx muvaffaqiyat holati va quyidagi shakldagi JSON qaytaring. Birinchi misol topilgan yozuv, ikkinchisi oddiy topilmadi natijasi:

{
  "found": true,
  "card": {
    "title": "Order #A128",
    "status": { "label": "Shipped", "tone": "success" },
    "fields": [{ "label": "Carrier", "value": "DHL" }],
    "reference": "A128",
    "asOf": "2026-10-12T09:00:00Z",
    "link": { "label": "Track", "url": "https://shop.example.com/orders/A128" }
  },
  "facts": { "order_id": "A128", "status": "shipped", "carrier": "DHL" }
}

{ "found": false }

found majburiy. found: true uchun card, facts yoki ikkalasini bering. Kartada title va fields majburiy (boʻsh massiv mumkin). status, reference, asOf, link ixtiyoriy. Javob kartasiga kind qoʻshmang. Status turlari: neutral, success, warning, danger. asOf uchun ISO vaqt, havola uchun login maʼlumotlarisiz HTTPS URL ishlating. Yaroqsiz ixtiyoriy havola tashlab ketiladi.

facts — qiymatlari satr, chekli son, boolean yoki null boʻlgan yassi obyekt. Ichma-ich obyekt va massivlar, javob/karta sxemasidagi nomaʼlum maydonlar rad etiladi. Faqat javob uchun kerakli faktlarni yuboring. Model escape qilingan, cheklangan va ishonchsiz maʼlumot sifatida belgilangan matnni oladi; uni buyruq deb qabul qilmaydi. Karta HTML emas, oddiy matn.

Cheklovlar va xatolar#

Mijoz shaxsi boʻlmasa endpoint chaqirilmaydi, kirish ogohlantirishi koʻrsatiladi. Majburiy kirishlar yetishmasa tashrifchidan soʻraladi. found: false neytral topilmadi kartasini chiqaradi. Timeout, 2xx boʻlmagan holat, notoʻgʻri JSON/sxema yoki katta javob xato holatini beradi va modelga taxmin qilmaslik aytiladi. Oddiy topilmadi uchun HTTP 404 oʻrniga 2xx bilan found: false qaytaring. Uzun karta matni va model maʼlumoti kesiladi, shuning uchun muhim faktlarni qisqa yozing.

Dashboarddan sinash#

1. Lookupni saqlang, Sinovni oching. Oʻzingiz nazorat qiladigan namunaviy mijoz IDʼi, ixtiyoriy email va barcha majburiy kirishlarni kiriting.
2. Sinovni ishga tushiring. Lookup tashrifchilar uchun oʻchirilgan boʻlsa ham haqiqiy imzolangan soʻrov ketadi; oddiy repetitsiya chatida endpoint chaqirilmaydi. Egasi boʻyicha sinov chastotasi cheklangan.
3. Tekshirilgan karta/xulosa yoki xato, request ID, davomiylik va mavjud boʻlsa HTTP holatini koʻring. Loglarda kalit va mijoz tokenlarini saqlamang.
4. Topildi, topilmadi, boshqa akkaunt, yetishmagan kirish va timeout holatlarini sinang. Keyin haqiqiy embedda ikki autentifikatsiyalangan mijoz bilan tekshiring: dashboard namunasi brauzer izolyatsiyasi yoki real model tool tanlovini isbotlamaydi.

Widget status kartalarini koʻrsatadi; oddiy tanlov/tasdiq bosilishi yorliqni xabar qilib yuboradi. Run bilan bogʻlangan oʻzgartirish va bandlov tasdiqlari himoyalangan bajarish oqimidan foydalanadi. Konnektorlar kartalarni kanal matni/kartasi, tugma, tezkor javob yoki roʻyxatga moslaydi; matnli fallback ham kanal limitlariga boʻysunadi. Har foydalaniladigan kanalda yetkazilishni tekshiring.