Device makers

If you make door locks, key systems, entry barriers or EV chargers, your product does something on the campground itself, and the public Grondia API cannot drive it: booking events carry no guest data, there is no endpoint to hand a door code back, and a check-in cannot be triggered through the API (why). Instead, Grondia can write an adapter: code on the Grondia side that calls your API at the right moments of a stay. This page lists what the adapter needs from your API.

Adapters Grondia has built

Grondia has built adapters for these systems:

• Salto KS, door locks
• Nuki, smart locks
• resivo, access control
• Came and FAAC, entry barriers
• AMPECO, EV charging

Every adapter follows the same pattern, so what follows is what the adapters needed.

How an adapter works

Each campground that uses your product gives Grondia its own credentials for your system. Grondia stores them encrypted, one set per campground, and keeps a test or production setting next to them. From then on the adapter reacts to the life of a booking.

• Grondia adapter
• Your API

1. A booking is confirmed

2. Grondia adapter to Your API: Create access, valid from check-in to check-out

3. Your API to Grondia adapter: Access id, and the code if you create it

4. The guest arrives and uses the code

5. Your API to Grondia adapter: Event: access used (optional, signed)

6. Grondia adapter to Your API: List events since the last poll (backstop)

7. The booking is completed, cancelled or a no-show

8. Grondia adapter to Your API: Revoke the access id

9. Your API to Grondia adapter: 200, or 404 if it is already gone

Some adapters create the access a few days before arrival instead of at confirmation. Chargers work the other way round: Grondia gets finished charging sessions from your system and puts them on the guest’s invoice.

What we need from your API

Login without a person. An API token, or client credentials that give a token. Say how long a token lives and how to renew it. If your API only offers a user login, say which user and which role it needs.

What a campground has to type in. Usually an API token and the id of the lock, gate or charge point. Tell us where in your product a campground finds them.

A test environment. A second environment next to production, with its own credentials.

A cheap read call. A read-only call that proves the credentials work, for example a list of the devices. Every adapter has a “test connection” action that makes it.

Create access for a stay. One call, or a short fixed sequence, that creates a credential valid from check-in to check-out: a PIN, a card, a licence plate, an RFID token. Grondia works out the start and end from the campground’s local check-in and check-out times. Say which time format your API takes and whether it expects a time zone. The call must return an id we can store. Say who creates the code, your API or us, and how a campground chooses which doors, zones, gates or charge points the access opens (a call that lists them is best).

Change a stay. Dates change. A way to update the same access in place is best. If a change means deleting and creating again, say whether the guest’s code changes with it.

Revoke. A call that ends an access by its id, at once, and that is safe to repeat. We revoke when a booking is completed, cancelled or marked as a no-show, and we treat a 404 for an access that is already gone as done. If you can, keep a record of a revoked access rather than deleting it: when someone asks later which door opened for whom, the record is the answer.

Events and usage. Optional, and welcome. For locks and barriers, an event each time an access is used or refused. For chargers, every finished session with its energy in kWh, its cost and currency, the card or token used and the charge point. Offer both ways to get them:

• a signed webhook (an HMAC of the body with a shared secret, or a secret in a custom header);
• a list call, “events since this time”, with a stable id on every event. Today the barrier and charger adapters poll such a list about every 15 minutes as a backstop and use the id to ignore duplicates.

Limits. The rate limit, whether it counts per campground account or for the whole integration, and what your API answers when it is exceeded. A stay takes a few calls to create and one to revoke, plus periodic reads: a nightly reconcile for locks, a poll about every 15 minutes for barriers and chargers.

A way to test. A sandbox account that behaves like production and, for physical devices, one real unit or a simulator that really opens or refuses. Without it we build from your documentation alone, and the first real test happens at a campground.

Versions and changes. A versioned API, and notice before a call we use is changed or removed.

A support contact. A named technical contact and a support address, for the day a guest stands at a door that does not open.

What to do next

Write to Felix, felix@grondia.com, or to Siro, siro@grondia.com, with your API documentation and a way to test it: a sandbox account, test hardware or a simulator. Grondia decides whether and when to build an adapter for your system; Felix or Siro tell you what happens next. A message to us is the start of a conversation, not a commitment to build.

If Grondia builds an adapter, the later steps (a pilot with one campground, the App Store listing, support) work as in the Partner program, including what to send for the listing.