Machine address review and installation confirmation
Use the same address workflow for ZHZN, Reyeah and VC EL. The address belongs to the fleet record; it does not depend on the vending controller, cabinet APK, payment terminal or manufacturer SDK. Completing this workflow does not qualify a controller adapter or repair a cabinet.
The address-review API and browser workflow were deployed on September 7, 2026. Open Operator in your browser and select Address and installation; the Operator platform guide records verified phone release availability. A published API or client does not establish the cabinet's physical location. Installation remains unconfirmed until an operator records actual onsite observation.
What the two confirmations mean
| Displayed status | What was established |
|---|---|
| Address not confirmed | There is no current reviewed address match. A legacy address label, GPS pin or successful geocode alone does not qualify. |
| Address match confirmed | An authorized operator reviewed a selectable map candidate against the entered structured address and explicitly saved it. |
| Physical installation not confirmed | No current operator attestation links this cabinet number to a described position at the saved address. |
| Installation confirmed by operator | An operator typed the cabinet's exact machine number and recorded where they observed it installed. This is an operator statement, not independent sensor verification. |
| Postal deliverability: not checked | No postal delivery database, unit validation or mail-delivery test was used. This remains true after either confirmation. |
Photon searches OpenStreetMap features. Its documented address fields, country restriction and house/street/city layers support comparing map candidates; they do not constitute a postal-deliverability service. Location bias changes ranking, while country and bounding-box filters restrict results. Reverse lookup finds a nearby mapped feature. A returned point alone therefore cannot establish the exact cabinet position. This last conclusion is our interpretation of the documented behavior. Official Photon 1.3 API
Photon can return a centroid and bounding box unless full geometries were imported. Data may also be restricted to selected countries during import. Confirm the deployed index's coverage and data date when a valid address is absent; absence from map data does not prove an address is invalid. Official Photon import and geometry documentation
The platform uses its configured Photon service. It does not silently fall back to the public demo. The public demo has usage limits and no availability guarantee. Photon hosting policy
Review an address
- Sign in with an account allowed to update this machine. All three review endpoints require
machines:write; a read-only account can inspect saved status. - Open the machine's Address and installation panel, or Field setup → Locate. Check the machine number before proceeding. A missing backend review fingerprint means this backend cannot provide the new workflow; refresh or contact support.
- Enter building/house number, street, city/locality and the assigned two-letter country code. State/region is required for US, CA, AU and IN. Postal code is required for US, CA, AU, GB, IN, NZ, DE and FR. Provide locally required details elsewhere. Unit/floor is recorded as entered and is not independently validated; persistent saved issues explain this limitation after confirmation too. This workflow checks a numbered street address against geocoder data; it is not a universal validator for every country's address forms.
- Choose Check address. This creates a temporary review record without moving the machine or changing its saved address.
- Compare Entered and Returned address components. Read all issues, inspect latitude/longitude, and open the candidate pin on OpenStreetMap if needed. A nonselectable candidate cannot be confirmed. If no complete matching numbered address is available, preserve the entry and resolve the missing map or local evidence; do not choose a city/street result merely to pass setup.
- Explicitly select an eligible candidate and choose Confirm selected address match. Only the machine returned by the successful server response establishes confirmation. The UI does not infer success from an HTTP response without the required metadata.
Editing any address field invalidates the review, including a lookup still in flight. Reviews expire and cannot be reused after a placement change. An HTTP 409 requires Refresh saved location, then a new check. A timeout may leave the outcome uncertain: refresh before retrying. Entered fields survive lookup failures and refreshes; leaving the page discards unsaved form changes.
Confirm installation only after observing it
After the address match is confirmed, inspect the actual cabinet at that address. Type the exact displayed machine number, record an entrance/floor/position in the placement note, and explicitly attest that you observed it there. Then choose Confirm installation as operator.
| Cabinet family | Identity and observation needed |
|---|---|
| ZHZN | Match the fleet machine number to the cabinet's assigned identity/build record. Record the physical position; an online agent or a screenshot does not prove the venue. |
| Reyeah | Match the cabinet's configured equipment number to the fleet record. Neither an installed APK nor a remote companion establishes location. |
| VC EL | Match the visible cabinet/asset label to the intended fleet record. For the photographed cabinet, XT-202303207146 is the supplied cabinet reference; do not substitute a guessed controller identity. VC EL branding and the TCN manual leads do not establish Silkron or adapter compatibility. |
Without access to the cabinet or reliable on-site observation, leave installation unconfirmed. Never prefill or invent the attestation. New field setup requires an address match to advance past Locate, and both confirmations plus normal lifecycle readiness before Go live. Existing live cabinets retain their normal operation while missing address or installation evidence is displayed.
API contract for integrators
Read the current geo.addressValidation.fingerprint from the machine. It describes the saved placement revision and must accompany every request below. Never derive a fingerprint from local coordinates or invent one for an older backend.
Endpoint suffix under /api/v1/machines/{machineNo} |
Body | Result |
|---|---|---|
POST /address/check |
address: {houseNumber, street, unit?, locality, region?, postalCode?, country}, expectedFingerprint |
Review ID, status, issues, entered address, candidates, expiry and fingerprint. |
POST /address/confirm |
checkId, candidateId, expectedFingerprint, confirmed: true |
Updated machine with the authoritative address confirmation. |
POST /address/installation |
expectedFingerprint, confirmed: true, machineReference, placementNote |
Updated machine with a separate operator installation attestation. |
Check statuses are incomplete, not_found, ambiguous, mismatch, provider_error, unavailable and review_required. A check status is not a saved machine status. Only candidates marked selectable: true are eligible, and eligibility is rechecked by the backend on confirmation. Clients send review IDs rather than editable coordinates at confirmation.
Legacy coordinate and label writes remain unverified. Do not send an address and explicit GPS coordinates in the same legacy request. Address or placement changes invalidate earlier confirmation; clients must render the latest returned machine instead of retaining a previous green badge.
The signed-in operator's authorization, server review expiry and placement fingerprint are enforced by the backend. A user interface check alone is insufficient when another operator, device heartbeat or replica changes the machine concurrently.
Storage and rollout
Address checks expire after 15 minutes and are stored server-side, bound to the machine, current owner and placement fingerprint. Only one active review is stored per cabinet; starting another check supersedes the previous review. Confirmation accepts a stored candidate identifier; the client cannot provide replacement coordinates or a verification verdict. A confirmed address increments the placement revision. Changing address, GPS, ownership or placement invalidates the prior evidence, and a move requires new installation confirmation.
SQLite and PostgreSQL commit placement fields together, with an authoritative owner/fingerprint comparison inside a database transaction. Ordinary fleet mirrors preserve the current revision's placement fields so a stale heartbeat cannot restore an older address. Configured storage failures return an error before the in-memory placement is updated. With no fleet persistence in a local development environment, checks are process-local and disappear on restart.
Roll out the API to every replica before publishing the new web/mobile clients or accepting address confirmations. Older API replicas do not implement the placement-preserving mirror and must not remain in service during confirmation. No database rewrite marks existing addresses confirmed; each machine requires review. Rollback to an older API requires suspending address confirmations first. Keep the signed app release and API deployment identities in the release record.
New setup requires both address review and installation confirmation even when a hardware check is explicitly overridden. Existing live cabinet payments and hardware sellability are not disabled by absent address evidence. A lifecycle label alone is never address evidence.
Acceptance still needed
Exercise the workflow on the deployed web and phone clients using a permitted test fleet record: complete address, ambiguous result, incomplete/country mismatch, missing map data, lookup outage, expired review, concurrent placement change, unauthorized account and interrupted confirmation. Confirm each client keeps the two status labels separate. For each physical cabinet, separately record identity, location, controller compatibility, display stability and the existing vend/payment acceptance checks. No physical acceptance is implied by automated address-flow tests.
Continue with the machine operation manuals, remote access procedure and VC EL identification and flicker guide.