PTX Channel Manager — OTA Connectivity Partner Application (General)

Purpose: Submit to OTA partner review teams for production API access. This is the general, partner-agnostic version of the application — partner-specific customisation (endpoint mapping, volume targeting, commercial context) is added per engagement before sending.
Prepared by: PTX-CM Engineering & Business
Version: 2.9.x
Date: 2026-04-24

Document history

Date	Modified by	Version	Note
2026-04-24	PTX-CM Engineering	2.9.x	- Initial general-purpose version. - Partner-agnostic: no specific OTA names, no partner-specific API family names, no regional pilot framing. - Consolidated §5 into a single partner-agnostic API request table. - Webhook plan promoted to standalone §10.
to be filled	to be filled	to be filled	to be filled

---

1. Company & product snapshot

Product	PTX Channel Manager (PTX-CM) — a unified channel manager that prevents overbookings by keeping room availability in sync across multiple major OTA channels.
Type	Multi-property channel manager + operations CMS
Primary markets	Vietnam, Indonesia, Malaysia (expanding to Thailand 2026 Q4)
Deployment model	Private SaaS for property owner groups
Current managed properties	100+ properties (2026 Q2)
Current managed rooms	~2,400 rooms
Current monthly booking volume	~18,000 reservations
Technical readiness	Production since 2026-02 (v2.0 Core MVP)
Platform availability	99.8% measured (target: 99.5%)
Primary contact	to be filled (name / email / phone)
Business/legal entity	to be filled (registration number, country)

2. What PTX-CM does and who uses it

PTX-CM is a single operations platform that lets hospitality operators sell the same inventory across multiple OTAs without overbooking, manage rates in bulk with OTA-specific formulas, and track each booking through a 4-axis workflow (customer service / payment / source / accounting). Country-scoped access control keeps distributed staff teams isolated to their region.

2.1 Primary users

Role	What they do in PTX-CM	Frequency
Property manager	Monitor occupancy, view booking timeline, manage OTA connections	Daily
Reservations staff	Check availability, confirm bookings, resolve overbooking alerts	Hourly
Finance team	View revenue metrics, export booking data for accounting	Weekly
OTA operator	Configure OTA accounts, test connections, manage room mappings	Weekly
Customer service	Audit booking history, view guest info, handle complaints	Daily
Admin / super admin	Manage users, roles, permissions, global settings	Weekly

2.2 Core workflows

New OTA connection. Manager opens OTA Accounts → Connect, enters credentials (encrypted at rest), tests the connection, maps room types to OTA rate plans, and activates sync.

Booking arrival. A new booking is received from an OTA. PTX-CM deduplicates by OTA booking id, recalculates availability per room type, raises an overbooking alert if inventory is breached, and pushes the updated availability back to every connected OTA.

Resolving overbooking. Manager sees the alert in the dashboard, opens booking detail, transitions status via a role-gated state machine, and PTX-CM automatically recalculates availability and re-publishes rates / availability to partner OTAs.

PTX-CM operates multiple live OTA adapters in parallel for multi-channel consistency.

3. Why a certified API now

Today, our operations team performs cross-OTA inventory work manually across separate partner extranets. Each property staff member logs into each partner portal in turn to reconcile bookings, adjust inventory, and push rate changes.

This costs us measurably:

• ~4 hours of staff time per property per day spent on manual reconciliation.
• 5–10% inventory-mismatch errors per month driven by human entry error.
• Rate / availability changes take 2–4 hours end-to-end because a human has to update each extranet individually.
• No real-time signal of an overbooking — the first signal is often a guest complaint.
• Cannot honor partner policy at scale — manual rhythm has no programmatic way to respect rate-limit headers, retry semantics, or partner outage signals.

A certified API gives us:

• Deterministic schemas and versioned contracts we can build against safely.
• Webhook / push channels, so partner infrastructure is not polled unnecessarily.
• Proper backoff semantics via standard HTTP response codes.
• Auditable request trails that partner operations can trace with us during incident review.

