Joy Loyalty · Integrations

Roadmap
integrations

Cái gì đang hỏng, vì sao, và những việc cần làm để mọi integration gửi được dữ liệu, tự phục hồi và báo cho merchant biết.

Vấn đề qua con số · log prod 02/11 → 19/11

Công suất đủ. Độ tin cậy thì không.

205k
lần gửi bị bỏ sau khi đối tác rate limit: Omnisend contact 172.229, Klaviyo profile 22.479, Omnisend event 10.404
27.166
lần refresh token Klaviyo thất bại trên 44 shop. Credential đã chết vẫn bị gọi hàng tuần; merchant vẫn thấy "Connected"
40,7k
dòng lỗi do Joy tự gây ra: trang khách hàng trong admin dò Klaviyo và Omnisend cho cả shop chưa từng kết nối
344
webhook đơn hàng không vào được hàng đợi nhưng vẫn trả "thành công" cho Shopify (303 lỗi "Task size too large"). Các đơn này có thể chưa được cộng điểm
21.382
dòng log chứa header authorization Mailchimp của merchant. Địa chỉ khách Recharge và header Apple Wallet cũng bị lộ
10.491
webhook gửi cho merchant bị tính là lỗi chỉ vì endpoint trả về chữ ok thay vì JSON

Số liệu là số dòng log, không phải số khách duy nhất. Không đưa shop id hay email vào bộ slide này.

Một nguyên nhân đứng sau tất cả

Joy không có module integration. Mỗi app được nối tay qua ~30 file, chạy trên đường không retry được, không có delivery id, không có dead-letter queue, không có trạng thái health, không có metric thành công.

Compute, Pub/Sub và Cloud Tasks thừa sức gánh thêm 5–8 đối tác. Cái thiếu là mọi thứ giúp một lần gửi an toàn.

Vì sao làm mới thay vì vá từng chỗ

Mỗi bên được gì khi integration chạy trên một nền tảng chung

Hiện tại
Sau khi làm mới
Merchant
Vẫn thấy "Connected" trong khi credential đã chết nhiều tuần. Dữ liệu sync bị mất mà không ai biết: 205k lần bị bỏ trong 18 ngày, không ai báo.
Badge và banner ở Home báo app nào hỏng và cái gì đang dừng (nhắc nhở, sự kiện sinh nhật, sync profile), có nút Kết nối lại, Re-sync và một email.
Khách của merchant
Điểm từ đơn hàng có thể không bao giờ tới (344 đơn); profile Klaviyo/Omnisend cũ đi nên email loyalty hiện sai số dư.
Đơn hàng được lưu bền trước khi trả 200 cho Shopify; mọi cập nhật profile được retry tới khi giao xong hoặc cách ly chờ xem xét, không bao giờ bị bỏ.
Support
Lục Cloud Logging bằng tay, log chỉ giữ 18 ngày, không có màn hình xem shop nào lỗi gì.
DevZone có chẩn đoán theo shop: lần thành công gần nhất, kết quả 7 ngày, lỗi bằng lời dễ hiểu, replay lần gửi lỗi. Ticket gắn nhãn theo integration.
Developer
Thêm một app = ~32 file, 45 chỗ sửa, 17 nhánh switch; sót một chỗ không test nào bắt được; app nào cũng tự chế retry và rate limit.
Thêm một app = một entry trong registry + một adapter. Retry, rate limit, dedupe, health và metric có sẵn từ nền tảng; contract test bắt lệch.
Kinh doanh
Không thêm được Postscript hay đối tác SMS khác một cách an toàn (gửi trùng là thêm một SMS trả tiền). Không có API đối tác nên đối tác không xây được trên Joy.
API đối tác F1 cho Loop, Tapcart, Okendo xây trên Joy; Postscript chạy trên hợp đồng gửi; Joy dẫn đầu ở chỗ chưa đối thủ nào có (cộng điểm khi đổi hàng qua Loop).

Thay đổi cốt lõi, nhìn qua một lần gửi

Đối tác trả 429. Chuyện gì xảy ra tiếp theo?

Hiện tại

Điểm thay đổi
publish lên Pub/Sub, retry:false
Omnisend trả 429
handler sleep rồi thử lại ngay trong cùng request
Vẫn 429
trả undefined; dispatcher trả 'ok'
Bị bỏ
một dòng log. Không retry, không replay, không metric, merchant không biết
172.229 lần trong 18 ngày

Sau khi làm mới

Điểm thay đổi
producer ghi bản ghi gửi đang chờ với deliveryId cố định, rồi mới xác nhận
Xếp lượt
worker lấy một suất trong ngân sách của shop, đúng giới hạn thật của Omnisend
429 → hẹn lại
chờ đúng thời gian Omnisend cho phép (Omnisend ghi trong body, không có header Retry-After); hoãn không tính là một lần thử
Giao xong
ghi nhận thành công. Klaviyo và LINE tự chống trùng theo mã gửi; Omnisend thì không, nên Joy tự giữ mã
Hoặc cách ly
gửi rồi mà timeout = không rõ đối tác nhận chưa → giữ lại cho người kiểm, không gửi lại mù (tránh automation chạy 2 lần)

Auth cũng theo cùng cách: 401 thành auth_broken (dừng gọi, giữ token, báo merchant), thay vì retry hàng tuần.

1 · Integration đang dùng · đếm trên Firestore prod, chỉ đọc, 20/11

Ai dùng gì: số merchant đang kết nối từng integration

