Ta strona po polsku czeka na sprawdzenie przez native speakera. Wersja angielska jest wiążąca.

Served dla programistów

Odczytuj rezerwacje, gości i dostępność lokalu i dowiaduj się o każdej zmianie rezerwacji, gdy tylko nastąpi. Klucze tworzy właściciel lokalu; nie trzeba przystępować do programu partnerskiego.

Uwierzytelnianie

Właściciel lokalu tworzy klucz API w Served: Ustawienia, Dla programistów. Klucz zaczyna się od sv_live_, należy do jednego lokalu i jest pokazywany tylko raz. Served przechowuje tylko jego skrót.

Wysyłaj klucz jako token Bearer w każdym żądaniu. Brakujący, nieznany lub unieważniony klucz dostaje 401. Klucz unieważnisz w tym samym miejscu; przestaje działać od razu.

curl "https://served.global/api/v1/bookings?from=2026-11-14&to=2026-11-15" \
  -H "Authorization: Bearer sv_live_..."
Otwórz Ustawienia, Dla programistów

Zakresy

Każdy klucz ma jeden lub więcej zakresów odczytu. Żądanie poza nimi dostaje 403 insufficient_scope.

  • bookings:read Rezerwacje: GET /bookings i GET /bookings/{id}.
  • guests:read Goście: GET /guests i GET /guests/{id}, z imionami i nazwiskami, danymi kontaktowymi, zgodami marketingowymi i liczbą wizyt.
  • availability:read Dostępność: GET /availability, terminy, które oferuje strona rezerwacji lokalu.

Limity i błędy

  • 120 żądań na minutę na klucz. Powyżej dostajesz 429 rate_limited z nagłówkiem Retry-After w sekundach.
  • Listy przychodzą stronami do 100 wierszy, 50, jeśli nie ustawisz limit. Gdy next_cursor nie jest null, przekaż go jako cursor, aby pobrać następną stronę.
  • Każda odpowiedź to JSON, wysyłany z Cache-Control: no-store i bez plików cookie. Czasy są w ISO 8601, w UTC.

Błędy mają jeden kształt, z kodem do rozróżniania:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the guests:read scope."
  }
}
unauthorized
401: nie wysłano klucza Bearer.
invalid_key
401: klucz jest nieznany lub unieważniony.
insufficient_scope
403: klucz nie ma zakresu tego punktu końcowego.
plan_required
403: lokal jest w planie Served Start.
rate_limited
429: ponad 120 żądań w minucie.
invalid_request
400: parametr zapytania jest nieprawidłowy; komunikat mówi który.
not_found
404: brak takiego rekordu w tym lokalu.
unavailable
503: spróbuj ponownie za chwilę.

Plany

Każdy płatny plan Served obejmuje API i webhooki bez dodatkowych opłat. Served Start nie: jego żądania dostają 403 plan_required, a właściciele widzą zachętę do zmiany planu zamiast kluczy. Plan jest sprawdzany przy każdym żądaniu.

Punkty końcowe API

Bazowy URL: https://served.global/api/v1. Każdy punkt końcowy odczytuje tylko lokal, do którego należy klucz.

Lista rezerwacji

GET /api/v1/bookings

Rezerwacje według godziny rozpoczęcia, od najstarszej.

Zakres: bookings:read

Parametry zapytania

from
Początek w tej dacie lub później.
to
Początek przed tą datą.
status
pending, requested, held, confirmed, seated, completed, cancelled lub no_show.
limit
Od 1 do 100, domyślnie 50.
cursor
next_cursor z poprzedniej strony.

Przykładowa odpowiedź

{
  "data": [
    {
      "id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
      "reference": "K7Q2M9XA",
      "status": "confirmed",
      "party": 4,
      "starts_at": "2026-11-14T18:30:00.000Z",
      "ends_at": "2026-11-14T20:00:00.000Z",
      "channel": "online",
      "via": "instagram",
      "table": {
        "id": "8b2e4c6a-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
        "label": "T12"
      },
      "deposit_status": "paid",
      "guest_id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
      "created_at": "2026-11-02T09:12:44.000Z",
      "updated_at": "2026-11-02T09:12:44.000Z"
    }
  ],
  "next_cursor": "WyIyMDI2LTExLTE0VDE4OjMwOjAwKzAwOjAwIiwiM2YxYzJiOWUtN2E0ZC00ZThiLTljMjEtNWQ2ZTdmOGE5YjBjIl0"
}

