Partner API — Integration Guide

✅ ภาพรวมการเชื่อมต่อ

Partner app (แอป Sales Order ของคุณ) เปิด shelfculator ตรงไปที่ร้านที่ต้องการให้ rider ทำ survey เมื่อทำเสร็จ shelfculator เด้งกลับเข้า partner app — แล้ว partner เรียก API มาเช็คว่างานเสร็จจริงไหม

Partner app                    shelfculator                    DDS partner API
    │                              │                              │
    │ 1. shelfculator://store?...  │                              │
    │─────────────────────────────▶│  rider ทำ survey + อัปโหลด    │
    │                              │                              │
    │ 2. <return base>://...?...   │                              │
    │◀─────────────────────────────│  (rider กดปุ่ม "กลับไปแอป")    │
    │                              │                              │
    │ 3. GET /surveyStatus  (x-api-key)                           │
    │────────────────────────────────────────────────────────────▶│
    │ 4. { all_completed: true, completed: 2, total: 2 }          │
    │◀────────────────────────────────────────────────────────────│

1 เปิด shelfculator (deep link ขาไป)

Partner app เปิด URL นี้ (เช่นผ่าน Android Intent / Linking.openURL) — format นี้กำหนดโดย shelfculator (ฝั่งเรา):

shelfculator://store?sid=<รหัสร้าน>&store_type=<ประเภทร้าน>&username=<rider>&date=<YYYY-MM-DD>

ถ้า task ยังไม่อยู่ในเครื่อง shelfculator จะ syncPull ก่อนแล้วค่อยนำทางเข้าร้านนั้น

2 เด้งกลับ partner app (deep link ขากลับ)

shelfculator เก็บ "deep link base" ของ partner ไว้ที่ return_android_app (ฝั่งเราตั้งให้ตอน onboard) เมื่อ rider กดปุ่ม "กลับไปแอป" shelfculator จะเปิด:

<return base>?sid=<รหัสร้าน>&store_type=<ประเภท>&username=<rider>

# ตัวอย่าง ถ้า base = salesorderapp://survey-return
salesorderapp://survey-return?sid=dds263-2&store_type=DDS&username=aa1ddstest1

partner ต้องทำ: ประกาศ URL scheme ของตัวเองใน Android (AndroidManifest.xml → intent-filter + android:scheme) แล้วแจ้ง base URL นี้มาให้เรา set ใน return_android_app ของ rider/org

<!-- ตัวอย่าง AndroidManifest.xml ของ partner -->
<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="salesorderapp" />
</intent-filter>

ถ้ายังไม่พร้อมแก้แอป ปล่อย return_android_app เป็นว่าง (null) ได้ — rider จะใช้ shelfculator แบบหน่วย survey ปกติ ไม่มีปุ่มเด้งกลับ

3 API: เช็คสถานะ survey

GET https://api.digitaldatasmart.com/surveyStatus

Authentication

ส่ง org API key ผ่าน header x-api-key (หรือ Authorization: Bearer <key>) — key ผูกกับ organizer จึงเห็นเฉพาะงานของ org ตัวเอง · เป็น server-to-server เท่านั้น ห้ามฝังลง mobile app · rate limit 60 req/นาที ต่อ key (เกิน → 429)

Query parameters (จำเป็นทั้งหมด)

username    = rider (เช่น aa1ddstest1)
sid         = รหัสร้าน (เช่น dds263-2)
store_type  = ประเภทร้าน (เช่น DDS)
date        = วันเปิดบิล YYYY-MM-DD (เช่น 2026-06-11)

ตัวอย่างเรียก (curl)

curl 'https://api.digitaldatasmart.com/surveyStatus?username=aa1ddstest1&sid=dds263-2&store_type=DDS&date=2026-06-11' \
  -H 'x-api-key: dds_live_xxxxxxxxxxxxxxxxxxxxxxxx'

Response 200

{
  "success": true,
  "username": "aa1ddstest1",
  "sid": "dds263-2",
  "store_type": "DDS",
  "date": "2026-06-11",
  "total": 2,           // จำนวนงานของร้าน/วันนั้น
  "completed": 2,       // ที่เสร็จแล้ว
  "all_completed": true // total > 0 และเสร็จครบ
}

หมายเหตุ: ถ้า total = 0 = ไม่มีงานของ org คุณตรงเงื่อนไขนั้น (หรือ key ไม่ตรง org) — all_completed จะเป็น false เสมอ

Error codes

Checklist ก่อน onboard

DDS เตรียมให้คุณ

• สร้าง Organizer + AppUser (rider) ใต้ org ของคุณ
• ตั้ง return_android_app = deep link base ของแอปคุณ (หรือเว้นว่างถ้ายังไม่พร้อม)
• สร้าง API key แล้วส่งให้ผ่านช่องทางปลอดภัย (key แสดงครั้งเดียว — เก็บให้ดี)

ฝั่งคุณ (partner dev)

• แจ้ง deep link base ของแอปคุณ (เช่น salesorderapp://survey-return)
• ประกาศ URL scheme ใน Android + เปิด shelfculator://store?... ขาไป
• รับ deep link ขากลับ แล้วเรียก surveyStatus (เก็บ key ฝั่ง server) เพื่อยืนยันสถานะจริง