Shop còn cài Joy (bản ghi integration) Shop còn cài Joy (cờ trên shop) kể cả shop đã gỡ Joy Tổng: 20.835 shop đang cài

Bản thân số đếm cho thấy điều gì

Joy tự mâu thuẫn ở câu hỏi "đã kết nối chưa?"

Klaviyo

790 vs 761

bản ghi integration vs cờ trên shop

Judge.me

1.114 vs 1.216

bản ghi integration vs cờ trên shop

Judge.me

830

kết nối nằm trên shop đã gỡ Joy

Klaviyo

239

kết nối trên shop đã gỡ Joy, khớp với các lần refresh token chết

  • "App này đã kết nối chưa?" có bốn câu trả lời: cờ trên shop, bản ghi integration, map dự phòng của admin và map của AI tool. Bảy cờ admin đọc không có ai ghi.
  • Có ít nhất bảy đường code ghi trạng thái kết nối. Một trong số đó, auto-disconnect Klaviyo, còn revoke luôn quyền bên Klaviyo.
  • Chưa đếm được: Smax, Chatty, Joy Wishlist, Klaviyo Reviews, Facebook Page, API của Joy. Không có bản ghi kết nối nào để đếm.
Sửa bằng registry (3.2) và health service theo từng app (3.6).
02

Hiện tại

Kiến trúc &
hạ tầng hiện tại

Đọc từ code tại HEAD 2ff18f82dc.

2.1 · Một integration đang được nối như thế nào

Thêm một app phải đụng ~32 file, 45 chỗ sửa

Hằng số

Id app nằm chung với hằng số loyalty program; event, message, job type ở chỗ khác. Id dùng bốn kiểu viết hoa khác nhau.

const/programs/integrationPrograms.js

17 nhánh switch

Connect/disconnect ở repository, các đường controller, danh sách fan-out, map handler Cloud Task, và card, route, map trạng thái phía admin.

subscribeBackgroundHandling.js: 212 case, 9.933 dòng

4 câu trả lời "đã kết nối"

Cờ shop statusConnected* (19 tên), isConnected của doc, map dự phòng admin, map AI tool. Chúng lệch nhau, đã đo được.

7 chỗ ghi trạng thái

Connect callback, disconnect, side effect của repo, auto-disconnect Klaviyo (có revoke!), lỗi auth Intercom, lỗi bulk Drip, update chung.

Bỏ sót một chỗ thì không test nào báo lỗi. Credential bị copy vào payload Pub/Sub và Cloud Task; reconnect ghi đè cùng một doc, nên việc cũ trong hàng đợi có thể chạy bằng credential của lần cài mới.

2.2 · Đường gửi ra hiện tại, và chỗ dữ liệu bị mất

Mọi chỗ làm rơi dữ liệu đều chỉ ghi một dòng log rồi thôi

01
Sự kiện loyalty hoặc thay đổi khách
Fan-out tới mọi app đã kết nối trong triggerIntegrationAppService
publish lỗi → mất việc
02
Pub/Sub backgroundHandling*
retry: false. Một dispatcher 212 case
lỗi gì dispatcher cũng trả 'ok'
03
Service riêng từng app
Mỗi app tự chế rate limit và retry. Omnisend sleep ngay trong handler
429 → 3 lần → bỏ
04
Re-enqueue trên enqueueSubscriberv2
Một queue Cloud Tasks dùng chung, maxAttempts: 1, không đặt rateLimits
hoãn cũng bị tính là một lần thử
05
API đối tác
Klaviyo, Omnisend, Mailchimp, Attentive, Gorgias…
401 → vẫn gọi hàng tuần

Chiều nhận vào cũng không khá hơn: bốn nguồn review không ký, hai verifier fail-open, Recharge không xác thực, và webhook Shopify sai HMAC vẫn trả 200 mà không ghi log.

3.2 · Hạ tầng theo từng loại integration

Cái gì đang chạy từng loại, và chuyện gì xảy ra khi lỗi

LoạiAppĐang chạy trênKhi gặp 401 / 429 / 5xx
Email / SMS marketing (gửi ra)Klaviyo, Omnisend, Mailchimp, Attentive, Drip, Sendlane, PushOwlPub/Sub Light/Small (retry:false) → service; Klaviyo re-enqueue trên queue chung; bulk collector cho KlaviyoThrottle gate, 3 lần rồi bỏ; chỉ private key Klaviyo tự disconnect khi 401
Helpdesk / nhắn tinGorgias, Intercom, LINE, SmaxCùng đường Pub/Sub; Gorgias giới hạn trong RAMGorgias refresh lỗi → vòng lặp TypeError; LINE retry không có idempotency key
Review (nhận vào)Judge.me, Yotpo, Loox, Stamped, Fera, Review Rocket, Air Reviews, Klaviyo ReviewsWebhook HTTP trên apiHookV2, xử lý inline; dedupe chung4 nguồn không ký, 2 fail-open
Subscription / wishlistRecharge, Joy Subscription, Joy WishlistHTTP nhận vào + gọi raRecharge không xác thực, lấy tenant từ query, PII trong log
Mạng xã hộiInstagram, Facebook PageWebhook Meta có ký → Pub/Sub; token refresh khi cần, không có cronToken đã bị thu hồi vẫn retry mỗi lần dùng
WalletApple, Google WalletHTTP + APNs / Google APIHeader auth và push token vẫn bị ghi log
Email của JoyMailgun custom domain, SMTP của merchantTopic sentEmailNotification, không retryBreaker đầy đủ duy nhất trong Joy, nhưng thử custom domain ở mọi lần gửi (~18k/ngày)
Shopify (đường integration)Webhook đơn hàng, Admin API, FlowapiHookV2 + Cloud Tasks cho đơn hàngEnqueue lỗi vẫn trả 200; ~10,7k lần Admin bị throttle/ngày; Flow lỗi vẫn trả 200
API Joy cung cấpREST v2, webhook gửi merchant, headless, MCPHTTP function; webhook qua webhookSend, không retry2xx không phải JSON bị tính là lỗi; 5xx của merchant không bao giờ retry

