Fejlesztőknek

Áttekintés

Az API a partner rendelőknek ingyenes. Minden kulcs egy rendelőhöz tartozik, és csak annak a rendelőnek az adatait látja.

• Alapcím: https://app.bundee.hu/api/v1
• Formátum: JSON (UTF-8). A kérés törzse JSON vagy hagyományos űrlap lehet.
• Időpontok: ISO 8601, magyar időzónával (pl. 2026-11-03T14:20:00+01:00). Bemenetként a 2026-11-03 14:20 forma is jó.
• Adatvédelem: a gazdi e-mail-címét és telefonszámát az API nem adja ki. A kedvencről név, faj, fajta, ivar és születési dátum jön, a gazdiról csak a megjelenített név.
• Ha a szervered nem támogatja a szép útvonalakat, a ?r= forma mindig működik: https://app.bundee.hu/api/v1/index.php?r=appointments

Hitelesítés

Kulcsot a rendelő vezetője készít a Rendelő kezelése → Integrációk oldalon. A teljes kulcsot csak egyszer mutatjuk meg, mi csak a lenyomatát tároljuk. Minden kérésben küldd el a fejlécben:

Authorization: Bearer fk_live_1a2b3c4d_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A kulcs bármikor visszavonható. Visszavonás után a kérések azonnal 401-es hibát kapnak.

Példák

A holnapi foglalások lekérése

curl "https://app.bundee.hu/api/v1/appointments?from=2026-11-15&to=2026-11-15" \
  -H "Authorization: Bearer $BUNDEE_API_KEY"

Válasz (rövidítve):

{
  "data": [
    {
      "id": 42,
      "clinic_id": 1,
      "starts_at": "2026-11-15T09:20:00+01:00",
      "ends_at": "2026-11-15T09:40:00+01:00",
      "status": "kert",
      "status_label": "Visszaigazolásra vár",
      "reason": "oltas",
      "reason_label": "Oltás",
      "note": "Kicsit izgulós az autóban.",
      "vet_note": null,
      "source": "web",
      "pet": { "id": 3, "name": "Léna", "species": "kutya", "breed": "Briard", "sex": "szuka", "birth_date": "2020-05-14" },
      "owner": { "display_name": "Kovács Anna" },
      "created_at": "…",
      "updated_at": "…"
    }
  ],
  "meta": { "from": "…", "to": "…", "count": 1 }
}

Visszaigazolás

curl -X POST "https://app.bundee.hu/api/v1/appointments/42/confirm" \
  -H "Authorization: Bearer $BUNDEE_API_KEY"

Vizit lezárása összefoglalóval

curl -X POST "https://app.bundee.hu/api/v1/appointments/42/complete" \
  -H "Authorization: Bearer $BUNDEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary":"Veszettség elleni oltás beadva, minden rendben.","next_due_date":"2027-11-14"}'

Foglalt sáv a saját naptáradból

curl -X POST "https://app.bundee.hu/api/v1/busy-blocks" \
  -H "Authorization: Bearer $BUNDEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"starts_at":"2026-11-16T10:00:00+01:00","ends_at":"2026-11-16T12:00:00+01:00","summary":"Műtét","external_id":"praxis-123"}'

Hibák és korlátok

Hiba esetén mindig ilyen formájú JSON jön, megfelelő HTTP-kóddal:

{ "error": { "code": "invalid_transition", "message": "Ez a lépés most nem lehetséges.", "status": "teljesult" } }

• 401 unauthorized / invalid_key: hiányzó, hibás vagy visszavont kulcs.
• 404 not_found: nincs ilyen végpont, vagy az azonosító nem a te rendelődé.
• 405 method_not_allowed: rossz metódus.
• 409 invalid_transition: az állapotváltás most nem lehetséges (pl. már elutasított foglalás visszaigazolása).
• 422 validation_failed / invalid_parameter: hibás bemenet.
• 429 rate_limited: kulcsonként percenként legfeljebb 120 kérés. A válaszban Retry-After fejléc jelzi, mennyit várj.

Webhookok

Webhookkal nem kell folyton lekérdezned az API-t: amikor valami történik egy foglalással, mi küldünk egy HTTPS POST kérést a megadott címre. Csak nyilvános https:// címre küldünk, átirányítást nem követünk.

A törzs mindig ugyanilyen boríték, a data.appointment pontosan olyan, mint az API válaszában:

{
  "id": "dlv_128",
  "event": "appointment.created",
  "api": "v1",
  "created_at": "2026-10-24T18:05:11+02:00",
  "clinic_id": 1,
  "data": { "appointment": { "id": 42, "status": "kert", "...": "..." } }
}

Fejlécek: X-Bundee-Event, X-Bundee-Delivery (ugyanaz, mint az id, ezzel kiszűrheted az ismétlést), X-Bundee-Timestamp (Unix-idő) és X-Bundee-Signature.

Újrapróbálás: akkor tekintjük sikeresnek, ha 10 másodpercen belül 2xx választ adsz. Ha nem, 1 perc, 5 perc, 30 perc, 2 óra és 12 óra múlva újra küldjük, utána feladjuk. A kézbesítési naplót az Integrációk oldalon látod. Válaszolj gyorsan, és a feldolgozást végezd utána.

Aláírás ellenőrzése

Az aláírás: sha256= + HMAC-SHA256 hexában, kulcsa a webhook titka (whsec_…), az aláírt szöveg pedig időbélyeg + "." + nyers törzs. Mindig a nyers törzzsel számolj, és utasítsd el az 5 percnél régebbi időbélyeget.

PHP

<?php
$secret = getenv('BUNDEE_WEBHOOK_SECRET');           // whsec_...
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_BUNDEE_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_BUNDEE_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $sig) || abs(time() - (int)$ts) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);
// ... mentsd el $event['id']-t, hogy egy eseményt csak egyszer dolgozz fel
http_response_code(200);

Node.js (Express)

const crypto = require("crypto");
const express = require("express");
const app = express();

app.post("/bundee-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("X-Bundee-Timestamp") || "";
  const sig = req.get("X-Bundee-Signature") || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.BUNDEE_WEBHOOK_SECRET)
    .update(ts + "." + req.body)
    .digest("hex");
  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // ... feldolgozás
  res.sendStatus(200);
});

Verziók

Az útvonalban lévő v1 a verzió. Ezen belül csak visszafelé kompatibilis bővítés jöhet (új mezők, új végpontok, új események), ezért a programod hagyja figyelmen kívül az ismeretlen mezőket. Ha valamit el kell törnünk, az v2 lesz, és a régit legalább 6 hónapig párhuzamosan futtatjuk. Minden válaszban benne van az X-Bundee-Api-Version fejléc.

Rendelőszoftverek

Itthon a rendelők többsége régóta használt praxisszoftverrel dolgozik, és egyre több a felhőalapú rendszer is, amely a PetVetData-hoz is kapcsolódik. Külföldön ismert rendszerek például az ezyVet, a VetMaster vagy a DaySmart Vet. A Bundee egyikkel sem áll partnerségben.

Ha a rendelőszoftvered gyártója bekötné a Bundee-t, ez az oldal és egy teszt API-kulcs elég hozzá. Ha a szoftvered nem tud API-t hívni, a foglalások e-mailben és naptár-szinkronnal (iCal) is elérhetők az Integrációk oldalon.