Skip to content

Tài liệu kỹ thuật

Tích hợp LRS trong một buổi chiều.

Thử lại khi lỗi

LRS coi lần gửi là thành công khi endpoint trả mã 2xx. Các trường hợp khác được thử lại, tối đa 5 lần, rồi đánh dấu thất bại. Nhật ký gửi lưu 7 ngày.

EndpointGEThttps://api.lrsvn.com/v1/webhooks/{id}/deliveries

Webhook là cách gửi "ít nhất một lần": cùng một sự kiện có thể đến nhiều lần nếu phản hồi của bạn bị mất. Hãy xử lý theo id của sự kiện để không làm trùng.

Quy tắc gửi

  • Thành công là mã HTTP 2xx. Thân phản hồi bị bỏ qua (chỉ đọc tối đa 64 KB).
  • Mỗi lần gửi chờ tối đa 15 giây. LRS không đi theo chuyển hướng, nên 3xx tính là lỗi.
  • Khác 2xx, lỗi kết nối hoặc hết thời gian chờ thì thử lại. Mỗi sự kiện được gửi tối đa 5 lần, sau đó chuyển sang failed.
  • Webhook bị tắt hoặc bị xoá: các lần gửi còn chờ chuyển sang failed.
Kết quả của một lần gửiXử lý
2xxThành công — delivered.
3xxKhông theo chuyển hướng; tính là lỗi, thử lại.
4xx, 5xxLỗi, thử lại.
Timeout, lỗi mạng hoặc TLSQuá 15 giây hoặc không kết nối được: lỗi, thử lại.

Yêu cầu

cURL
curl https://api.lrsvn.com/v1/webhooks/$WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer $LRS_API_KEY"

Trả về nhật ký 7 ngày gần nhất, mới nhất trước. Hỗ trợ ?page= và ?limit=.

Phản hồi

JSON
{
  "data": [
    {
      "id": "whd_7b1e0c93a4d2f8e65c1a0b9d3e7f2a48",
      "event": "order.paid",
      "status": "delivered",
      "attempts": 1,
      "response_status": 204,
      "created_at": "2026-09-30T10:05:31Z",
      "delivered_at": "2026-09-30T10:05:32Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20 }
}

Trường phản hồi

TrườngKiểuMô tả
statusstringpending (đang chờ gửi hoặc chờ thử lại), delivered hoặc failed.
attemptsintegerSố lần đã gửi, từ 0 đến 5.
response_statusintegerMã HTTP endpoint trả về ở lần gần nhất; null nếu chưa có.
delivered_atstringThời điểm gửi thành công; null nếu chưa thành công.

Xử lý phía bạn

  1. Xác minh chữ ký trước khi đọc nội dung.
  2. Lưu id của sự kiện và trả 2xx ngay; việc nặng chuyển sang hàng đợi nội bộ.
  3. Nếu đã thấy id này, trả 2xx mà không xử lý lại.

Mã lỗi

HTTPMãKhi nào
403forbiddenPhiên đăng nhập không phải Owner hoặc Admin.
403scope_deniedAPI key không có scope organization:write.
404not_foundKhông tìm thấy webhook.