3.3 · Hạ tầng hiện tại có đủ không?

Đủ về quy mô. Không đủ về độ tin cậy.

Có, chưa dùng

Queue bền có retry

Topic integration để retry:false; queue chung chỉ cho một lần thử

Một phần

Rate limit theo Retry-After

3 app dùng chung integrationRateLimits; cache 30 giây theo instance

Chưa có

Idempotency cho từng lần gửi

unique_id Klaviyo rơi về id ngẫu nhiên; không task nào có tên

Chưa có

Dead-letter queue + replay

Chỉ topic ordered có, gắn bằng script tay, không nằm trong CI

Chưa có

Ngắt khi hỏng auth và báo merchant

Chỉ SMTP có. 61.240 dòng refresh Klaviyo thất bại

Chưa có

Metric thành công theo app

App ghi lỗi bằng text tự do, không bao giờ ghi lần thành công

Một phần

Xác thực chiều nhận vào

4 nguồn không ký, 2 fail-open, 1 không xác thực

Một phần

Quản lý secret

Token nằm trong payload và log; một khoá hằng trong source

04

Bằng chứng

Log prod
nói gì

Cloud Logging 02/11 → 19/11 (bucket giữ 18 ngày), chỉ đọc, phân trang tới hết. Lỗi số lượng lớn được đếm chính xác.

4.2 · Gom theo nguyên nhân gốc · 336.363 dòng đã đếm

Hạ tầng gây ra phần lớn mất mát; code gây ra phần lớn nhiễu; không ai báo cho merchant

HẠ TẦNG Bỏ việc sau rate limit: không có retry bền, không có đường bulkOmnisend, Klaviyo · 205.112 dòng
61,0%
CODE + HẠ TẦNG Credential chết vẫn retry, không có breakerKlaviyo · 61.240 dòng = 27.166 lần refresh lỗi
18,2%
CODE Admin tự dò gây lỗiKlaviyo, Omnisend · 40.714 dòng
12,1%
BẢO MẬT Secret và PII trong logMẫu Mailchimp · 21.382 dòng
6,4%
HẠ TẦNG Bản thân các dòng 429 của Klaviyo6.241 dòng, 5.466 dòng rơi vào 13/11 (một shop hạ hạng hàng loạt)
1,9%
CẤU HÌNH → UX Cấu hình sai mà không ai thấyKlaviyo thiếu scope, Flow gửi email rỗng · 1.674 dòng
0,5%

Không tính vào tỷ lệ (khác cửa sổ mẫu): webhook báo lỗi giả 10.491 · fallback custom domain ~18k/ngày · Shopify Admin throttle ~10,7k/ngày · webhook đơn hàng không vào hàng đợi 344.

4.1 · Phát hiện theo từng integration

Cái gì kích hoạt → vì sao nó cứ lặp lại

Omnisend

182.633

contact + event bị bỏ sau 429. Retry sleep trong handler rồi return

Klaviyo

22.479

lần sync profile bị bỏ; hoãn cũng tính vào 3 lần thử. 98% từ đợt 13/11

Klaviyo OAuth

44 shop

quyền đã chết vẫn refresh hàng tuần; nhánh invalid_grant không bao giờ chạy tới

Gorgias

~3.000/ngày

invalid_client từ 05/11 trên 8 tài khoản, sau đó vòng lặp TypeError

Mailchimp

17,4k

401/403 trong 10 ngày, dòng nào cũng kèm header auth của merchant

Instagram

~6.300

phiên bị thu hồi vẫn retry mỗi lần dùng; không cron, không nhắc kết nối lại

Webhook đơn hàng

344

không vào hàng đợi mà vẫn trả 200. Nhét cả ctx.state vào task

Shopify Admin

~10,7k/ngày

gọi inline trong webhook bị throttle; đọc khách trả rỗng, tag bị bỏ

Webhook gửi merchant

10.491

lỗi giả: 2xx kèm body không phải JSON thành 500

Email của Joy

~18k/ngày

thử custom domain cho cả shop chưa xác thực domain

05

Mục tiêu

Một nền tảng
integration chung

Xây một lần, chứng minh trên một app trước (Omnisend event cho phần gửi, Klaviyo cho phần health), rồi từng app chuyển sang sau một cờ bật/tắt.

5.1 · Kiến trúc mục tiêu

Nhận bền, gửi đúng một lần, biết tình trạng, báo merchant

