Plan a door-access integration

A door integration combines evidence from campai, your organization's access rule, and the lock provider's credential API. campai booking or member data does not itself unlock a door. This guide defines the boundary so an integration can be implemented and tested without assuming a particular lock vendor is supported.

Use an external service when the lock provider needs a continuously available backend, its own credentials, or durable synchronization. A developer app can run supported app actions, but it does not replace that service's access ledger or the lock vendor's delivery guarantees.

Decide whether access follows a specific booking, a current membership, an active subscription, or an explicit combination. Read the smallest relevant dataset:

Evidence	API operation	What still needs a rule
Contact and membership dates	Get contact	Which membership dates and contact types permit access
Booking details	Get booking	Booking status, cancellation, payment requirements, and allowed time window
Subscription records	List subscriptions	Which product and effective state qualify
Event timing	List events	Which occurrence and venue correspond to the door

Follow Synchronize bookings for the verified booking read and Keep member data in sync for contact reads. Keep booking status, payment status, and cancellation records separate. Do not reduce all three to “the booking exists.”

For each grant, store the environment, organization, contact or booking ID, lock-provider subject ID, door ID, validity interval, and the evidence timestamp. Keep the mapping private. A campai contact ID should not become a publicly reusable door credential.

Document the interval boundaries. For example, your organization may choose entry from 15 minutes before an event until its end. That is your policy, not an API default. Convert timestamps using the event's time zone and test daylight-saving changes. A date-only membership field requires an explicit local-day interpretation before it becomes an instant.

Define whether payment is required, how cancellations revoke access, and whether a changed event moves an existing grant. For overlapping bookings, combine grants deliberately; revoking one booking should not remove access still justified by another.

Use a worksheet like this with your venue operator. The interval here is a policy example to approve, not a campai default:

Input	Proposed decision	Evidence to retain
Eligible booking, 10 minutes before its start	Grant entry if the approved window starts 15 minutes early	Booking ID, door, start/end instants, decision time
Same booking after cancellation	Revoke its grant	Cancellation evidence and provider confirmation
Two overlapping eligible bookings, one canceled	Retain only the access justified by the remaining booking	Both source IDs and the resulting interval
Latest successful scan exceeds your allowed age	Apply the operator’s agreed outage policy	Last successful scan and the reason for the fallback
Provider times out while creating a grant	Mark the outcome uncertain	Provider operation reference for reconciliation

Finish this worksheet before connecting a real lock. Your implementation is ready for a designated test lock only when each row has a concrete provider operation, a way to read back the result, and an expiry or revocation check.

Compute a desired set of grants from current evidence. Compare it with your persisted ledger and the lock provider's reported state. Create, update, or revoke only the differences, and record each provider operation and result.

Keep uncertain results distinct from failures. If the provider times out after creating a credential, look up that operation before creating another. If campai is unavailable, do not interpret an empty fallback value as a successful reconciliation. Define a short cache lifetime and an outage policy with the operator.

Never include a real unlock or credential-creation action in a connectivity check. First verify reads and calculate proposed grants against synthetic bookings. Then use a vendor test environment or a designated test lock for the physical behavior.

The reviewed webhook types cover contacts, debtors, creditors, and postings. They do not include booking or event changes. Do not register an invented bookings.updated event or assume a contact update announces a booking cancellation.

Poll bookings and events at an interval chosen for the required revocation delay, with bounded concurrency. Contact webhooks can speed up membership refreshes, but missed-delivery reconciliation remains necessary. Record the last successful scan and alert when your decision data is too old.

Cover a valid booking, a canceled booking, an unpaid booking when payment is required, a rescheduled occurrence, overlapping grants, membership expiry, a lost provider response, and each service being unavailable. Check the provider's actual credential state after each test.

Verify revocation on the designated test lock, including any offline behavior and local caching. An API response from either service is not proof that a disconnected physical device has applied the change. Keep emergency access and operational recovery under the venue's existing procedures.

Continue with Turn event bookings into reviewed door-access grants for complete Node.js/PHP readers, a local review interface, expiring grants, and a provider-mapping contract.