# Wikiup PMS integration — staging test data

Base URL: https://api-preview.wikiup.app

**Preview is not a live-account safety boundary.** Use a separate Wikiup/provider property with no real connected channels. Confirm exact property and room IDs. A sample name, another login or a preview hostname does not prove isolation. Do not use a live Airbnb listing to run certification exercises.

This guide uses Wikiup APIs only. No client needs database access, provider credentials or an operator provisioning script. Examples are documentation templates, not a certification runner. Certification evidence must come from ordinary PMS workflows and actual accepted tasks, not canned provider payloads.

## Credentials and scope

Send `Authorization: Bearer <owner-session-token-or-eligible-api-key>`. Room/reservation routes use `x-property-id: <isolated-property-id>`; property path routes authorize `{id}` directly. Owner access plus `property.manage` is required for staging operations. Keys are further constrained by permission level, property allowlist and expiry.

A property-restricted API key cannot create a new property. Create through an eligible owner session or unrestricted creation-capable key, then narrow subsequent credentials to the new property. Do not paste tokens into browser code, committed files, screenshots or support tickets.

## 1. Create or reuse an isolated property

1. `GET /api/properties`: inspect memberships and choose the exact target. Do not identify a property only by its display name.
2. If needed, `POST /api/properties` with `{property:{name,listingTitle,address:{line1,city,state,postalCode,country},timeZone,settings}}`. Use a clearly synthetic name/address and explicit IANA timezone. Retain the returned property ID.
3. `POST /api/rooms` with its property header and `{room:{name,listingTitle,details:{maxGuestsCount,petsAllowed},pricing:{basePrice,weekendBasePrice,minimumStay,maximumStay}}}`. Prices are major USD units; dates and rules follow property time. New rooms start Draft. Retain the returned room ID.
4. `GET /api/properties/{id}/channel-management`: inspect `workspace` and `plans`. The human owner reviews terms and explicitly sends `POST /api/properties/{id}/channel-management` with `{action:"enable",plan:"rental",termsVersion:<current plans.rental.version>,accepted:true}`. Do not hardcode terms or automatically accept a paid agreement.

No real or simulated OTA connection is necessary for Booking CRS. Existing completed setup operations and mappings are reused; uncertain creates require reconciliation, not another creation request.

## 2. Prepare Booking CRS

Use the existing route for every command:

`POST /api/properties/{id}/channel-management/sandbox-reservations`

```json
{"action":"prepare","roomId":"<isolated-room-id>"}
```

Success: HTTP 200 `{"status":"ready","roomId":"<isolated-room-id>"}`.

Preparation installs/reuses Booking CRS and provisions/reuses the room/rate mapping using saved room pricing. A new mapping needs a positive basePrice. Local ownership/mapping checks and the provider's zero-connected-channel check occur before provisioning. No booking, payment, guest email, OTA authorization or inventory publication is performed. It does not enable channel management or accept terms on behalf of the owner.

UI equivalent: Property → Channels → Booking CRS → Prepare Booking CRS, available only for an eligible owner-managed preview property without real channel connections.

## 3. Submit an external test booking

```json
{
  "action":"create",
  "requestId":"<new UUID>",
  "roomId":"<isolated-room-id>",
  "arrivalDate":"<YYYY-MM-DD>",
  "departureDate":"<YYYY-MM-DD>",
  "nightlyPriceUsd":137
}
```

Use a 1–30-night stay, departure exclusive, and a positive USD nightly price at most 100000. The server uses a fixed synthetic guest and one adult. HTTP 202 returns `{simulationId,status:"submitted",action:"create"}`. Save that simulationId. Submitted is not imported and is not a passed certification result.

By contrast, `POST /api/reservations` creates a direct Wikiup reservation. Use normal reservation screens/APIs to test that outbound event direction; do not confuse it with external revision ingestion.

## 4. Observe actual import

- `GET /api/properties/{id}/channel-management/sandbox-reservations` returns up to 25 latest simulations and their current import state.
- `delivery:"pending"`: no confirmed import yet.
- `delivery:"received"`: revision received but not applied; inspect normal workspace issues before retrying.
- `delivery:"applied"`: imported. Inspect the actual Wikiup reservation using `reservationIds`; it is not inserted by the simulator directly.
- `POST /api/properties/{id}/channel-management/sandbox-reservations` with `{"action":"verify"}` returns HTTP 200 `{simulations,verification:{applied,blocked,complete}}`. Verification checks isolation, runs normal booking revisions and acknowledges applied revisions. It does **not** publish rates, restrictions or availability. `complete:false` or nonzero blocked requires investigation even with HTTP 200.

Do not substitute main channel `sync`/`verify_publication` actions for this ingestion-only operation: those may also reconcile or publish other channel state.

## 5. Modify and cancel the recorded test booking

```json
{
  "action":"modify",
  "requestId":"<new UUID>",
  "simulationId":"<original-simulation-id>",
  "arrivalDate":"<YYYY-MM-DD>",
  "departureDate":"<YYYY-MM-DD>",
  "nightlyPriceUsd":149
}
```

```json
{"action":"cancel","requestId":"<new UUID>","simulationId":"<original-simulation-id>"}
```

Both return HTTP 202 submitted. Repeat verify/poll and inspect the real imported change. Cancellation completes when the row has `status:"canceled"` and `delivery:"applied"`. Modify changes dates/price in the recorded room; changing rooms is not supported by this simulator command. Arbitrary provider booking IDs cannot be modified/cancelled. A previously canceled simulation cannot be modified.

For simulated-channel tests only, use the same optional connectionId scope throughout create/modify/cancel/verify. It must identify an active simulated connection and the room must belong to its mapping. Standalone Booking CRS needs no connectionId.

## Retries and errors