Kiến trúc integration mục tiêuBa làn: Joy gửi cho đối tác qua delivery worker bền; đối tác gửi webhook qua verifier và lưu bền; đối tác gọi Joy qua API F1. Cả ba dùng chung registry, credential theo tham chiếu, health service đổ ra giao diện merchant, và metric kết quả. 1 · GỬI RA · Joy → đối tác 2 · NHẬN VÀO · webhook đối tác → Joy 3 · ĐỐI TÁC GỌI JOY NỀN CHUNG · mọi app đều dùng Sự kiện trong Joy điểm, tier, đơn, profile Bản ghi chờ deliveryId cố định, lưu trước Delivery worker queue Cloud Tasks riêng · xếp lượt theo shop đúng giới hạn đối tác Adapter từng app Klaviyo, Omnisend, Postscript… dedupe nếu đối tác hỗ trợ API đối tác Klaviyo, Omnisend, … Kết quả thành công · thử lại sau mơ hồ → cách ly Sweeper sửa lần bàn giao lỗi Webhook đối tác review, Loop, Recharge Verifier chữ ký + đúng shop Lưu xong mới trả 200 nhận bền, chống trùng Xử lý loyalty cộng điểm, ghi review App đối tác Loop, Tapcart, Okendo API đối tác F1 key theo phạm vi route mặc định chặn REST v2 khách, điểm, tier, reward Integration registry mỗi app một module Credential nạp theo tham chiếu không đi trong message Health service connected · degraded · auth_broken Merchant nhìn thấy badge, banner, re-sync, email Metric + cảnh báo tỷ lệ thành công theo app kết quả + lỗi auth

5.1b · Mỗi đối tác một kiểu · Joy gửi ra

Cùng một nền chung, nhưng mỗi đối tác có luật riêng

Phần khác nhau nằm trong adapter của từng app; delivery worker chỉ hỏi adapter "bao giờ được gửi lại" và "có chống trùng không".

Đối tácXác thựcGiới hạnKhi bận (429)Chống trùngĐiểm riêng
KlaviyoOAuth (hoặc private key)Theo tài khoản + app, chia theo loại API (event 350/giây, bulk 10/giây)Header Retry-AfterCó: unique_idRefresh token tối đa 10 lần/phút; bulk không xoá được thuộc tính
OmnisendAPI key / OAuth400/phút cho cả brand, dùng chung với app khácretryAfter trong body (một số API)Không chống trùng event automationĐã chuyển sang API theo ngày, Joy vẫn dùng /v5
MailchimpOAuth10 kết nối chạy cùng lúc (không tính theo tốc độ)Không cóGhi theo email, lặp lại an toànBatch không theo thứ tự
AttentiveOAuthSubscribe 10/giâyHeader x-ratelimit-*Chưa rõĐăng ký lại người đã đăng ký → khách nhận SMS
GorgiasOAuth80 lần / 20 giây——Joy đang tự giới hạn 35/20 giây trong RAM; hỏng invalid_client từ 05/11
InstagramOAuth Meta———Token sống 60 ngày, phải refresh trước khi hết hạn
LINEChannel tokenQuota theo thángKhông có headerCó: X-Line-Retry-Key (24 giờ)429 có thể là hết quota tháng, thử lại vô ích
Postscript (mới)Partner key + key của shop15/giây cho mỗi cặp đối tác–shopMã lỗi 3002, không headerexternal_id chưa chắc chống trùngTối đa 50 thuộc tính/khách; không bao giờ tự đăng ký khách

5.1c · Mỗi đối tác một kiểu · đối tác gửi vào Joy

Mỗi nguồn webhook ký và gửi lại theo cách riêng

Verifier có một hợp đồng chung, nhưng cách kiểm chữ ký là riêng cho từng nhà cung cấp.

NguồnCách kiểm thật / giảKhi Joy trả lỗiChống trùng / ghi chú
Shopify webhookHMAC trên body gốcTimeout 5 giây; lỗi thì gửi lại 8 lần trong 4 giờ, rồi tự xoá subscriptionX-Shopify-Webhook-Id (Joy đang dùng Event-Id)
Shopify Flow actionHMACGửi lại tới 36 giờ, kể cả khi timeout hoặc 429action_run_id
Judge.meHeader JUDGEME-HMAC-SHA256, ký bằng secret app OAuth của Joy——
LooxHMAC, chỉ khi merchant tự đặt key (gói Convert/Unlimited)——
FeraJWT trong URL, ký bằng secret của shop mà Joy đã có—Kiểm được ngay
YotpoKhông ký → dùng mã bí mật trong URLGửi lại ít nhất 10 lầnWebhookMessageId
StampedSecret gửi trong header, không ký body——
RechargeX-Recharge-Hmac-Sha256 = SHA-256(secret + body); Joy chưa có secretLỗi thì gửi lại rồi xoá webhook—
Loop (mới)X-Loop-Signature, secret của merchantTimeout 10 giây; gửi lại 5 lần; có thể nhận hơn một lầnTopic return, trigger return.closed; tự suy ra "đổi hàng"

Nguồn: tài liệu API chính thức của từng đối tác, đối chiếu ngày 20/11 (verify-partner-api-A/B.md).

5.3 · Bảy nguyên tắc thiết kế

Bảy nguyên tắc, nói ngắn gọn

1

Mỗi app là một module riêng

Thêm app mới chỉ cần viết module của app đó, không phải sửa 30 file.

Không chọn: lưu cấu hình app trong database (vẫn phải viết code, lại khó test).

2

Mọi lần gửi đi qua một hàng đợi riêng

Mỗi lần gửi có mã riêng. Đối tác có chống trùng (Klaviyo, LINE) thì nhận đúng một lần; đối tác không có thì lần không rõ kết quả được giữ lại để kiểm.

Không chọn: bật "thử lại" cho hàng đợi chung (sẽ chạy lại cả trăm việc không liên quan).

3

Trạng thái kết nối chỉ một nơi quyết định

Làm lần lượt từng app, bắt đầu từ Klaviyo.

Không chọn: đổi hết một lần trong khi 7 chỗ khác vẫn đang ghi.

4

Token không đi kèm trong tin nhắn