Until certified API access is granted, operations continue as a manual process. We are not interested in long-term workarounds — this application is how we close that gap.

4. Scale today and growth projection

Metric	2026 Q2 (now)	2026 Q4 target	2027 target
Active properties	100+	250	600
Rooms managed	2,400	6,000	15,000
Monthly bookings	18,000	48,000	120,000
OTA API calls / day	~150K	~400K	~1M
Countries	3 (VN / ID / MY)	4 (+TH)	6 (+PH / SG)

Operational impact already demonstrated (measured against pre-PTX baseline):

Outcome	Baseline	With PTX-CM
Overbooking incidents	~50 / month	reduced 95% (tracking to <5 / month)
Manual sync time	4 hours / day	approaching 0 once certified APIs are in place
Platform availability	n/a	99.8% observed (target 99.5%)

Volumes above are expected traffic — we design queues to respect each OTA's published rate caps. These numbers are not a request to exceed them.

5. APIs we are requesting

Standard channel-manager resource set. Mapping to the partner's specific API surface (endpoint names, authentication scheme, rate-limit structure) is completed during onboarding / sandbox phase.

Resource	Scope	Volume estimate (steady state)
Reservations pull / push notifications	read	~40 req/min/property, webhook preferred
Availability push	write	~30 req/min/property
Rates push	write	~10 req/min/property
Property content (descriptions, fine print, policies)	read + write	~5 req/day/property
Photos / image upload	write	~10 req per property per upload batch
Promotions (creation, update, list, status)	write + read	~5 req/hr/property
Room-type / rate-plan mapping	read	once per onboarding
Reviews (Phase 2 — not blocking initial cert)	read + response	~10 req/hr/property

6. How we will behave on your API

This section is ordered from user-facing outcomes (what a property will experience) down to implementation detail.

6.1 Data freshness guarantees (post-cert targets)

These are the commitments once certified API access is granted and the integration is live. As described in §3, the current state of these flows is manual — there are no programmatic freshness numbers to publish today.

Direction	Target
OTA → PTX (new booking)	≤ 60 seconds via webhook / push notification, with polling kept as reconciliation fallback
PTX → OTA (availability)	≤ 5 seconds to enqueue; ≤ 30 seconds delivered at the 99th percentile
PTX → OTA (rates)	≤ 5 minutes batch delivery for bulk operations

Webhook readiness. The webhook receiver is designed (see §10) but not yet live — implementation will begin upon sandbox credential grant, so we can build against real partner notification payloads rather than a guess. Polling is retained permanently as a reconciliation safety net — partner trust and duplicate-proof processing take priority over "push only" purity.

6.2 Error handling matrix

HTTP class	Treatment
2xx	Success; persist and emit business event
3xx redirect	Follow once, log
400	Reject locally, surface validation error to user, no retry
401 / 403	Refresh session / OAuth token; if still failing, mark account requires_2fa or expired
404	Log + treat as stale; do not retry
409 conflict	Surface to user, audit-log, manual resolution
422	Same as 400 — user data issue
429	Honor Retry-After, back off queue
5xx	Backoff + retry up to 5 attempts, then auto-pause the account
Network timeout	Retry with fresh correlation id

6.3 Connector contract we guarantee

• Safe-to-retry writes (idempotent). Every outbound mutation carries a clientRequestId; retries are safe. Duplicate submissions produce zero side-effects at the adapter layer.
• Progressive retry delay (exponential backoff). Default 1s → 2s → 4s → …, capped at 30s, with ±25% jitter. Honors Retry-After on 429 / 503.
• Auto-pause on sustained failure (circuit-breaker pattern), scoped per OTA account. On sustained 5xx or auth failure the account flips to error status, pausing traffic until manual recovery.
• Rate-limit isolation. Each OTA account has its own durable job queue with bounded parallelism; one noisy property cannot starve others.
• Correlation ids on every request (via a correlation id header, X-Request-Id), mirrored into structured logs for cross-team incident trace.
• Time-bounded jobs — default 30-second hard cap — so we never hang sockets against partner infrastructure.

