Source document: docs/pilot/PARTNER-ONBOARDING-PACKAGE.md
Source version: 0.0.0
Generated time: 2026-07-06T14:59:19.735Z
Owner: Operations / Founder
Audience: Internal
Status: Approved

Partner Onboarding Package

Danh mục chính xác những gì một đối tác nhận được khi onboard. Không chứa secret.
Nguồn tài liệu: docs/integration/ (Partner Integration Kit) + docs/operations/.

1. Bộ tài liệu bàn giao (partner nhận)

Hạng mục	File	Mô tả
Integration Guide	`docs/integration/PARTNER-INTEGRATION-GUIDE.md`	Tổng quan kiến trúc, auth, error handling, retry, idempotency, booking lifecycle, best practices, troubleshooting.
OpenAPI	`docs/integration/openapi.yaml`	Contract máy-đọc (9 operation), khớp implementation.
Postman Collection	`docs/integration/bng-booking.postman_collection.json` + `.postman_environment.json`	Health/Availability/Pricing/Booking/Confirm/Cancel + environment mẫu (không secret).
Code Samples	`docs/integration/examples/`	curl · JavaScript · Python, mỗi ví dụ chạy độc lập (đã kiểm chứng `curl/flow.sh` end-to-end).
Sandbox Checklist	`docs/integration/PARTNER-SANDBOX-CHECKLIST.md`	Lộ trình 30 phút / 2 giờ / 1 ngày, mỗi bước có tiêu chí PASS.
Error Catalog	`docs/integration/API-ERROR-CATALOG.md`	Mọi mã lỗi + HTTP status + hướng xử lý + ma trận retry.

2. Thông tin kết nối (BNG cấp riêng cho từng partner)

BNG bàn giao qua kênh onboarding (không nằm trong repo):

Base URL sandbox: https://staging-api.booking.bngagency.vn
API Key sandbox — cấp qua ops issue-key, giao một lần qua one-time secret link / password manager. Bí mật server-to-server.
Danh sách unitId sandbox hợp lệ (vd u_muongthanh_deluxe) — để gọi Availability/Booking.
Xác nhận IP đã allowlist (xem mục 3).

3. API Key Request Process

Partner gửi BNG: tên tổ chức, môi trường (sandbox), IP egress (server sẽ gọi API).
BNG:

create-partner → activate-partner → provision-tenant → activate-tenant → seed-inventory (hoặc gắn inventory thật).
Allowlist IP egress của partner trên nginx staging (bắt buộc — /api/booking/* trả 403 nếu chưa).
issue-key --customer <partnerId> --env sandbox --deliver → giao raw key một lần.

Partner nhận key + base URL + unit IDs + xác nhận allowlist → bắt đầu theo Sandbox Checklist.

Raw key hiển thị đúng một lần. Mất/lộ → BNG rotate-key. Không self-serve.

4. Support Contact Process

Kênh: (BNG điền — email/Slack/Zalo onboarding). Không gửi API key qua kênh thô.
Khi báo lỗi, gửi: endpoint đã gọi · payload (ẩn PII) · x-request-id (partner tự sinh mỗi request) · HTTP status · error.code. KHÔNG gửi API key.
Tự phục vụ trước khi hỏi: đọc API-ERROR-CATALOG.md (rẽ nhánh theo error.code) + mục Troubleshooting trong Integration Guide.
SLA / giờ hỗ trợ: (BNG điền).

5. Điều kiện hoàn tất onboarding (Definition of Ready cho partner)

Nhận đủ bộ tài liệu (mục 1).
Nhận API key + base URL + unit IDs (mục 2).
IP đã được allowlist (xác nhận: GET /api/booking/availability không trả 403 nginx).
Hoàn thành Availability → Booking → Confirm → Cancel theo Sandbox Checklist.

Nguồn sự thật (Source of Truth): docs/pilot/PARTNER-ONBOARDING-PACKAGE.md · v0.0.0 · sinh tự động lúc 2026-07-06T14:59:19.735Z. Trang này là view suy dẫn — không sửa trực tiếp.