Bộ gửi tự lấy token khi chạy, nên việc cũ không chạy nhầm token mới.

Không chọn: chuyển hết token sang Secret Manager ngay (quá lớn, chặn việc khác).

5

Đối tác dùng key riêng

Merchant cấp key cho từng đối tác, và key chỉ mở đúng các API cần dùng.

Không chọn: dùng chung key của shop (mở toàn quyền).

6

Chuyển từng app một

Mỗi app có một công tắc; lỗi thì tắt là quay về cách cũ.

Không chọn: một công tắc cho tất cả, đổi trong một lần.

7

Mất kết nối thì tạm dừng và báo

Không xoá token, không tự ngắt; merchant kết nối lại là chạy tiếp.

Không chọn: tự ngắt và thu hồi quyền như Klaviyo đang làm.

Tóm lại

Gửi chắc chắn, không gửi trùng, biết app nào đang hỏng, và mọi thay đổi đều có đường quay lại.

06

Việc phải làm

62 việc,
năm nhóm

1 · Chặn mất dữ liệu ngay

5 ngày, trước Black Friday

2 · Sửa lỗi từng app

Klaviyo, Omnisend, Gorgias…

3 · Xây nền tảng chung

hàng đợi gửi, theo dõi kết nối

4 · App mới

Flow, Tapcart, Loop, Postscript

5 · API cho đối tác

và dọn những thứ đã chết

Chi tiết từng việc (làm gì, ở đâu trong code, thế nào là xong) nằm trong roadmap.md.

Nhóm 1

20/11 → 25/11

Làm ngay trong 5 ngày: việc nhỏ, dễ quay lại, phần lớn không cần deploy

Bật 3 cảnh báokhi dữ liệu bị bỏ, khi Klaviyo mất quyền, khi đơn hàng không vào hàng đợi → biết sự cố ngay, không đợi merchant báo
Xoá thông tin nhạy cảm khỏi logkey Mailchimp, header Apple Wallet, địa chỉ khách, email người nhận đang bị ghi ra log
Trang khách hàng thôi hỏi app chưa kết nốibớt hơn 40 nghìn dòng lỗi do chính Joy gây ra
Kiểm chữ ký webhook reviewshop nào đã có key thì bắt buộc kiểm → chặn review giả
Đánh dấu kết nối đã chếtKlaviyo, Gorgias: chỉ ghi nhận shop nào, chưa thay đổi gì
Thử Omnisend trên sandboxxem Joy có vô tình huỷ đăng ký nhận tin của khách không; nếu có thì dừng mọi đồng bộ hàng loạt
Tìm đơn chưa được cộng điểm344 webhook bị mất; chỉ đọc để đếm, chưa tự cộng điểm
Support gọi các shop có kết nối chếtmời kết nối lại, không khuyên ngắt kết nối
Gỡ hướng dẫn Tapcartbài hướng dẫn công khai đang làm lộ key
Gắn nhãn ticket theo integrationđể so số ticket trước và sau khi sửa

Nhóm 2

Đợt 1 – 3

Sửa lỗi từng app: lỗi nào cũng phải tự thử lại, dừng hẳn, hoặc báo cho merchant

Klaviyo

  • Mất quyền thì dừng gọi và báo merchant, không thử lại hàng tuần
  • Sửa 2 lỗi trong đoạn thử lại
  • Gửi thêm số điểm sắp hết hạn, điểm còn thiếu để lên hạng

Omnisend · Mailchimp · Drip · Attentive

  • Omnisend: kết nối lại không làm tắt event
  • Mailchimp: một shop lỗi không kéo cả cron dừng
  • Drip: lỗi thoáng qua không bị tính là mất kết nối
  • Attentive: chỉ đăng ký khách đã đồng ý và chưa đăng ký (đăng ký lại sẽ nhắn SMS cho khách)

Gorgias · Instagram · Chatty

  • Gorgias: hết vòng lặp lỗi, tìm vì sao hỏng từ 05/11
  • Instagram: phiên hết hạn thì nhắc merchant kết nối lại; đổi app secret
  • Chatty: bỏ key dùng chung cho mọi shop

Webhook đơn hàng Shopify

  • Lưu đơn xong mới trả lời Shopify, đơn lớn cũng không mất
  • Không nhận được thì báo lỗi để Shopify gửi lại
  • Gọi Shopify bị nghẽn thì xếp hàng thử lại, không bỏ

Flow · Webhook gửi merchant · Email

  • Flow lỗi thì báo lỗi rõ ràng, không giả vờ thành công
  • Merchant trả "ok" là thành công, hết 10 nghìn lỗi giả
  • Chặn URL webhook / máy chủ SMTP trỏ vào mạng nội bộ
  • Email: chỉ thử domain riêng khi đã xác thực; mã hoá lại mật khẩu SMTP

Review · Joy Subscription · dọn hậu quả

  • Loox: tạo key chữ ký cho shop còn thiếu
  • Joy Subscription: sửa lỗi Shopify gửi lại bị coi là "đã xử lý"
  • Đồng bộ lại cho các shop đã mất dữ liệu (từng shop, có duyệt)

Sửa thế nào · 1 / 2 · gửi dữ liệu và kết nối

Vấn đề → cách sửa → được gì

Đối tác bận (429) là Joy bỏ dữ liệu

Joy thử lại ngay vài lần trong vài giây rồi bỏ luôn. 205 nghìn lần trong 18 ngày.

Mọi lần gửi đi qua hàng đợi chung. Đối tác bận thì hẹn giờ gửi lại theo luật riêng của từng đối tác, không bỏ. Ngân sách gửi để thấp hơn giới hạn công bố vì quota dùng chung với app khác của merchant.

