Partneri API

A partneri integráció a műhely által előre kiosztott kapacitáson belül tud foglalni. Hitelesítés: Authorization: Bearer <api-kulcs>. Minden időpont ISO 8601 formátumban, explicit időzóna-eltolással érkezik és megy; a műhely naptára Europe/Budapest szerint működik, a foglalások mindig 30 perces határon indulnak.

English: authenticate with a Bearer API key. Timestamps are ISO 8601 with offset; bookings always start on a 30-minute boundary. Availability is computed server-side — never assume a slot is free without asking.

Alap URL / base URL: https://proautobooking.com

GET/api/v1/services

Az Ön hozzáférésére engedélyezett szolgáltatások. — Services enabled for your account.

Válasz / response

{
  "data": [
    { "id": "6f0…", "name": "Gumicsere 17\"", "duration_min": 45,
      "price_huf": 12000, "bay_name": "Gumiszerelés" }
  ]
}

GET/api/v1/availability?service_id=…&from=2026-08-20&to=2026-08-27

Szabad indulási időpontok. A szervert kérdezze meg minden foglalás előtt. — Free start times; always the server decides.

Válasz / response

{
  "data": [ { "starts_at": "2026-08-20T11:00:00+02:00" } ],
  "meta": { "remaining_today": 2, "horizon_end": "2026-08-27" }
}

POST/api/v1/bookings

Foglalás létrehozása. Az Idempotency-Key fejléc kötelező. — Create a booking; Idempotency-Key header required.

Kérés / request

{
  "service_id": "6f0…",
  "starts_at": "2026-08-20T11:00:00+02:00",
  "customer": { "name": "Kovács Anna", "phone": "+36301234567",
                "email": "anna@pelda.hu" },
  "vehicle":  { "plate": "AA-BB-123", "make_model": "Skoda Octavia" },
  "external_ref": "PARTNER-2026-0912",
  "note": "Nyári gumira váltás"
}

Válasz / response

201 Created
{
  "data": { "id": "9c1…", "starts_at": "2026-08-20T11:00:00+02:00",
            "ends_at": "2026-08-20T11:45:00+02:00", "status": "confirmed",
            "manage_url": "https://proautobooking.com/f/…" }
}

GET/api/v1/bookings?external_ref=PARTNER-2026-0912

Foglalás keresése a saját hivatkozási azonosítója alapján. Hasznos, ha elveszett a válasz. — Look up your own booking by external_ref; useful when a response was lost.

Válasz / response

{
  "data": { "id": "9c1…", "status": "confirmed",
            "starts_at": "2026-08-20T11:00:00+02:00",
            "ends_at": "2026-08-20T11:50:00+02:00",
            "service_name": "Gumicsere 17\"",
            "external_ref": "PARTNER-2026-0912",
            "manage_url": "https://proautobooking.com/f/…" }
}

GET/api/v1/bookings/{id}

Saját foglalás állapota. Más partner foglalására 404. — Your own booking only; anything else returns 404.

Válasz / response

{
  "data": { "id": "9c1…", "status": "confirmed",
            "starts_at": "2026-08-20T11:00:00+02:00",
            "ends_at": "2026-08-20T11:50:00+02:00",
            "service_name": "Gumicsere 17\"",
            "external_ref": "PARTNER-2026-0912" }
}

PATCH/api/v1/bookings/{id}

Áthelyezés másik szabad sávba. A szolgáltatás nem változtatható. — Move to another free slot; the service cannot change.

Kérés / request

{ "starts_at": "2026-08-21T09:00:00+02:00" }

Válasz / response

{
  "data": { "id": "9c1…", "status": "confirmed",
            "starts_at": "2026-08-21T09:00:00+02:00",
            "ends_at": "2026-08-21T09:45:00+02:00" }
}

DELETE/api/v1/bookings/{id}

Foglalás lemondása kötelező indoklással (min. 5 karakter). Az ügyfél e-mailben értesül. Már lemondott saját foglalásra is 200 a válasz. — Cancel a booking; a reason of at least 5 characters is required, the customer is emailed, and cancelling an already cancelled booking of yours also returns 200.

Kérés / request

