Skip to main content

Quickstart

This page gets you from zero to your first operational calls in a few minutes, then walks the workflow the API was designed around: paste a set of meter readings, generate the invoices.

1. Get an API key​

API keys are issued in the BookingFlow dashboard (Settings → API keys):

  • bf_live_... — operations on real data
  • bf_test_... — test-mode key against the test project

The key is shown exactly once and scoped to one park (site). Treat it like a password: Authorization: Bearer bf_live_... on every request.

2. Make your first call​

API=https://europe-west1-bookingflow-6fd8c.cloudfunctions.net/api
KEY=bf_live_...

# What site am I operating?
curl -s $API/v1 -H "Authorization: Bearer $KEY"

# List today's bookings
curl -s "$API/v1/bookings?limit=25" -H "Authorization: Bearer $KEY"

Every response carries an X-Request-Id header — quote it in any support conversation.

3. Quote and create a booking​

# Is a 2-night stay available for 2 adults + 1 child + 1 dog?
curl -s "$API/v1/availability?from=2026-12-01&to=2026-12-03&adults=2&children=1&pets=1" \
  -H "Authorization: Bearer $KEY"

# Book it. The server prices the stay; you cannot set the price.
curl -s $API/v1/bookings -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "accommodation": "0F7p9sGHx",
        "arrive": 1793107200,
        "depart": 1793280000,
        "adults": 2,
        "children": 1,
        "pets": 1,
        "status": "confirmed",
        "first_name": "Alex",
        "last_name": "Rider",
        "email": "alex@example.com",
        "phone": "+441234567890"
      }'

Always send an Idempotency-Key on writes. If the network drops mid-request and your agent retries, the same key returns the same booking — never a double booking.

4. The meter round workflow (agents)​

This is the flow the API exists for: an operator pastes a clipboard of electricity meter readings into their agent, and the agent turns it into Xero invoices.

Step 1 — ingest the round in one request. Rows may reference pitches by number or id. date may be omitted (defaults to now):

curl -s $API/v1/meter_readings/bulk -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: meter-round-2026-11-30" \
  -H "Content-Type: application/json" \
  -d '{
        "readings": [
          {"pitch_number": "101", "reading": 15420.5, "date": "2026-11-30"},
          {"pitch_number": "102", "reading": 10230.0, "date": "2026-11-30"},
          {"pitch": "pitch-103",  "reading": 9033.25, "date": "2026-11-30", "notes": "new meter"}
        ]
      }'

The response reports per-row outcomes. Unknown pitch numbers land in errors with their index — fix them and re-send only those rows with a fresh idempotency key.

Step 2 — generate every invoice in one call:

curl -s $API/v1/invoices/generate_all -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: invoices-2026-11-30" \
  -H "Content-Type: application/json" \
  -d '{"since": "2026-11-30"}'

Each pitch with two or more readings and an un-invoiced latest reading gets a DRAFT Xero invoice (usage × the site's price per kWh). Pitches are skipped with a reason; a single failing pitch never aborts the round. Running the call twice — or after every round — creates no duplicates: an invoice is never generated twice for the same closing reading.

Step 3 — inspect and confirm:

# The invoices created this round
curl -s "$API/v1/invoices?limit=50" -H "Authorization: Bearer $KEY"

# One pitch's full reading history
curl -s "$API/v1/meter_readings?pitch=pitch-101" -H "Authorization: Bearer $KEY"

The invoices are DRAFT in Xero; an operator reviews and approves them in Xero as usual.

5. Find anything else​

  • Unknown URL? GET /v1 lists nothing else on purpose — the resource reference (sidebar) is the map, and functions/openapi.yaml is the machine-readable contract.
  • Something failed? The error envelope's code and param tell you what to fix; doc_url links the relevant reference page.
  • Building automation? See Webhook endpoints — every mutation is also delivered as a signed event.