Không mất dữ liệu; lần gửi không rõ kết quả được giữ lại để kiểm

Thao tác lớn làm nghẽn Klaviyo

Một shop hạ hạng hàng loạt sinh ra hàng chục nghìn lần gọi Klaviyo, mỗi khách một lần.

Gom lại thành một job đồng bộ hàng loạt, Klaviyo xử lý một lần.

Hết những đợt nghẽn như ngày 13/11

Kết nối đã chết mà vẫn gọi

Klaviyo, Gorgias, Instagram, Mailchimp hết quyền vẫn bị gọi hàng tuần; merchant vẫn thấy "Connected".

Phát hiện mất quyền thì dừng gọi, giữ token, hiện banner cho merchant. Kết nối lại thì tự đồng bộ lại.

Merchant biết và tự sửa được

Admin tự gây lỗi

Mỗi lần mở trang khách hàng, admin hỏi Klaviyo/Omnisend cả khi shop chưa kết nối.

Chỉ hỏi những app shop đã kết nối.

Giảm 80% lỗi Klaviyo trong log

Gorgias lặp lỗi liên tục

Từ 05/11, refresh token thất bại rồi sinh thêm lỗi khác, ~8.900 dòng/ngày.

Lỗi refresh thì đánh dấu mất kết nối; song song kiểm tra tài khoản OAuth Gorgias của Joy.

Hết vòng lặp, 8 tài khoản được báo

Mailchimp cron dừng cả loạt

Một shop lỗi làm cả cron dừng; job treo mãi ở trạng thái "đang đồng bộ".

Mỗi shop chạy riêng; job lỗi quá số lần thì đánh dấu thất bại.

Shop khác không bị kéo theo

Sửa thế nào · 2 / 2 · Shopify, webhook, email, bảo mật

Vấn đề → cách sửa → được gì

Đơn hàng bị mất điểm

Đơn lớn không vào được hàng đợi, nhưng Joy vẫn báo Shopify là "đã nhận". 344 đơn.

Lưu đơn trước rồi mới trả lời Shopify. Hàng đợi chỉ giữ mã đơn nên không còn quá to. Lưu không được thì báo lỗi để Shopify gửi lại.

Không mất đơn nào

Gọi Shopify bị nghẽn

Bị Shopify chặn tạm thời thì Joy coi như không có dữ liệu, gắn tag cũng bỏ qua. ~10,7 nghìn lần/ngày.

Bị chặn thì xếp hàng gọi lại sau; gắn tag số lượng lớn thì dùng bulk.

Tag và dữ liệu khách không bị thiếu

Webhook gửi merchant báo lỗi giả

Server merchant trả "ok" là Joy tính lỗi; còn lỗi thật thì lại không gửi lại.

Server trả thành công là thành công. Lỗi thật thì tự gửi lại sau.

Hết 10.491 lỗi giả

Thông tin nhạy cảm trong log

Log ghi cả key, header, địa chỉ khách, email người nhận.

Log chỉ ghi loại lỗi, mã lỗi và id.

Không còn dòng log lộ secret mới

Webhook review không kiểm

Bốn app review không ký; Recharge không xác thực. Ai biết URL cũng gửi review giả được.

Mỗi nhà cung cấp một cách: Fera đã ký sẵn (kiểm được ngay); Recharge cần thêm secret của app Recharge; Yotpo không ký được nên dùng mã bí mật trong URL. Có giai đoạn chuyển tiếp để không chặn nhầm.

Chặn review và đơn giả

Flow, email, Joy Subscription

Flow lỗi vẫn báo thành công; email thử domain riêng của shop chưa có (~18 nghìn lần/ngày); Joy Subscription bỏ qua lần Shopify gửi lại.

Flow báo lỗi rõ; email kiểm domain đã xác thực trước; Joy Subscription lưu xong mới đánh dấu đã xử lý.

Lỗi hiện ra để sửa; bớt 95% nhiễu email

Lỗi tiềm ẩn · từ tài liệu đối tác, log chưa thấy

Chưa thành lỗi trong log, nhưng sẽ thành lỗi nếu bỏ qua

Tìm ra khi đối chiếu cách sửa với tài liệu API chính thức của từng đối tác. Mỗi thẻ: chuyện gì có thể xảy ra → làm gì.

Recharge có thể đang tự xoá webhook

Nếu handler của Joy trả mã khác 2xx, Recharge sẽ gửi lại rồi xoá webhook. Joy chưa lưu secret để kiểm chữ ký Recharge.

Kiểm mã trả về trên staging; chọn cách lấy secret (xin shop hay mã trong URL) khi làm verifier.

Attentive: đăng ký lại = nhắn SMS cho khách

Mỗi lần đồng bộ hàng loạt gọi subscribe cho cả người đã đăng ký, Attentive nhắn SMS cho họ.

Chỉ gọi subscribe cho khách đã đồng ý và chưa đăng ký; giới hạn 10 lần/giây.

Omnisend đã thay API /v5

Joy vẫn gọi /v5; Omnisend chuyển sang API theo ngày (2026-03-15), chưa báo ngày tắt.

Adapter mới viết theo API mới; hỏi Omnisend ngày tắt /v5.

Omnisend không chống trùng event

Gửi lại một event có thể làm automation của merchant chạy 2 lần.

Lần gửi không rõ kết quả được giữ lại để kiểm, không tự gửi lại.

Mailchimp tự đăng ký khách mới

