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.
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.
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}.
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 minucie
5 minutach
30 minutach
2 godzinach
6 godzinach
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.
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