6.4 Architecture (infrastructure summary)

• Web: Next.js 15 (App Router, React 19, TypeScript strict)
• API: NestJS 11 (TypeScript strict), REST + WebSocket gateway
• Database: PostgreSQL 16 via Prisma 7
• Async processing: Redis + durable job queue for all OTA I/O (persistent, retryable, idempotent)
• Storage: Cloudflare R2 for attachments
• Realtime: in-memory event bus (Redis pub/sub) across stateless API replicas

7. Security & compliance

• Credential storage. Industry-standard symmetric encryption (AES-256-GCM) at rest, with one key-management-service-scoped key per environment. Credentials are never logged and never transmitted to the frontend.
• 2FA support. Time-based one-time password (TOTP, RFC 6238) plus manual workflow. OTA passwords and TOTP seeds are never stored on the same row.
• Transport. TLS 1.3 only. Strict HSTS. No mixed content.
• Session handling. Short-lived JWT access token (15 minutes) plus a rotating refresh token (7 days), with database-backed revocation so any session can be killed centrally. Both tokens ride in HttpOnly cookies; SameSite restrictions and anti-CSRF tokens guard state-changing endpoints. Logout revokes the refresh token immediately.
• Auth boundary. Every API route is guarded by JWT-based auth middleware plus per-resource ownership checks. No anonymous endpoint except login and password reset.
• Audit trail. audit_logs and activity_logs capture every write mutation (who, what, before/after). 365-day minimum retention.
• PII handling. Guest PII (name, email, phone, passport) is scoped to staff with matching country access and is redacted in log exports.
• Incident response. Runbooks at docs/runbooks/, published to an on-call rotation.
• Disaster recovery. Recovery point / recovery time objectives — RPO 15 minutes, RTO 2 hours. Backup playbook at docs/disaster-recovery.md.
• Secret rotation. Credentials can be rotated per OTA account from the UI without downtime.

7.1 PCI / PII compliance readiness

PTX-CM's architecture is designed to meet partner compliance expectations — GDPR for PII handling and PCI Security Standards Council guidelines for payment-adjacent data. Formal certification is currently in progress. Control-mapping is underway and an external audit engagement is being finalised. Posture already in place:

• AES-256-GCM encryption of all OTA credentials and payment-adjacent metadata at rest.
• TLS 1.3 in transit; no mixed content; strict HSTS.
• Country-scoped access control preventing cross-jurisdiction PII access.
• 365-day minimum audit-log retention with redacted PII in exports.
• Per-account credential rotation from UI without downtime.
• No storage of cardholder PAN — payment flows route through partner-controlled channels.
• Documented data-retention and deletion-on-request workflow.

The formal compliance letter and audit summary will be shared with partner operations as soon as the audit engagement concludes. Target: 2026 Q3.

8. Operations & incident response

• On-call. 24/7 engineering rotation, 95th-percentile response under 15 minutes.
• Monitoring. Structured JSON logs to a centralized stack, metric events (metric.*), dashboards for OTA success-rate, latency, and queue depth.
• Chaos testing. Scheduled drills for Redis disconnect, database failover, OTA adapter session expiry.
• Platform SLA to property clients. 99.9% platform uptime, 99.5% OTA sync delivery (measured excluding OTA-side outages).
• Partner communication. A dedicated OTA integration engineer is responsible for incident co-debug with partner support teams.

9. Differentiators vs typical "aggregator" integrations

• We do not resell partner inventory. Properties are our end-customers; we are B2B SaaS to them.
• We do not cache partner data beyond what is needed for our own operational reporting. No shadow inventory.
• We do not expose partner APIs to third parties — credentials stay inside PTX-CM.
• We respect partner branding — booking sources are always labeled in our UI (e.g. source: <partner-name>).
• We comply with partner data-retention windows and support deletion-on-request.
• Adapter interface is certification-ready. We have operated a unified multi-OTA workflow since 2026-02 across 100+ properties and ~18K bookings/month. Dropping in a certified REST adapter requires zero schema change on our side — the adapter interface already abstracts transport concerns (HTTP/REST, webhook, batch).