Khách mới được thêm vào list ở trạng thái "subscribed" mà không kiểm consent.

Kiểm lại cùng lúc với việc sửa consent của Attentive.

Shopify: chống trùng sai khoá

Shopify khuyên dùng X-Shopify-Webhook-Id; Joy đang dùng X-Shopify-Event-Id cho mọi topic.

Đổi khoá chống trùng khi làm webhook đơn hàng.

Klaviyo: refresh token giới hạn 10 lần/phút

Joy refresh mỗi lần gặp 401, không khoá; 429 từ endpoint token dễ bị hiểu nhầm là mất quyền.

Refresh tuần tự theo shop; 429 ở endpoint token là lỗi tạm, không đánh dấu mất kết nối.

Smax còn dùng không?

Có batch lưu lại nhưng không ai xử lý.

Winn xác nhận; còn dùng thì xử lý nốt, không thì gỡ code.

Loop, Postscript: chưa chắc làm được như thiết kế

Loop không có trường "khách chọn đổi hàng"; Postscript không ghi rõ có chống trùng theo external_id.

Thử trên dữ liệu thật / shop test trong spike trước khi làm.

Nhóm 3

làm thử trên một app trước

Xây nền tảng chung: làm một lần, mọi app dùng

Hàng đợi gửi chung

Mọi app gửi qua một chỗ. Đối tác bận thì tự gửi lại, không gửi trùng, không âm thầm bỏ. Làm thử Omnisend trước.

Theo dõi tình trạng kết nối

Biết app nào đang tốt, chập chờn hay mất kết nối. Mất kết nối thì dừng gọi, giữ token. Làm Klaviyo trước.

Màn hình cho merchant

Banner kiểu "Klaviyo mất kết nối, email sinh nhật đang dừng", kèm nút kết nối lại và đồng bộ lại.

Kiểm webhook đối tác

Chỉ nhận dữ liệu thật, từ đúng đối tác, cho đúng shop.

Đồng bộ hàng loạt

Thao tác lớn chạy thành một job, không thành hàng chục nghìn lần gọi.

Công cụ cho support

Xem shop gửi lỗi những gì và bấm gửi lại.

Danh mục app

Mỗi app khai báo ở một chỗ, có test bắt lỗi khi quên sửa chỗ nào.

Đo và cảnh báo

Tỷ lệ thành công của từng app, có cảnh báo khi tụt.

Nhóm 4

App mới

App mới: chọn app tốt, hợp với Joy, đối thủ đã làm hoặc Joy làm được trước

Đợt 1

Flow cho app review

Okendo, REVIEWS.io, Junip, Growave. Làm nhanh, Rivo cũng làm theo cách này.

Đợt 2

Tapcart (app mobile)

5/9 đối thủ đã có. Phải sửa lỗi lộ key trước khi làm tiếp.

Đợt 2 – 3

Loop (đổi trả)

Lên listing trước. Điểm mạnh: chưa đối thủ nào cộng điểm khi khách chọn đổi hàng thay vì hoàn tiền.

Đợt 3

Postscript (SMS)

Ưu tiên số một, 6/9 đối thủ đã có. Cần hàng đợi gửi chung xong trước để không gửi trùng SMS.

tìm hiểu

App subscription

Skio, Loop Subscriptions, Stay AI: sáu app loyalty khác đã có mặt, Joy thì chưa.

Làm ngay: nộp hồ sơ đối tác với Postscript, Loop, Tapcart; đo xem shop trả phí của Joy đang dùng app nào.
Sau 17/02: app đổi trả (Redo, AfterShip), Gladly, Zendesk (cho nhân viên CSKH chỉnh điểm ngay trong ticket, chưa đối thủ nào có).

Nhóm 5

API cho đối tác & dọn dẹp

Cho đối tác một API an toàn, dọn những thứ đã chết

Đợt 1

API đối tác F1

Merchant tạo key riêng cho từng đối tác. Key chỉ mở đúng phần cần: khách hàng, xem hạng, xem phần thưởng, cộng/trừ điểm. Mỗi đối tác có giới hạn lượt gọi riêng và thu hồi được bất cứ lúc nào. Loop, Tapcart, Okendo sẽ dùng API này.

Cần chốt trước 25/11 đối tác dùng API trên gói nào

·Test tự động cho REST API
·REST v1: đếm ai còn dùng, đưa bảng chuyển sang v2
·Báo ngừng REST v1 từ bây giờ, tắt hẳn sau ít nhất 90 ngày
·Quy tắc đánh version và kênh thông báo cho developer
·Smax: xử lý nốt dữ liệu đang tồn hoặc gỡ bỏ
·17 card integration chỉ là link: ghi rõ là link

7 · Thứ tự và mốc thời gian

Mỗi tuần bật một thay đổi lớn, theo dõi ít nhất 3 ngày rồi mới làm tiếp

20/11 → 25/11

Đợt 0

  • Toàn bộ Nhóm 1
  • Chặn lộ secret, bớt lỗi giả, bật cảnh báo
25/11đã gọi shop, biết kết quả Omnisend, log sạch secret, đã chốt gói cho F1
26/11 → 01/12

Black Friday

  • Không deploy
  • Chỉ viết code trên branch và thử nghiệm
LUẬTchỉ Winn deploy, và chỉ khi merchant đang mất dữ liệu
02/12 → 18/12

Đợt 1

  • Sửa các lỗi nhỏ
  • Hàng đợi gửi chung: thử với Omnisend
  • Theo dõi kết nối Klaviyo (chỉ ghi nhận)
  • Webhook đơn hàng không mất nữa
  • Flow review, API F1