Reuse an identical requestId/body after a lost client response. Changed input requires a new UUID. An uncertain upstream create is held for reconciliation; never delete its journal or switch IDs to force another booking.

| Status | Meaning / next action |
| --- | --- |
| 401 | Missing, expired or invalid credential. Authenticate again. |
| 403 | Wrong environment, nonowner or missing permission. Do not bypass by changing headers. |
| 404 | Room or recorded simulation is not in the selected property. Check exact IDs. |
| 409 | Setup disabled, real channel present, mismatched mapping, changed request under reused ID or uncertain operation. Inspect state before retrying. |
| 422 | Invalid dates/price/command or provider validation. Fix input; a zero-OTA guard failure is not permission to disconnect a live listing. |
| 503 | Integration configuration unavailable. Do not fill missing preview configuration from production. |

Errors are JSON. Providers may expose different classified messages; consumers should use status and available code rather than hardcoding an exact sentence.

## Room rules, cleanup and certification

`PATCH /api/rooms/{id}/pricing` accepts basePrice, weekendBasePrice and these nullable overrides:

- minimumStay: integer 1–365.
- maximumStay: integer 1–1125; cannot be below room minimum (default floor 1).
- advanceNoticeHours: integers 0–24, 48, 72 or 168.
- sameDayBookingCutoff: 24-hour HH:mm in property time; supported channel cutoff requires all mapped rooms to share a half-hour cutoff at/after 02:00.
- preparationDays: 0, 1 or 2 nights **before and after**.
- bookingWindowDays: 30-day steps through 330, or 365; applies to arrival.

Null clears a local override. Existing stricter channel baselines may remain. A successful room save is separate from verified channel enforcement; inspect Activity. Max guests remains a local setting; explicit supported pet-policy changes have their own synchronization path.

There is no bulk reset endpoint. Cancel recorded test bookings and retain receipts. Account/property deletion and channel removal have their own permissions, confirmations and consequences; never use them to reset the live property or to hide failed tests.

The API reference groups these routes under **Staging test data**, channel lifecycle commands under **Channel management**, releases under **Operator controls**, and scheduler ticks under **Internal jobs**. A staging workflow does not confer certification or production access; provider review, commercial terms and production cutover remain separate approvals.

## Inventory publication and saved changes

Use **Property Settings → Channels → Inventory synchronization** on the isolated property after preparing its normal room mapping. This uses the same saved prices, date ranges, minimum/maximum stay and occupancy as the rest of Wikiup:

1. POST channel management with `{action:"inventory_review"}`. Inspect the returned 500-day coverage, rooms, nightly price range and room minimum/maximum values. No provider writes occur.
2. Explicitly approve `{action:"inventory_publish",reviewId:<returned id>,reviewed:true}`. The proposal expires after 15 minutes and is invalidated by saved-state changes. Full publication requires preview, zero real local connections and an upstream zero-channel check. It sends one combined rate/restriction request and one availability request.
3. `{action:"inventory_verify"}` first ingests reservations, then verifies/reconciles authorized inventory. It can send pending definite-rejection retries or subsequent saved deltas; it is not a read-only audit command.
4. `{action:"inventory_evidence"}` reads sanitized step statuses, task IDs, UTC update time and retained receipt history. A lost receipt stays missing even when readback confirms application. Retain the provider request evidence rather than inventing a task ID.

Successful full readback enables isolated change-driven deltas. Subsequent ordinary price/rule/reservation saves use the durable publication path; idle recovery does not full-publish on a timer. Minimum and maximum stay are the generic rule subset; Airbnb's additional listing settings remain in their specialized paths. CTA/CTD date editors and pooled inventory remain unsupported product capabilities.

For an existing live Airbnb connection, automatic **price-only** publication is a separate owner opt-in: after the normal publication review has been published and verified, choose **Enable automatic price updates**, or send `{action:"enable_rate_sync",connectionId:<selected connection id>,reviewId:<verified review id>,reviewed:true}`. Current prices and mapping identity are rechecked. This never opts in an existing connection merely through deployment, never sends booking restrictions/stop-sell with a price edit, and never sends availability from the price worker. External price drift requires another review.

Unknown sends are read back before replay. If unsent inventory no longer matches current saved state, publication pauses for review. Provider readback confirms provider inventory, not downstream OTA delivery or certification approval. Production recovery code remains separately gated and dormant until explicitly released and configured.

Automatic price opt-in is now connection-scoped. Pass connectionId explicitly; only its mapped rooms publish. Use disable_rate_sync with connectionId to stop future sends. Shared room/source mappings are rejected until they have independent source rates, so an opted-out channel cannot be updated indirectly.

Per-room channel increases use the optional `priceAdjustment` field on `map`, or `price_adjustment` / `verify_price_adjustment` for an existing mapping. The [channel-management guide](/channel-management-api.md#roomchannel-price-adjustments) defines percentage/fixed values, null versus omitted behavior, verification, retry safety and the Onyx record location. This does not change room/direct pricing or authorize another channel.

## Automated API integration regression project

The monorepo's `wikiup-api-integration-test` project exercises disposable core PMS and isolated Booking CRS workflows through Wikiup APIs. It records ownership in private run journals, attempts reviewed teardown on pass/failure/interruption, and provides an explicit cleanup-resume command. It refuses production origins and existing-property targets. The runner can obtain and refresh a preview owner session through the normal Firebase email/password sign-in API. Reviewed deletion requires that owner session; an API key alone cannot complete teardown. See `wikiup-api-integration-test/README.md` for commands, coverage and blocked-cleanup behavior.

This is API regression evidence, not official UI-originated Channex certification evidence. Paid enablement requires an exact owner-approved terms version for that run, and cleanup never bypasses uncertain provider outcomes or locks.