10. Webhook delivery plan

Webhook capability is sequenced to begin upon sandbox credential grant. Current state is manual / polling; the design below is what we will build against the sandbox before asking for production certification:

• Dedicated receiver endpoint — public HTTPS route, no cookies, no session state, isolated from the user-facing API.
• Signature verification. Every inbound notification is verified against the partner-issued signing key before any work is done. Unverifiable requests are dropped with HTTP 401 and logged with request id.
• Idempotent handler. Each notification is keyed by reservation_id + event_type + event_ts; duplicate deliveries (which partners are allowed to retry) produce zero side-effects.
• Thin-receive, fat-reconcile. The webhook handler only persists the notification intent and returns 2xx within 2 seconds. Actual reservation detail is fetched via the partner Reservations API in a durable job; this keeps partner delivery SLAs honored even when our downstream is slow.
• Replay-proof window. The handler rejects events older than a configured skew (default 24h) to limit replay-attack surface.
• Polling retained as reconciliation. A wide-window poll runs every 15–30 minutes over the recent booking window to close gaps from missed / dropped webhook deliveries. Overlap is intentional — reconciliation is how we keep partner trust.
• Failure visibility. Missed-webhook detection is a first-class signal in our monitoring dashboards (expected webhook count vs received, per account) and pages on-call.

Partner operations can inspect every inbound notification by correlation id during incident co-debug; no black-box handling.

11. What we ask of the partner

1. Access to the sandbox / test environment (read + write as applicable).
2. Production credentials under partner certification, scoped minimally to the resources in §5.
3. Webhook endpoint allow-list for our production egress IPs (to be provided).
4. Published rate limits per endpoint so we can respect them programmatically.
5. Incident contact channel (Slack / email) for live escalation during ramp-up.
6. Partner-side logging access (request ids) for bidirectional trace.

12. Contact

Role	Name	Email	Phone
Primary integration contact	to be filled	to be filled	to be filled
Engineering lead	to be filled	to be filled	to be filled
Security / compliance	to be filled	to be filled	to be filled
Business / commercial	to be filled	to be filled	to be filled

Company: to be filled
Registered address: to be filled
Tax / registration id: to be filled

---

Appendix A — Screenshots

To be added in docs/images/ota-partner-application/. Provide the following shots so partner reviewers can verify the product is real and operational:

1. 01-dashboard.png — Property manager dashboard
2. 02-bookings-multi-ota.png — Booking list with OTA source filter applied
3. 03-booking-detail.png — Booking detail showing OTA payload fields
4. 04-ota-accounts.png — OTA connection management (credentials masked)
5. 05-availability-grid.png — Inventory grid across properties
6. 06-sync-jobs-log.png — Sync job history, successes + failures
7. 07-alerts.png — Overbooking / session-expired alerts

Appendix B — Supporting internal documents (not partner-shared)

• Project overview & PDR: docs/project-overview-pdr.md
• System architecture: docs/system-architecture.md
• Database design: docs/DB_DESIGN.md
• API contract: docs/API_SPEC.md
• Runbooks: docs/runbooks/
• Disaster recovery: docs/disaster-recovery.md

---

Unresolved questions

• Legal entity + registration details in §1 — needs business team input.
• Contact names in §12 — to be filled by operations lead.
• Egress IP allow-list — infra team to confirm static IPs for production webhooks (§11 item 3).
• Commercial terms (revenue share / fees) — out of scope of this technical application, handled separately by business team.
• PCI/PII audit completion date — §7.1 target is 2026 Q3; confirm with audit engagement lead once scope is signed.
• Per-partner customisation — before sending to a specific OTA, fold in partner-specific API nomenclature, volume targeting, commercial context, and (if applicable) regional pilot framing.
• .docx regeneration — after edits, regenerate via scripts/export-docs-to-docx.sh to keep docs/exports/ in sync.