18/12Omnisend gửi thành công ≥ 99%, không trùng; hết lỗi webhook giả
21/12 → 18/01

Đợt 2

  • Tuần lễ: chỉ quan sát
  • Từ 04/01: banner báo mất kết nối Klaviyo
  • Thêm app vào hàng đợi chung, kiểm webhook
  • Tapcart, listing Loop
18/01merchant thấy banner; Tapcart chạy; so ticket với trước
19/01 → 17/02

Đợt 3

  • Chuyển nốt các app
  • Gửi lại webhook cho merchant
  • Cảnh báo, công cụ support
  • Báo ngừng REST v1; Postscript beta; cộng điểm Loop
17/02app nào cũng có cảnh báo khi gửi lỗi

Nghỉ Tết 04/02 → 10/02. Thay đổi lớn chỉ bắt đầu từ tuần 04/01.

7.2 · An toàn khi bật thay đổi

Trước khi bật, phải đo được nó; hỏng thì quay lại được ngay

Thay đổiPhải theo dõi đượcKhi nào quay lạiQuay lại bằng cách
Các sửa nhỏ đầu tiênCảnh báo dữ liệu bị bỏ và lỗi KlaviyoCó lỗi lạ mới xuất hiệnDeploy lại bản cũ, dưới 30 phút
Hàng đợi gửi chung, từng appSố gửi thành công / thử lại / lỗi của từng app; có gửi trùng khôngThành công thấp hơn cách cũ, hoặc có gửi trùngTắt công tắc của app đó, dưới 15 phút
Báo "mất kết nối"Bao nhiêu shop bị báo nhầmBáo nhầm vượt ngưỡngTắt công tắc, chạy script trả trạng thái cũ
Webhook đơn hàng trả lỗi thậtMột tuần chạy thử chỉ ghi nhậnLỗi tăng hơn lúc chạy thửDeploy lại bản cũ, đăng ký lại webhook
Bắt buộc kiểm chữ kýShop nào còn gửi không kýChặn nhầm dữ liệu thậtBật lại chế độ chấp nhận cả hai
Mã hoá lại SMTP, đổi key TapcartLỗi giải mã, lỗi gửi email, danh sách shopLỗi tăng đột biếnVẫn đọc được bản cũ; đổi từng shop một

Thay đổi nào merchant nhìn thấy cũng có sẵn bài hướng dẫn, mẫu trả lời cho support và một dòng giải thích trong app.

8 · Cần anh/Winn quyết

Năm quyết định đang chặn việc

1

Ai làm phần app mới?

Tuyển, mượn một dev 8–10 tuần, hay tạm chỉ làm phần sửa lỗi. Trước 02/12 · chặn Flow, Loop, Postscript, F1

2

Đối tác dùng API trên gói nào?

Free có được dùng không, có tính vào quota của merchant không. Winn + product · 25/11 · chặn F1, Loop, Tapcart

3

Gorgias hỏng từ 05/11 vì sao?

Tài khoản OAuth của Joy bên Gorgias còn dùng được không; thử refresh một tài khoản đang tốt. Trước 25/11

4

Khi nào báo "mất kết nối"?

Chấp nhận báo nhầm bao nhiêu; có tự ngắt không; merchant có thấy "chập chờn" không. Trước 04/01

5

Gửi không rõ kết quả thì sao?

Chấp nhận trùng, chấp nhận thiếu, hay người kiểm tay; giữ lại tối đa bao lâu cho từng đối tác. Tạm thời Omnisend event mặc định giữ lại để kiểm. Trước Đợt 2 · chặn Postscript

Nếu không có người cho app mới: vẫn làm hết phần sửa lỗi và chống mất dữ liệu; F1 chỉ làm bản đọc dữ liệu; Flow lùi lại; quý này chưa làm Postscript và cộng điểm Loop.

9 · Rủi ro

Cái gì có thể sai, và đã tính cách xử lý

Báo nhầm "mất kết nối"

Chạy một tuần chỉ ghi nhận trước; không xoá token nên báo nhầm cũng không hỏng gì

Gửi trùng

Mỗi lần gửi có mã riêng; lần nào không rõ thì giữ lại cho người kiểm

Omnisend huỷ đăng ký khách

Nếu đúng, đồng bộ hàng loạt sẽ nhân thiệt hại → chưa có kết quả thử thì chưa chạy

Đổi key Tapcart

Làm hỏng block cũ → đổi từng shop, sau khi block mới đã chạy

Gửi lại dữ liệu khách đã xoá

Trước khi gửi luôn kiểm khách còn được phép gửi không

Chi phí log tăng

Chỉ ghi mẫu, có ngân sách, để riêng một bucket

Staging thiếu cấu hình

Test lỗi sai lý do → chuẩn bị queue/index trên staging trước

Ticket tăng lúc đầu

Lỗi trước đây im lặng nay hiện ra → so sánh có tính phần này

Ngoài tầm Joy

Không có người; đối tác duyệt chậm; Chatty cập nhật chậm

Lớn hơn dự tính

Cắt bớt phạm vi, không bao giờ bỏ bước an toàn

5 ngày tới

Chặn mất dữ liệu
trước BFCM.

20/11 số liệu nền + 3 cảnh báo trước 25/11 gỡ secret khỏi log · tắt dò · có kết quả consent · tìm ra đơn mất điểm · liên hệ shop credential chết · chốt luật F1

Nguồn: roadmap.md v7 và integration-usage-counts.md, plans/261119-2330-integrations-roadmap.