Integrate ArchWalk 360 into your product

29. Partner plugin integration

Recommended path: Partner API for provisioning/sync + ArchWalk Embedded Creator for authoring + ArchWalk Viewer for guests.

ArchWalk does not persist resorts, physical rooms, or room types. Those remain partner-owned. ArchWalk stays generic: Integration → Experience → Panoramas → navigation / optional Floor Plan → publication → Viewer.

Architecture

Partner data/import
        ↓
Partner backend
        ↓
ArchWalk Partner API — provisioning
        ↓
Experience mapping

Partner user
        ↓
Partner UI
        ↓
Embedded Creator

Guest
        ↓
Partner room/listing
        ↓
ArchWalk Viewer

200 rooms is not 200 Experiences

Example: Blue Lagoon Resort imports 200 physical rooms. Those collapse into 8 visually distinct room types. The partner create-or-resolves 8 ArchWalk Experiences — not 200.

Create another Experience when the representation is materially different (layout, accessible configuration, renovation, attached spaces, or another difference that would make reuse misleading).

Identity

Example mapping for Deluxe King at Blue Lagoon:

{
  "name": "Deluxe King",
  "external_customer_id": "blue_lagoon",
  "external_resource_id": "room_type_deluxe_king"
}

external_customer_id is optional. Use it when you already namespace resources by customer or resort. If external_resource_id is globally stable inside the Integration, omit external_customer_id.

Store returned experience_id, public_id, and publication_status in your own system if useful. The external identity remains sufficient to re-resolve safely.

Provisioning (create-or-resolve)

Call POST /api/v1/360/experiences once per distinct visual variant, not once per physical room.

const variants = groupImportedRoomsByVisualVariant(rooms);

for (const variant of variants) {
  const experience = await archwalk.createOrResolveExperience({
    name: variant.name,
    external_customer_id: resort.id,
    external_resource_id: variant.stableId,
  });
  saveMapping(variant.id, {
    experienceId: experience.experience_id,
    publicId: experience.public_id,
    publicationStatus: experience.publication_status,
    draftRevision: experience.draft_revision,
  });
}

Idempotency: the same Integration + exact identity returns 200 and the same experience_id / public_id. Name is not overwritten on resolve. Safe to retry. Concurrent creates collapse to one row.

A sync should not be all-or-nothing. If one variant fails (validation, 409 deletion-reserved, 429, 5xx), continue the others. Successful variants remain usable. Retry later; already-synced identities resolve instead of duplicating. Honor 429 Retry-After / retry_after_seconds. There is no bulk “create 200 Experiences” Partner route — existing create-or-resolve is the contract.

360 status in the partner UI

publication_status on the Experience is only unpublished or published. Partner UI labels are derived, not extra ArchWalk fields:

Edit 360

1. Partner UI Edit 360 for that variant.
2. Partner backend mints POST /api/v1/360/creator-sessions bound to that Experience. The API key stays on the server.
3. Embed /aw360/c/{api_id} (api_id from the mint response; the path parameter is the session id).
4. Exact-origin handshake: creator:ready-for-init then creator:init with { token } in memory only.

Never put the Partner API key in HTML, browser JS, URL, localStorage, sessionStorage, logs, or postMessage. Never put the Creator token in the iframe URL. Switching variants must drop the previous token.

Existing Embedded Creator already handles Panorama upload, external media where permitted, labels, order, starting view, room-to-room navigation, Floor Plan, and publish/unpublish. Do not rebuild those controls in the partner shell.

Creator events

Use the public Creator contract: creator:ready-for-init, creator:ready, creator:dirty, creator:saved, creator:published, creator:unpublished, creator:error, creator:reauth-required.

On creator:published, update the selected variant to Published and offer View 360 / Preview using /aw360/v/{public_id} (publicId on the event, or re-GET the Experience). On creator:unpublished, return the variant to Draft. A full page reload is not required for these known events.

Viewer reuse

Physical rooms 101, 102, and 103 that share Deluxe King all embed the same published public_id. Two rooms of the same visual variant must resolve to the same Viewer URL.

Security (unchanged platform rules)

1. API key — server-to-server only.
2. Creator session — short-lived browser credential.
3. Allowed origins — framing / Creator origin trust. Not API-key authorization, not IP allowlisting, not global API CORS.
4. API CORS — separate (frontend_origin for the ArchWalk app).
5. Tenant — Organization + Integration come from the Partner credential. Browser-supplied tenant ids must not choose tenancy.
6. draft_revision — optimistic concurrency. Pure API editors must re-read and retry on 409 archwalk_360_draft_revision_conflict. Hybrid users let Embedded Creator own that behavior.

See the AcmeStay reference /seller/plugin and /listing/plugin?room=101 for an executable version of this flow.