Partner integration
Your booking system sells the seat and calls us; we mint the wallet pass.
If you run a cinema, a theatre or a venue with its own booking engine, this is the whole of the API you need. Two calls.
The boundary
The merchant's booking system sells the seat and calls us; we mint the wallet pass, sync it, notify against it, and expire it. We hold no inventory, take no money, and know no seat map.
—
pass-service/docs/adr/0016-we-deliver-tickets-we-do-not-sell-them.md
You keep the booking engine you already have — showtimes, seat maps, holds, checkout, refunds. We never see any of it. What we take is the handful of facts that have to appear on a phone: which screening, which seat, which hall, and a barcode.
What that buys you is the one thing a printed ticket cannot do: tell its holder at 18:40 that the 19:30 moved to Танхим 5.
What you will do
Before the first call
Someone at the merchant has to do two things in the dashboard, once per film run:
- Create a
TICKETProgram and publish it. A Program is one film's run at one branch — "Dune 3 — Өргөө 7" — not one screening. The screening time lives on each individual pass, so a ten-screen multiplex creates one Program per film per branch, not one per showing. - Set its
externalRefto whatever your system already calls that film run.
That second field is what lets you address a Program with your own identifiers. If you run Vista,
the natural key is CinemaId + ScheduledFilmId:
0001-HO00001797 Avengers: Doomsday at Урөө 1,5 IMAX
0007-HO00001866 Dune: Part Three at Өргөө 7 ParkOdYou never store a UUID of ours. externalRef is unique per merchant and opaque to us — we match on
it and nothing else.
Publishing is a human act
The API issues against an already-published Program and will never create or publish one. A Program still in DRAFT
answers 409. This is deliberate: publishing mints a Google Wallet class, and a Google class is permanent and
undeletable — so a mistyped film id has to cost a person's attention rather than a permanent artifact.
What we cannot tell you
If you supply your own barcode, your door scanner reads your own payload and we never learn of the scan. There are no admission numbers, no no-show counts and no ledger on our side for those tickets. The wallet-side facts — issued, installed, synced, notified — are the only numbers we have.
Omit the barcode and the opposite holds: we mint the code, your staff scan it with our Scanner app, and we can answer "was this ticket used". See issuing.