Para agentes de IA: markdown desta página — /docs-content-en/entities/booking-wait-list/booking.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Book from the wait list

POST /v1/booking-wait-list/:id/booking

Creates a booking from a wait list record: the record's clients move to the new booking, and the record itself is removed from the wait list.

Fields go at the root of the JSON, without a fields wrapper. Messages to the client about the booking depend on the is*NotificationOn switches of the booking resource.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionWait list record identifier. List: GET /v1/booking-wait-list

Request fields (body)

Field Type Required Description
FieldresourceIds Typenumber[] Requiredyes DescriptionIdentifiers of the resources the booking reserves. The array cannot be empty. List: GET /v1/booking-resources
FielddatePeriod.from.timestamp Typenumber Requiredyes DescriptionBooking start, Unix time in seconds
FielddatePeriod.from.timezone Typestring Requiredyes DescriptionTime zone of the start in IANA format, e.g. UTC
FielddatePeriod.to.timestamp Typenumber Requiredyes DescriptionBooking end, Unix time in seconds. Must be later than the start
FielddatePeriod.to.timezone Typestring Requiredyes DescriptionTime zone of the end in IANA format

The body accepts no other fields. The booking name and description are set by updating the booking.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/booking-wait-list/27/booking" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceIds": [49],
    "datePeriod": {
      "from": { "timestamp": 1795158000, "timezone": "UTC" },
      "to": { "timestamp": 1795161600, "timezone": "UTC" }
    }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/booking-wait-list/27/booking" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceIds": [49],
    "datePeriod": {
      "from": { "timestamp": 1795158000, "timezone": "UTC" },
      "to": { "timestamp": 1795161600, "timezone": "UTC" }
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/booking-wait-list/27/booking', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    resourceIds: [49],
    datePeriod: {
      from: { timestamp: 1795158000, timezone: 'UTC' },
      to: { timestamp: 1795161600, timezone: 'UTC' },
    },
  }),
})

const { data } = await res.json()
console.log('Booking ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/booking-wait-list/27/booking', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    resourceIds: [49],
    datePeriod: {
      from: { timestamp: 1795158000, timezone: 'UTC' },
      to: { timestamp: 1795161600, timezone: 'UTC' },
    },
  }),
})

const { data } = await res.json()
console.log('Booking ID:', data.id)

Response fields

On success, the HTTP status is 201 Created and the response contains the card of the new booking — the same as GET /v1/bookings/:id returns.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typenumber DescriptionBooking identifier. The booking's clients are returned by GET /v1/bookings/:id/clients
Fielddata.name Typestring | null DescriptionBooking name
Fielddata.description Typestring | null DescriptionBooking description
Fielddata.resourceIds Typenumber[] DescriptionIdentifiers of the reserved resources
Fielddata.datePeriod Typeobject DescriptionBooking period: from and to are ISO 8601 date-time strings

Response example

JSON 
{
  "success": true,
  "data": {
    "datePeriod": {
      "from": "2026-11-20T07:00:00+00:00",
      "to": "2026-11-20T08:00:00+00:00"
    },
    "description": null,
    "id": 49,
    "name": null,
    "resourceIds": [
      49
    ]
  }
}

Error response example

404 — there is no wait list record with this id, for example because it has already been moved to a booking:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Booking record not found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no wait list record with this id, including one already moved to a booking. Message Booking record not found
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionresourceIds or datePeriod is missing, or resourceIds is an empty array. Message resourceIds and datePeriod are required
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than resourceIds and datePeriod. Message Only resourceIds and datePeriod can be written
HTTP400 CodeINVALID_PARAMS DescriptionresourceIds contains a value that is not a positive integer. Message resourceIds must contain positive integers
HTTP400 CodeINVALID_PARAMS Descriptionfrom or to has no timestamp or timezone. Message datePeriod requires from/to with a finite timestamp and timezone
HTTP400 CodeINVALID_PARAMS DescriptionThe time zone is not in IANA format. Message timezone must be an IANA timezone
HTTP400 CodeINVALID_PARAMS DescriptionThe body is not a JSON object. Message Body must contain resourceIds and datePeriod
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer. Message id must be a canonical positive safe integer
HTTP422 CodeBITRIX_ERROR DescriptionA resource from resourceIds does not exist. Message Some resources were not found with the resource IDs, b24Code 1038
HTTP422 CodeBITRIX_ERROR DescriptionThe booking end is earlier than the start. Message Invalid date period
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the booking scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP429 CodeRATE_LIMITED DescriptionRequest rate exceeded. The effective cap is in the x-ratelimit-limit header
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 returned a response of an unexpected shape. If this happened while re-reading the booking after creation, the booking has already been created and the record removed from the wait list — find the booking in the list of bookings before retrying

Full list of common API errors — Errors.

Known specifics

A rejected request does not remove the record. On a 400 or 422 response, the record stays in the wait list, and the move can be retried.

The booking card does not return the note. The record's note moves to the booking, but the booking card has no field for it, and description stays null. When the booking is moved back to the wait list, the note returns to the new wait list record.

See also