{ "openapi": "3.1.0", "info": { "title": "GuestMe B2B API", "version": "v1.0.0" }, "servers": [ { "url": "http://dev-backend-1.guestme.space", "description": "Generated server url" } ], "security": [ { "basicAuth": [], "bearerAuth": [] } ], "tags": [ { "name": "auth", "description": "OAuth2 авторизация", "x-displayName": "Аутентификация" }, { "name": "restaurants", "description": "Поиск ресторанов, информация, расписание, столы", "x-displayName": "Рестораны" }, { "name": "bookings", "description": "Создание, получение и отмена бронирований", "x-displayName": "Бронирования" }, { "name": "webhooks", "description": "Управление вебхуками для уведомлений", "x-displayName": "Webhooks" } ], "paths": { "/api/v1/external/webhook/{id}": { "put": { "tags": [ "webhooks" ], "summary": "Update a webhook", "operationId": "updateWebhook", "x-slug": "update", "x-sidebar-label": "Обновить", "parameters": [ { "name": "id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookExternalDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WebhookExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "webhooks" ], "summary": "Delete a webhook", "operationId": "deleteWebhook", "x-slug": "delete", "x-sidebar-label": "Удалить", "parameters": [ { "name": "id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "responses": { "200": { "description": "OK" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/webhook": { "get": { "tags": [ "webhooks" ], "summary": "Get all webhooks", "operationId": "getAllWebhooks", "x-slug": "list", "x-sidebar-label": "Список", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookExternalDto" } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "webhooks" ], "summary": "Create a new webhook", "operationId": "createWebhook", "x-slug": "create", "x-sidebar-label": "Создать", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookExternalDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WebhookExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/{id}/confirmation/code/request": { "post": { "tags": [ "bookings" ], "summary": "Request phone number confirmation code for restaurant's notification gateway", "operationId": "requestConfirmationCode", "x-slug": "request-code", "x-sidebar-label": "Запрос кода", "parameters": [ { "name": "id", "in": "path", "description": "Restaurant ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRequestExternalDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CodeTimeLeftExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/{id}/booking": { "post": { "tags": [ "bookings" ], "summary": "Request a booking for a restaurant", "operationId": "requestBooking", "x-slug": "create", "x-sidebar-label": "Создать бронь", "parameters": [ { "name": "id", "in": "path", "description": "Restaurant ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingExternalRequestDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/BookingExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/confirmation/code/verify": { "post": { "tags": [ "bookings" ], "summary": "Verify phone number confirmation code", "operationId": "verifyConfirmationCode", "x-slug": "verify-code", "x-sidebar-label": "Подтвердить код", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeVerificationExternalDto" } } }, "required": true }, "responses": { "200": { "description": "Phone number verified successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant": { "get": { "tags": [ "restaurants" ], "summary": "Get a page of restaurants by search text", "operationId": "findAllRestaurant", "x-slug": "search", "x-sidebar-label": "Поиск ресторанов", "parameters": [ { "name": "search", "in": "query", "description": "Search string for filtering restaurants by name and address", "required": false, "schema": { "type": "string" } }, { "name": "excludeIds", "in": "query", "description": "List of restaurant IDs to exclude from results", "required": false, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "pageable", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Pageable" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PageRestaurantExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/{id}": { "get": { "tags": [ "restaurants" ], "summary": "Get a restaurant by GuestMe ID", "operationId": "getRestaurantById", "x-slug": "get-by-id", "x-sidebar-label": "Ресторан по ID", "parameters": [ { "name": "id", "in": "path", "description": "Restaurant ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RestaurantExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/{id}/table/free/count": { "get": { "tags": [ "restaurants" ], "summary": "Get restaurant free table count by given parameters", "operationId": "countFreeRestaurantTables", "x-slug": "free-tables", "x-sidebar-label": "Свободные столы", "parameters": [ { "name": "id", "in": "path", "description": "Restaurant ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 }, { "name": "date", "in": "query", "description": "Booking ISO date-time", "required": true, "schema": { "type": "string", "format": "date-time" }, "example": "2025-01-01T10:00:00" }, { "name": "persons", "in": "query", "description": "Booking persons", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RestaurantTableCountDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/{id}/schedule": { "get": { "tags": [ "restaurants" ], "summary": "Get restaurant schedule records", "operationId": "getScheduleRecords", "x-slug": "schedule", "x-sidebar-label": "Расписание", "parameters": [ { "name": "id", "in": "path", "description": "Restaurant ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RestaurantScheduleGroupDto" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/restaurant/find/partner/{id}": { "get": { "tags": [ "restaurants" ], "summary": "Find a restaurant by partner system ID or PoS ID", "description": "Finds a restaurant by external system identifier (e.g., iiko, r_keeper)", "operationId": "findByPartnerId", "x-slug": "find-by-partner", "x-sidebar-label": "Поиск по партнёру", "parameters": [ { "name": "id", "in": "path", "description": "External partner ID (e.g., iiko or r_keeper UID)", "required": true, "schema": { "type": "string" }, "example": "123-456-789" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RestaurantExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/external/booking/{id}": { "get": { "tags": [ "bookings" ], "summary": "Get a booking by id", "operationId": "getBooking", "x-slug": "get", "x-sidebar-label": "Получить бронь", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/BookingExternalDto" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "bookings" ], "summary": "Cancel a booking by id", "operationId": "cancelBooking", "x-slug": "cancel", "x-sidebar-label": "Отменить бронь", "parameters": [ { "name": "id", "in": "path", "description": "Booking ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1001 } ], "responses": { "200": { "description": "OK" } }, "security": [ { "bearerAuth": [] } ] } }, "/oauth2/token": { "post": { "tags": [ "auth" ], "summary": "Get access token", "x-slug": "token", "x-sidebar-label": "Получить токен", "description": "Get access_token by client_credentials flow", "parameters": [ { "name": "Authorization", "in": "header", "description": "Basic base64(client_id:client_secret)", "required": true, "schema": { "example": "Basic dnRiOnZ0Yg==" } } ], "requestBody": { "description": "Form for requesting access token using client_credentials", "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "grant_type": { "type": "string", "description": "OAuth2 grant type, must be 'client_credentials'", "example": "client_credentials" }, "scope": { "type": "string", "description": "Must be 'ROLE_EXTERNAL_INTEGRATION'", "example": "ROLE_EXTERNAL_INTEGRATION" } }, "required": [ "grant_type", "scope" ] }, "encoding": { "grant_type": { "style": "form", "explode": true }, "scope": { "style": "form", "explode": true } } } }, "required": true }, "responses": { "200": { "description": "Successful token response", "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "scope": { "type": "string" }, "token_type": { "type": "string", "default": "Bearer" }, "expires_in": { "type": "integer", "format": "int32" } } }, "example": { "scope": "ROLE_EXTERNAL_INTEGRATION", "access_token": "eyJhbGciOiJIUzUxMiJ9...", "token_type": "Bearer", "expires_in": 599 } } } } } } } }, "components": { "schemas": { "WebhookExternalDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Webhook ID" }, "url": { "type": "string", "description": "Webhook request URL", "example": "https://example.com/webhook", "minLength": 1 }, "token": { "type": "string", "description": "Token for webhook request" }, "authorizationHeaderPrefix": { "type": "string", "description": "Authorization header prefix", "example": "Bearer", "maxLength": 20, "minLength": 0 }, "events": { "type": "array", "description": "Set of event types to subscribe", "items": { "type": "string", "enum": [ "CREATE", "UPDATE", "DELETE" ] }, "maxItems": 20, "minItems": 0, "uniqueItems": true }, "entities": { "type": "array", "description": "Set of entity types to subscribe", "items": { "type": "string", "enum": [ "RESTAURANT", "BOOKING" ] }, "maxItems": 20, "minItems": 0, "uniqueItems": true } }, "required": [ "url" ] }, "CodeRequestExternalDto": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone number", "example": "+79998887766", "minLength": 1 } }, "required": [ "phone" ] }, "CodeTimeLeftExternalDto": { "type": "object", "properties": { "timeLeft": { "type": "integer", "format": "int64", "description": "Time left in seconds", "example": 120 } } }, "BookingExternalRequestDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Guest first name", "example": "Mike", "minLength": 1 }, "lastName": { "type": "string", "description": "Guest last name", "example": "Kravec" }, "date": { "type": "string", "format": "date-time", "description": "Booking ISO date", "example": "2025-01-01T00:00:00Z" }, "phone": { "type": "string", "description": "Guest valid phone number", "example": "+79994656464" }, "persons": { "type": "integer", "format": "int32", "description": "Number of persons", "example": 2 }, "comment": { "type": "string", "description": "Guest comment" }, "meta": { "$ref": "#/components/schemas/BookingMetaExternalDto", "description": "Booking meta" } }, "required": [ "date", "firstName", "persons", "phone" ] }, "BookingMetaExternalDto": { "type": "object", "properties": { "promo": { "type": "string", "description": "Booking promo code" } } }, "BookingExternalDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Booking ID", "example": 1001 }, "persons": { "type": "integer", "format": "int32", "description": "Number of persons", "example": 2 }, "firstName": { "type": "string", "description": "Guest first name", "example": "Mike" }, "lastName": { "type": "string", "description": "Guest last name", "example": "Kravec" }, "phone": { "type": "string", "description": "Guest valid phone number", "example": "+79994656464" }, "comment": { "type": "string", "description": "Guest comment" }, "state": { "type": "string", "description": "Booking state", "enum": [ "ACCEPTED", "DECLINED", "CANCELING", "CANCELED", "CREATED", "SENT", "CLOSED", "IN_PROGRESS", "PATCHING", "ERROR" ], "example": "ACCEPTED" }, "date": { "type": "string", "format": "date-time", "description": "Booking ISO date", "example": "2025-01-01T00:00:00Z" }, "meta": { "$ref": "#/components/schemas/BookingMetaExternalDto", "description": "Booking meta" } }, "required": [ "date", "firstName", "id", "persons", "phone", "state" ] }, "CodeVerificationExternalDto": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone number", "example": "+79998887766", "minLength": 1 }, "code": { "type": "string", "description": "Verification code", "example": 123456, "minLength": 1 } }, "required": [ "code", "phone" ] }, "Pageable": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0 }, "size": { "type": "integer", "format": "int32", "minimum": 1 }, "sort": { "type": "array", "items": { "type": "string" } } } }, "AddressExternalDto": { "type": "object", "properties": { "country": { "type": "string", "description": "Country", "example": "Russia" }, "countryCode": { "type": "string", "description": "Country code", "example": "RU" }, "city": { "type": "string", "description": "City", "example": "Moscow" }, "home": { "type": "string", "description": "Home number", "example": 123 }, "street": { "type": "string", "description": "Street", "example": "Lenina" }, "point": { "$ref": "#/components/schemas/GeoPoint", "description": "Geo point" } }, "required": [ "city", "country", "countryCode", "home", "point", "street" ] }, "GeoPoint": { "type": "object", "properties": { "x": { "type": "number", "format": "double" }, "y": { "type": "number", "format": "double" } } }, "PageRestaurantExternalDto": { "type": "object", "properties": { "totalPages": { "type": "integer", "format": "int32" }, "totalElements": { "type": "integer", "format": "int64" }, "pageable": { "$ref": "#/components/schemas/PageableObject" }, "numberOfElements": { "type": "integer", "format": "int32" }, "size": { "type": "integer", "format": "int32" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/RestaurantExternalDto" } }, "number": { "type": "integer", "format": "int32" }, "sort": { "$ref": "#/components/schemas/SortObject" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "empty": { "type": "boolean" } } }, "PageableObject": { "type": "object", "properties": { "unpaged": { "type": "boolean" }, "paged": { "type": "boolean" }, "pageNumber": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" }, "offset": { "type": "integer", "format": "int64" }, "sort": { "$ref": "#/components/schemas/SortObject" } } }, "RestaurantExternalDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string", "description": "Restaurant name", "example": "Gussi" }, "status": { "type": "string", "description": "Restaurant status", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ], "example": "ACTIVE" }, "description": { "type": "string", "description": "Restaurant description", "example": "Gussi is a good restaurant" }, "address": { "$ref": "#/components/schemas/AddressExternalDto", "description": "Restaurant address" }, "info": { "$ref": "#/components/schemas/RestaurantInfoExternalDto", "description": "Restaurant info" }, "properties": { "$ref": "#/components/schemas/RestaurantPropertiesExternalDto", "description": "Restaurant properties" } }, "required": [ "address", "id", "info", "name", "properties", "status" ] }, "RestaurantInfoExternalDto": { "type": "object", "properties": { "phone": { "type": "string", "description": "Restaurant phone number", "example": "+79998887766" }, "site": { "type": "string", "description": "Restaurant site" }, "telegram": { "type": "string", "description": "Restaurant Telegram" }, "vk": { "type": "string", "description": "Restaurant VK" }, "iikoUid": { "type": "string", "description": "IIKO UID", "example": "123-456-789" }, "iikoCrmId": { "type": "string", "description": "IIKO CRM ID", "example": 123456789 }, "taxNumber": { "type": "string", "description": "Tax number", "example": 123456789 } } }, "RestaurantPropertiesExternalDto": { "type": "object", "properties": { "phoneConfirmationEnabled": { "type": "boolean", "description": "Indicates that the restaurant has enabled phone confirmation" }, "guestAcquisitionChannelEnabled": { "type": "boolean", "description": "Indicates that the restaurant has connected this guest acquisition channel and you can send your reservations to it" } }, "required": [ "guestAcquisitionChannelEnabled", "phoneConfirmationEnabled" ] }, "SortObject": { "type": "object", "properties": { "unsorted": { "type": "boolean" }, "sorted": { "type": "boolean" }, "empty": { "type": "boolean" } } }, "RestaurantTableCountDto": { "type": "object", "properties": { "count": { "type": "integer", "format": "int64" } } }, "RestaurantScheduleGroupDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "date": { "type": "string", "format": "date" }, "day": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ] }, "type": { "type": "string", "enum": [ "RESTAURANT", "BOOKING" ] }, "restaurantId": { "type": "integer", "format": "int64" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/RestaurantScheduleRecordDto" }, "minItems": 1 } }, "required": [ "day", "records", "restaurantId", "type" ] }, "RestaurantScheduleRecordDto": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "isWorkingTime": { "type": "boolean" }, "day": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ] }, "type": { "type": "string", "enum": [ "RESTAURANT", "BOOKING" ] } }, "required": [ "day", "end", "isWorkingTime", "start" ] }, "ExternalDto": { "description": "Event inheritable payload", "oneOf": [ { "$ref": "#/components/schemas/BookingExternalDto" }, { "$ref": "#/components/schemas/RestaurantExternalDto" } ] }, "WebhookEventExternalDto": { "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Event UUID", "example": "00000000-0000-0000-0000-000000000000" }, "date": { "type": "string", "format": "date-time", "description": "Event ISO date", "example": "2025-01-01T00:00:00Z" }, "data": { "$ref": "#/components/schemas/ExternalDto" }, "event": { "type": "string", "description": "Event type", "enum": [ "CREATE", "UPDATE", "DELETE" ], "example": "UPDATE" }, "entity": { "type": "string", "description": "Entity type", "enum": [ "RESTAURANT", "BOOKING" ], "example": "BOOKING" } }, "required": [ "data", "date", "entity", "event", "uuid" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "basicAuth": { "type": "http", "scheme": "basic" } } } }