Arendajatele

Nola avalik API ja veebihaagid

REST API ja väljuvad veebihaagid, mis on piiratud ühe teenusepakkuja kontoga. Sellest piisab, et ühendada n8n, Home Assistant või oma taustsüsteem, ilma et kellegi teise andmed nähtavale tuleksid. Võtmeid ja lõpp-punkte haldad lehel Seaded → Integratsioonid.

Loo API-võti OpenAPI spetsifikatsioon (JSON)

Autentimine

API-võtmed (Bearer)

Iga päring autenditakse API-võtmega, mille lood lehel API ja veebihaagid. Võtit näidatakse lihttekstina ainult korra, loomise hetkel. Hoia seda nagu iga teist saladust. Igal võtmel on üks või mitu õigust. Kui võtmel puudub õigus, mida lõpp-punkt nõuab, lõpeb päring veaga 403 forbidden.

Päis Authorization

Authorization: Bearer nola_live_XXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Õigused: bookings:read, bookings:write, availability:read, availability:write, resources:read, resources:write, services:write, pricing:write, clients:read, clients:write, wallet:read. Päringupiirang: 600 päringut minutis võtme kohta (üle selle vastab 429 rate_limited).

Teatmik

Lõpp-punktid

Meetod	Tee	Õigus
GET	/api/v1/bookings	bookings:read
POST	/api/v1/bookings	bookings:write
DELETE	/api/v1/bookings/{id}	bookings:write
GET	/api/v1/availability?date=YYYY-MM-DD	availability:read
GET	/api/v1/resources	resources:read
PATCH	/api/v1/resources	resources:write
PATCH	/api/v1/services	services:write
PUT	/api/v1/weekly-hours	availability:write
GET	/api/v1/pricing-rules	pricing:write
POST	/api/v1/pricing-rules	pricing:write
PATCH	/api/v1/pricing-rules	pricing:write
GET	/api/v1/clients	clients:read
POST	/api/v1/clients	clients:write
GET	/api/v1/wallet/transactions	wallet:read

Päringute ja vastuste täielikud skeemid on OpenAPI 3.1 spetsifikatsioonis. Loendi lõpp-punktid tagastavad { items, nextCursor }. Järgmise lehe saamiseks saada nextCursor tagasi parameetrina cursor.

Näited

curl

Tulevaste broneeringute loend

curl "https://api.getnola.co/api/v1/bookings?from=1735689600000" \
  -H "Authorization: Bearer nola_live_XXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Broneeringu loomine

curl -X POST "https://api.getnola.co/api/v1/bookings" \
  -H "Authorization: Bearer nola_live_XXXX_..." \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_...",
    "startMs": 1735732800000,
    "client": { "name": "Jane Doe", "email": "jane@example.com" }
  }'

Veebihaagid

Allkirjade kontroll (Node.js)

Iga saadetis on POST-päring, mille sisu on JSON { event, createdAt, data } ja millel on päis X-Nola-Signature: t=<unix ts>,v1=<hmac hex>: väärtuse `${t}.${rawBody}` HMAC-SHA256 lõpp-punkti saladusega (näidatakse korra, lõpp-punkti loomisel). Ebaõnnestunud saatmist proovitakse kasvava vahega uuesti kuni 8 korda ja pärast 20 järjestikust ebaõnnestumist lülitatakse lõpp-punkt automaatselt välja.

Kontroll ja Expressi töötleja

import { createHmac, timingSafeEqual } from "node:crypto";

// req.body must be the RAW request body string (not parsed JSON).
// Verify it before you JSON.parse it.
function verifyNolaWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")),
  );
  const timestamp = parts.t;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const sigBuf = Buffer.from(parts.v1, "hex");
  const expBuf = Buffer.from(expected, "hex");
  if (sigBuf.length !== expBuf.length) return false;
  if (!timingSafeEqual(sigBuf, expBuf)) return false;

  // Reject events older than 5 minutes to prevent replay.
  const ageMs = Date.now() - Number(timestamp) * 1000;
  return ageMs < 5 * 60 * 1000;
}

// Express example:
app.post("/webhooks/nola", express.text({ type: "*/*" }), (req, res) => {
  const ok = verifyNolaWebhook(
    req.body,
    req.header("X-Nola-Signature"),
    process.env.NOLA_WEBHOOK_SECRET,
  );
  if (!ok) return res.status(401).send("bad signature");

  const event = JSON.parse(req.body);
  console.log(event.event, event.data);
  res.sendStatus(200);
});

n8n

n8n-i töövoo ühendamine

Lisa käivitajaks sõlm „Webhook“ (Method: POST, Path: näiteks /nola).
Lisa Nolas lehel API ja veebihaagid lõpp-punkt selle sõlme Production URL-iga ja vali sündmused, mida soovid (näiteks booking.created).
Lisa n8n-is kohe käivitaja järele sõlm „Code“, mis kontrollib päist X-Nola-Signature selle lehe Node.js-i näite abil. Lõpp-punkti saladus pane n8n-i mandaati (credential), mitte töövoo JSON-i.
Hargne väärtuse {{$json.body.event}} järgi (näiteks booking.created, booking.cancelled) sõlmega „If“ või „Switch“.
Loe sõlmedega „HTTP Request“ ja päisega Authorization: Bearer <api key> broneeringu ja kliendi täisandmed, kasutades õigusi bookings:read / clients:read, ning jätka töövoogu (näiteks saada Slacki sõnum, uuenda tabelit või sünkrooni kalender).

Home Assistant

Vabade aegade pärimine ja broneerimine Home Assistantist

Kui vajad kindla ressursi reaalajas hõivatust ja nutiluku koode, kasuta pigem eraldi lõpp-punkte /access/occupancy ja /access/codes/current (vaata Seaded → Uksed ja seadmed). Need kasutavad kergemat, ühe ressursiga piiratud võtit, mis on mõeldud korduvaks pärimiseks. Allolev avalik API on laiemateks liidestusteks (broneeringute loomine, klientide lugemine jne).

configuration.yaml

# configuration.yaml: poll today's availability for a resource
rest:
  - resource: "https://api.getnola.co/api/v1/availability?date={{ now().strftime('%Y-%m-%d') }}&resourceId=<resourceId>"
    method: GET
    headers:
      Authorization: !secret nola_api_key
    scan_interval: 300
    sensor:
      - name: "Court 1 availability"
        value_template: >
          {{ value_json.slots | selectattr('available') | list | length }}

# Automations can POST a booking from Home Assistant, e.g. a physical
# button that books the next open slot. Call the /api/v1/bookings
# endpoint from a "rest_command" with method: POST and your JSON body.