Skip to content
BILLZ for developers

Create

POST
/v2/transfer
curl --request POST \
  --url 'https://api-admin.billz.ai/v2/transfer?Billz-Response-Channel=HTTP' \
  --header 'Authorization: Bearer <token>' \
  --header 'Billz-Response-Channel: HTTP' \
  --header 'Content-Type: application/json' \
  --header 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \
  --data '{ "arrival_shop_id": "92302dfb-fa33-4e6a-8d19-87214852b25d", "departure_shop_id": "fbfb9d6c-cbb2-43ab-8c90-e97d2eeb34d6", "name": "Трансфер 2023.05.17 14:47" }'

Asynchronous method. To receive the result synchronously over HTTP, pass the Billz-Response-Channel: HTTP header — otherwise the response will be 200 {"message": "<correlation_id>"}. Maximum wait is 600 seconds, after which 408 with error.code = TIMEOUT is returned.

Error codes: 400 — input validation error; 404 — object not found; 408 — timed out waiting for the asynchronous result; 401, 403, 429, 500 — shared by all methods. Body formats and semantics: Response codes and errors.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
platform-id
string
default: 7d4a4c38-dd84-4902-b744-0488b80a4c01

Platform identifier. A static value is used for integrations.

Billz-Response-Channel
string
Allowed values: HTTP

HTTP — wait for the event processing result and return it in the HTTP response. Without the header the method returns only the correlation_id of the published event.

Query Parameters

Section titled “Query Parameters”
Billz-Response-Channel
string
Allowed values: HTTP

Same as the Billz-Response-Channel header — for clients that cannot send a custom header. If both are passed, the header applies.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
departure_shop_id
required

The sending shop must be accessible to the user, otherwise 400

string
arrival_shop_id
required
string
name
required
string
session_id
string
transfer_items

Items can be passed right away at creation

Array<object>
object
id

Generated by the server

string
external_id

Generated by the server

integer format: int32
company_id
string
created_by
object
id
string
name
string
Example
{
  "arrival_shop_id": "92302dfb-fa33-4e6a-8d19-87214852b25d",
  "departure_shop_id": "fbfb9d6c-cbb2-43ab-8c90-e97d2eeb34d6",
  "name": "Трансфер 2023.05.17 14:47"
}

Responses

Section titled “Responses”

200

Section titled “200”

Success. With the Billz-Response-Channel: HTTP header — the asynchronous response envelope, without it — {"message": "<correlation_id>"}.

Media typeapplication/json
One of:

Asynchronous response envelope. Returned when the Billz-Response-Channel: HTTP header is passed. The final HTTP code of the request is taken from the status_code field.

object
session_id

Customer session identifier

string format: uuid
status_code

Event processing status (also the final HTTP response code)

integer
error
object
code

Error code, empty string if there is no error

string
message

Error text, empty string if there is no error

string
correlation_id

Request identifier, matches the ID of the published event

string format: uuid
topic

Response event type, for example <event_type>.success

string
data

Operation result, if the method returns one

object
Examplegenerated
{
  "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status_code": 1,
  "error": {
    "code": "example",
    "message": "example"
  },
  "correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "topic": "example",
  "data": {}
}