{ "reason": "Az ügyfél lemondta a partner rendszerében." }

Válasz / response

{ "data": { "id": "9c1…", "status": "cancelled" } }

GET/api/v1/limits

A kiosztott kapacitás, korlátok és a mai felhasználás. — Your allocated capacity, limits and today's usage.

Válasz / response

{
  "data": { "name": "Partner Kft.",
            "allowed_services": [ { "id": "6f0…", "name": "Gumicsere 17\"",
                                    "duration_min": 50,
                                    "bay_name": "Gumiszerelés" } ],
            "daily_booking_limit": 4, "bookings_used_today": 2,
            "min_lead_time_hours": 48, "booking_horizon_days": 7,
            "horizon_end": "2026-08-27", "rate_limit_per_minute": 60,
            "windows": [ { "weekday": 2, "bay_name": "Gumiszerelés",
                           "starts_at": "08:00:00", "ends_at": "12:00:00",
                           "max_bookings_per_day": 4 } ],
            "timezone": "Europe/Budapest" }
}

Hibakódok / error codes

401	unauthorized	Hiányzó vagy érvénytelen kulcs, vagy felfüggesztett hozzáférés.
403	service_not_allowed	A szolgáltatás nincs engedélyezve az Ön hozzáférésén.
404	not_found	Nincs ilyen foglalás (idegen foglalás is ezt adja).
409	slot_taken	A sávot időközben elfoglalták.
409	invalid_slot	Az időpont nem foglalható (ablak, előfoglalási idő, horizont).
409	quota_exceeded	Az adott napi kvótája elfogyott — a válasz megírja, mikor nyílik új.
409	plate_conflict	A rendszám már egy másik ügyfélhez tartozik — küldje a hozzá tartozó ügyféladatokat.
409	external_ref_conflict	Ezt az external_ref értéket már használta egy másik foglaláshoz.
409	request_in_progress	Ugyanezzel az Idempotency-Key értékkel épp fut egy kérés — várjon és próbálja újra.
422	invalid_request	Hibás vagy hiányos kérés (pl. időzóna-eltolás nélküli időpont, nem létező dátum).
422	reason_required	A lemondáshoz kötelező legalább 5 karakteres indoklás.
429	rate_limited	Túl sok hívás egy percen belül. Retry-After fejléc szerint várjon.
400	idempotency_key_required	A POST /bookings híváshoz Idempotency-Key kötelező.

Hibaformátum: { "error": { "code": "…", "message": "…" } }

Idempotencia és újrapróbálás

Foglalásnál küldjön saját, egyedi Idempotency-Key fejlécet. Ha ugyanazzal a kulccsal újra hív (hálózati hiba, időtúllépés), az eredeti választ adjuk vissza Idempotent-Replay: true fejléccel, és nem jön létre második foglalás. A foglalás létrehozása egyetlen tranzakcióban fut: ha bármi hibára fut, ügyfél, jármű és foglalás sem marad utána. Ha ugyanaz a kulcs épp feldolgozás alatt van, 409 request_in_progress a válasz. A kulcsokat 30 napig tartjuk meg. 429 esetén a Retry-After szerint várjon; 5xx esetén exponenciális várakozással próbálja újra.

Fejlécek és adatszabályok

Minden válasz Cache-Control: no-store és X-Request-ID fejlécet kap. Küldhet saját X-Request-ID értéket, azt visszatükrözzük és naplózzuk — hibabejelentésnél ezt adja meg.
Az időpontoknál kötelező az explicit időzóna-eltolás (+02:00 vagy Z); eltolás nélküli érték 422 invalid_request. A from/to paraméter valódi YYYY-MM-DD naptári dátum, és from ≤ to.
A rendszám szóköz és kötőjel nélkül, nagybetűsen illesztődik. Ha a rendszám már egy másik ügyfélhez tartozik, 409 plate_conflict a válasz — nem írjuk át a tulajdonost.
Az external_ref partnerenként egyedi, és lekérdezhető: GET /api/v1/bookings?external_ref=….

Hozzáférésért és kulcsért írj a info@proauto.hu címre. A kulcsot egyszer adjuk át, tárolni nem tudjuk — kezelje titkosan.