Pobierz rezerwację

GET /api/v1/bookings/{id}

Jedna rezerwacja według id.

Zakres: bookings:read

Przykładowa odpowiedź

{
  "data": {
    "id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "reference": "K7Q2M9XA",
    "status": "confirmed",
    "party": 4,
    "starts_at": "2026-11-14T18:30:00.000Z",
    "ends_at": "2026-11-14T20:00:00.000Z",
    "channel": "online",
    "via": "instagram",
    "table": {
      "id": "8b2e4c6a-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
      "label": "T12"
    },
    "deposit_status": "paid",
    "guest_id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
    "created_at": "2026-11-02T09:12:44.000Z",
    "updated_at": "2026-11-02T09:12:44.000Z"
  }
}

Lista gości

GET /api/v1/guests

Goście z CRM lokalu według ostatniej zmiany, od najstarszej, aby synchronizować zmiany.

Zakres: guests:read

Parametry zapytania

updated_since
Zmienieni w tej dacie lub później.
limit
Od 1 do 100, domyślnie 50.
cursor
next_cursor z poprzedniej strony.

Przykładowa odpowiedź

{
  "data": [
    {
      "id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
      "first_name": "Ola",
      "last_name": "Nowak",
      "email": "ola@example.com",
      "phone": "+48 600 000 000",
      "marketing": {
        "email": true,
        "consent_status": "granted"
      },
      "visit_count": 6,
      "created_at": "2026-03-08T19:02:10.000Z",
      "updated_at": "2026-11-02T09:12:44.000Z"
    }
  ],
  "next_cursor": null
}

Pobierz gościa

GET /api/v1/guests/{id}

Jeden gość według id.

Zakres: guests:read

Przykładowa odpowiedź

{
  "data": {
    "id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
    "first_name": "Ola",
    "last_name": "Nowak",
    "email": "ola@example.com",
    "phone": "+48 600 000 000",
    "marketing": {
      "email": true,
      "consent_status": "granted"
    },
    "visit_count": 6,
    "created_at": "2026-03-08T19:02:10.000Z",
    "updated_at": "2026-11-02T09:12:44.000Z"
  }
}

Pobierz dostępność

GET /api/v1/availability

Terminy dla jednej daty i liczby osób, z tej samej usługi co strona rezerwacji lokalu.

Zakres: availability:read

Parametry zapytania

date
Wymagany, RRRR-MM-DD w kalendarzu lokalu.
party
Od 1 do 20, domyślnie 2.

Przykładowa odpowiedź

{
  "data": {
    "date": "2026-11-14",
    "party": 4,
    "capacity_known": true,
    "slots": [
      {
        "time": "18:00",
        "available": true
      },
      {
        "time": "18:30",
        "available": false
      },
      {
        "time": "19:00",
        "available": true
      }
    ]
  }
}

Webhooki

Właściciel dodaje punkt końcowy https i wybiera jego zdarzenia w Ustawieniach, w sekcji Dla programistów. Served pokazuje sekret podpisu punktu końcowego tylko raz.

Served wysyła JSON na punkt końcowy w ciągu około minuty od zmiany. Każda odpowiedź 2xx potwierdza odbiór. Id zdarzenia jest takie samo przy każdym ponowieniu, więc używaj go do pomijania duplikatów.

Zdarzenia

  • booking.created: utworzono rezerwację, przez gościa lub personel. data to rezerwacja.
  • booking.changed: zmienił się jej stan, liczba osób, godzina, długość lub stolik. data to rezerwacja.
  • booking.cancelled: rezerwację odwołano. data to rezerwacja.
  • guest.created: do CRM dodano gościa. data zawiera tylko id i zgody; gościa odczytasz przez GET /guests/{id}.

Nagłówki każdej dostawy

Served-Signature
t=<sekundy unix>,v1=<podpis>, patrz niżej.
Served-Event
Typ zdarzenia.
Served-Delivery
Id dostawy, dla wsparcia.

Przykładowa dostawa

{
  "id": "0b7e9d2c-5a1f-4c3e-9d8b-7a6f5e4d3c2b",
  "type": "booking.created",
  "created_at": "2026-11-02T09:12:45.000Z",
  "data": {
    "id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "reference": "K7Q2M9XA",
    "status": "confirmed",
    "party": 4,
    "starts_at": "2026-11-14T18:30:00.000Z",
    "ends_at": "2026-11-14T20:00:00.000Z",
    "channel": "online",
    "via": "instagram",
    "table": {
      "id": "8b2e4c6a-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
      "label": "T12"
    },
    "deposit_status": "paid",
    "guest_id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
    "created_at": "2026-11-02T09:12:44.000Z",
    "updated_at": "2026-11-02T09:12:44.000Z"
  }
}

Served wysyła tylko do publicznych hostów https: bez adresów IP, bez sieci prywatnych i lokalnych. Nie podąża za przekierowaniami, czeka na odpowiedź 5 sekund i czyta z niej najwyżej 1 KB.

Sprawdzanie podpisów

Served podpisuje "<t>.<surowa treść>" algorytmem HMAC-SHA256 sekretem punktu końcowego i wysyła skrót szesnastkowy jako v1. Sprawdź go na surowej treści przed jej parsowaniem, porównuj w stałym czasie i odrzucaj t starsze niż 5 minut.

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the request body exactly as received, before JSON.parse.
export function verifyServedSignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (!signatureHeader) return false
  const parts = signatureHeader.split(',').map((part) => part.trim().split('='))
  const timestamp = Number(parts.find(([key]) => key === 't')?.[1])
  if (!Number.isInteger(timestamp)) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest()
  return parts.some(([key, value]) => {
    if (key !== 'v1' || !value) return false
    const given = Buffer.from(value, 'hex')
    return given.length === expected.length && timingSafeEqual(given, expected)
  })
}

// Express: keep the raw body on the webhook route.
app.post('/served-webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body.toString('utf8')
  if (!verifyServedSignature(body, req.get('Served-Signature'), process.env.SERVED_WEBHOOK_SECRET)) {
    return res.sendStatus(400)
  }
  const event = JSON.parse(body)
  // event.id is the same on every retry: skip one you have handled.
  res.sendStatus(200)
})

Ponowienia

Dostawa, która się nie powiedzie (brak odpowiedzi w 5 sekund, przekierowanie lub stan spoza 2xx), jest ponawiana po:

  1. 1 minucie
  2. 5 minutach
  3. 30 minutach
  4. 2 godzinach
  5. 6 godzinach
  6. 24 godzinach

Jeśli i ostatnia próba się nie powiedzie, Served porzuca tę dostawę. Punkt końcowy, który przez 3 dni nie przyjął żadnej dostawy, zostaje wyłączony, dopóki właściciel go nie włączy. Dziennik dostaw w konsoli pokazuje każdą próbę, a właściciel może wysłać dostawę ponownie. Dostawy i zdarzenia są przechowywane 30 dni.

Czego API nigdy nie wysyła

  • Notatek, alergii, diety ani informacji o zdrowiu, przy rezerwacji ani przy gościu.
  • Imienia i nazwiska ani danych kontaktowych gościa przy rezerwacji: rezerwacja wskazuje gościa przez guest_id, które rozwiązuje zakres guests:read.
  • Tagów, powodów odwołania, notatek personelu ani żadnego innego wolnego tekstu.

OpenAPI

Całe API, webhooki i ich pola są opisane w OpenAPI 3.1, gotowe dla Postmana, Insomnii i generatorów kodu.

Otwórz openapi.json

Optional analytics helps us improve Served: Google Analytics on this site, product analytics in the app and, on venue booking pages, the venue’s ad pixels (Meta, Google, TikTok). Declining does not limit any feature. Cookie Policy