Create claim

The method creates a claim with the specified parameters in the system Yango Delivery. Sending a request doesn't mean that the order has been accepted.
For same-day delivery, you need to fill in the "same_day_data" field in the request body and specify the dimensions and weight of the item. You don't need to fill out the "client_requirements" section.
You can find out the order evaluation result using the method claims/info.

Request

POST

b2b.taxi.yandex.net/b2b/cargo/integration/v2/claims/create

Service URL

Query parameters

Name

Description

request_id*

Type: string

Idempotency token. Letters, numbers, and other symbols are allowed. To guarantee that values are unique, we recommend using the uuid format and its derivatives.

If a server error (code 5xx) or timeout occur when creating a claim, use the same value to retry. (Otherwise, claim duplicating is possible, which may result in multiple couriers coming for the order).

In other cases (when creating a new claim), use the new request_id value.

Learn more


Min length: 1

Max length: 128

Headers

Name

Description

Accept-Language*

Type: string

Preferred response language. Examples: "en" ā€” English

Example: en

Body

application/json
{
    "shipping_document": "string",
    "items": [
        {
            "extra_id": "BP-208",
            "pickup_point": 1,
            "droppof_point": 2,
            "title": "Plumbus",
            "size": {
                "length": 0.1,
                "width": 0.2,
                "height": 0.3
            },
            "weight": 2,
            "cost_value": "2.00",
            "cost_currency": "AED",
            "quantity": 1,
            "fiscalization": {
                "excise": "12.50",
                "vat_code_str": "vat_none",
                "supplier_inn": 3664069397,
                "article": "20ML50OWKY4FC86",
                "mark": {
                    "kind": "gs1_data_matrix_base64",
                    "code": "444D00000000003741"
                },
                "item_type": "product"
            }
        }
    ],
    "route_points": [
        {
            "point_id": 6987,
            "visit_order": 1,
            "contact": {
                "name": "Bryan Burns",
                "phone": "+97142774444",
                "phone_additional_code": "602 17 500",
                "email": "customer-BryanBurns@yango.com"
            },
            "address": {
                "fullname": "One Central Building 5, Trade Center Second, Dubai",
                "shortname": "One Central Building 5, Trade Center Second",
                "coordinates": [
                    0
                ],
                "country": "UAE",
                "city": "Dubai",
                "building_name": "Dubai",
                "street": "Trade Center Second",
                "building": "building number",
                "porch": "A",
                "sfloor": "1",
                "sflat": "1",
                "door_code": "169",
                "door_code_extra": "courtyard entrance code #1234, apartment code #4321",
                "doorbell_name": "Magidovich",
                "comment": "The intercom doesn't work",
                "uri": "ymapsbm1://geo?ll=38.805%2C55.084",
                "description": "Yango Dubai Office, One Central Building 5, Trade Center Second, Dubai"
            },
            "skip_confirmation": false,
            "leave_under_door": false,
            "meet_outside": false,
            "no_door_call": false,
            "type": "source",
            "buyout": {
                "payment_method": "card"
            },
            "payment_on_delivery": {
                "customer": {
                    "inn": 3664069397,
                    "email": "customer-BryanBurns@yango.com",
                    "phone": "+97142774444"
                },
                "payment_method": "card"
            },
            "external_order_id": "100",
            "external_order_cost": {
                "value": "100.0",
                "currency": "AED",
                "currency_sign": "currency sign (if exists)"
            },
            "pickup_code": "893422"
        }
    ],
    "emergency_contact": {
        "name": "Rick",
        "phone": "+97142772222",
        "phone_additional_code": "602 17 500"
    },
    "client_requirements": {
        "taxi_class": "express",
        "cargo_type": "lcv_m",
        "cargo_loaders": 0,
        "cargo_options": [
            "thermobag"
        ],
        "pro_courier": false
    },
    "callback_properties": {
        "callback_url": "https://www.example.com/"
    },
    "skip_door_to_door": false,
    "skip_client_notify": false,
    "skip_emergency_notify": false,
    "skip_act": false,
    "optional_return": false,
    "due": "2020-01-01T00:00:00+00:00",
    "comment": "Restaurant",
    "referral_source": "WooCommerce",
    "same_day_data": {
        "delivery_interval": {
            "from": "2020-01-01T07:00:00+00:00",
            "to": "2020-01-01T07:00:00+00:00"
        }
    },
    "auto_accept": false,
    "offer_payload": "asjdijasDKL;ahsdfljhlkjhasF;HS;Ldjf;ljloshf"
}

Name

Description

items*

Type: V2CargoItem[]

Item parameters

Min items: 1

route_points*

Type: V2CargoPoint[]

Route point information

Min items: 2

auto_accept

Type: boolean

Enable automatic claim confirmation after creation. A manager's approval is required to use this option

callback_properties

Type: CallbackProperties

Parameters for notifying the client's server about the claim status change.

A notification is a POST request to the specified URL to
which information about the date of the last claim change
and claim ID in the format
'updated_ts=&claim_id=' will be added. Which means that this URL
'https://example.com/?my_order_id=123&' format will be expanded into
'https://example.com/?my_order_id=123&updated_ts=...&claim_id=...'.

Note that parameters are added by concatenation to callback_url, which means that the
URL such as 'https://example.com' will turn into this invalid format:
'https://example.comupdated_ts=...&claim_id=...'.

Only HTTP and HTTPS are supported. In the case of HTTPS, an SSL certificate must
be issued by a certification authority known to the server.

Notifications should be viewed as a push ahead of polling, a way
of speeding up information on status changes. The server expects
the 200 response, and if there are timeouts or any other response, it will attempt
to deliver the notification and then stop the attempts.
So in order to reliably obtain the claim status, the client
needs to request information using the method claims/info.

The client should note that the response of the claims/info operation may
contain an older claim state (the value of the
updated_ts field should be used as a reference). In this case, the operation
call must be repeated after some time (from 5 to 30 seconds).

client_requirements

Type: ClientRequirements

Customer requirements specified when creating or editing a claim

comment

Type: string

Comment to the order

Example: Restaurant

Max length: 7000

due

Type: string<date-time>

Estimated time of arrival of the courier.
If this parameter isn't specified, we will look for a courier as soon as possible.

Example: 2020-01-01T00:00:00+00:00

emergency_contact

Type: ContactWithPhone

Information about the contact person with a phone number

offer_payload

Type: string

Payload obtained using the method offers/calculate

Example: asjdijasDKL;ahsdfljhlkjhasF;HS;Ldjf;ljloshf

optional_return

Type: boolean

Disable item return in case of order cancellation.

Possible values:

  • true (the courier keeps the item)
  • false (by default, the item must be returned)

referral_source

Type: string

Claim source (the name of the CMS where the request is created can be entered)
When integrating via a module or aggregator, use referral_source obtained from the Yango integration team.

Example: WooCommerce

same_day_data

Type: SameDayData

Features of a "Same-day delivery" order

shipping_document

Type: string

Shipping documents

skip_act

Type: boolean

Don't show an acceptance certificate

skip_client_notify

Type: boolean

Don't send SMS notifications to the sender/recipient
when a courier is on their way.

Default value: false (send notifications)

skip_door_to_door

Type: boolean

Disable door-to-door delivery (disable the "Door-to-door" option).

Possible values:

  • true (the courier will deliver the order only at the entrance outside)
  • false (the courier will deliver the order to the door) - default value

skip_emergency_notify

Type: boolean

Don't send a notification to the emergency contact person

Default value: false (send notifications)

V2CargoItem

Name

Description

cost_currency*

Type: string

Three-digit code of the payment currency

Example: AED

Min length: 3

Max length: 3

cost_value*

Type: string

Price per item in cost_currency.
To insure the cost, enter the actual cargo price

Example: 2.00

droppof_point*

Type: integer<int64>

ID of the point (int64) to deliver
the item to. Differs from the ID in the claim.

It can be any number. Must match the route_points[].point_id value
of the destination point

Example: 2

pickup_point*

Type: integer<int64>

ID of the point (int64) to pick up
the item from. Differs from the ID in the claim.

It can be any number. Must match the route_points[].point_id value
of the dispatch point

Example: 1

quantity*

Type: integer<int64>

Number of units (int64)

Example: 1

Min value: 1

title*

Type: string

Item name

Example: Plumbus

extra_id

Type: string

Short unique item ID (order number in the claim, usually identical to external_order_id)

Example: BP-208

Max length: 512

fiscalization

Type: ItemFiscalization

Fiscalization information (valid for payment upon receipt)

size

Type: CargoItemSizes

Unit dimensions in meters. The actual values should be added to the fields.

If the dimensions aren't added, the order is placed, taking into account
the maximum dimensions allowed for the selected rate.

If the actual characteristics of the unit exceed the allowed dimensions,
the courier has the right to refuse to fulfill the order on site.
In this case, the minimum fee will be withheld.

Courier: up to 0.80 m Ɨ 0.50 m Ɨ 0.50 Š¼
Express: up to 1.00 m Ɨ 0.60 m Ɨ 0.50 m
Cargo:

  • Small body: up to 1.70 m Ɨ 0.96 m Ɨ 0.90 m
  • Medium body: up to 2.60 m Ɨ 1.30 m Ɨ 1.50 m
  • Large body: up to 3.80 m Ɨ 1.80 m Ɨ 1.80 m

weight

Type: number

Item weight in kg. The actual values should be entered in the field.

If the weight isn't added, the order is placed, taking into account
the maximum dimensions allowed for the selected rate.

If the actual characteristics of the parcel exceed the allowed dimensions,
the courier has the right to refuse to fulfill the order on site.
In this case, the minimum fee will be withheld.

Courier: up to 10 kg
Express: up to 20 kg
Cargo:

  • Small body: up to 300 kg
  • Medium body: up to 700 kg
  • Large body: up to 1400 kg

Example: 2

V2CargoPoint

Name

Description

address*

Type: CargoPointAddress

Point address

contact*

Type: ContactOnPoint

Information about the contact person

point_id*

Type: integer<int64>

Integer point ID (int64), unique within claim creation

Example: 6987

type*

Type: PointType

Point type:

  • source: the point of departure where the courier picks up the item
  • destination: destination points where the courier delivers the items
  • return: item return point (added automatically and matches the point of departure by default, but a different point can also be selected)

Example: source

Enum: source, destination, return

visit_order*

Type: integer<int64>

The order in which the points are visited (numbering starts with 1) (int64)

Example: 1

buyout

Type: RequestBuyout

Information on item buyout by the courier at the point of departure (relevant if payment upon receipt is enabled for all destination points on the route).

external_order_cost

Type: ExternalOrderCost

Cost of the external order linked to the point

external_order_id

Type: string

Order number from the customer's system.
Entered for destination points

Example: 100

Max length: 512

leave_under_door

Type: boolean

Leave the parcel at the door

meet_outside

Type: boolean

The courier will be met outside, at the entrance

no_door_call

Type: boolean

Don't ring the doorbell

payment_on_delivery

Type: RequestPaymentOnDelivery

Information about payment upon receipt (relevant for payment upon receipt)

pickup_code

Type: string

Parcel pick-up code.
The courier needs to enter this code to confirm that they have picked up the parcel.
This requires your employees to be at the point of dispatch to provide this code to the courier.
Relevant for source points.
Code format: 6 digits
|
Item pick-up code (pick-up point)

Example: 893422

Min length: 6

Max length: 6

Pattern: \d{6}

skip_confirmation

Type: boolean

Skip SMS confirmation at the given point

Default value: false (confirmation required).

CallbackProperties

Parameters for notifying the client's server about the claim status change.

A notification is a POST request to the specified URL to
which information about the date of the last claim change
and claim ID in the format
'updated_ts=&claim_id=' will be added. Which means that this URL
'https://example.com/?my_order_id=123&' format will be expanded into
'https://example.com/?my_order_id=123&updated_ts=...&claim_id=...'.

Note that parameters are added by concatenation to callback_url, which means that the
URL such as 'https://example.com' will turn into this invalid format:
'https://example.comupdated_ts=...&claim_id=...'.

Only HTTP and HTTPS are supported. In the case of HTTPS, an SSL certificate must
be issued by a certification authority known to the server.

Notifications should be viewed as a push ahead of polling, a way
of speeding up information on status changes. The server expects
the 200 response, and if there are timeouts or any other response, it will attempt
to deliver the notification and then stop the attempts.
So in order to reliably obtain the claim status, the client
needs to request information using the method claims/info.

The client should note that the response of the claims/info operation may
contain an older claim state (the value of the
updated_ts field should be used as a reference). In this case, the operation
call must be repeated after some time (from 5 to 30 seconds).

Name

Description

callback_url*

Type: string

The URL used in the case of a status change for the claim.

This mechanism is deprecated, use the claims/journal operation instead.

Example: https://www.example.com/

Pattern: ^https?:.*

ClientRequirements

Customer requirements specified when creating or editing a claim

Name

Description

taxi_class*

Type: string

Delivery rate. Possible values: courier, express, cargo

Example: express

cargo_loaders

Type: integer<int64>

Number of loaders for the cargo rate.
Possible values: 0, 1, 2.

For an exact list of possible values for a particular point,
use the method for obtaining rates tariffs.

cargo_options

Type: string[]

List of additional rate options.

Possible separate options:

  • auto_courier (a courier with a vehicle only)
  • thermobag (a courier with a thermobag)

Example of a list of options: ["auto_courier"].

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Example: thermobag

cargo_type

Type: CargoType

Body type (size) for the cargo rate.
Possible values:
- van ("Small body")
- lcv_m ("Medium body")
- lcv_l ("Large body").

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Example: lcv_m

Enum: van, lcv_m, lcv_l, lcv_xl

pro_courier

Type: boolean

Enable the "Pro" option for "Express" and "Courier" rates.
In this case, we will look only for experienced couriers.

ContactWithPhone

Information about the contact person with a phone number

Name

Description

name*

Type: string

Name of the contact person

Example: Rick

phone*

Type: string

Phone number of the contact person

Example: +97142772222

Max length: 30

Pattern: [0-9 \\(\\)\\-\\+]+

phone_additional_code

Type: string

Extension number to call the courier

Example: 602 17 500

SameDayData

Additional information for "Same-day delivery" claims

Name

Description

delivery_interval*

Type: object

Parcel pick-up and delivery interval

ItemFiscalization

Fiscalization information (valid for payment upon receipt)

Name

Description

article

Type: string

Item SKU.
Must be unique for items delivered from one point.

Example: 20ML50OWKY4FC86

excise

Type: string

Amount of excise tax

Example: 12.50

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

item_type

Type: ItemType

Name type: product or service.
Default value: product

Enum: product, service

mark

Type: ItemMark

Unique item code (control identification sign). Valid for Russia.
If items have a unique code, a separate block must be created for each of them

supplier_inn

Type: string

Supplier's ITN (10 or 12 digits). Fill in the field for orders with buyout and CoD options. If there is no ITN, specify the default value: 1234567890

Example: 3664069397

Pattern: ^(\d{10}<code>&#124;</code>\d{12})$

vat_code_str

Type: string

VAT rate. Possible values:
vat_none ā€” without VAT.
vat0 ā€” 0% VAT (applied in rare cases).
vat10 ā€” 10% VAT.
vat20 ā€” 20% VAT.

Example: vat_none

CargoItemSizes

Unit dimensions in meters. The actual values should be added to the fields.

If the dimensions aren't added, the order is placed, taking into account
the maximum dimensions allowed for the selected rate.

If the actual characteristics of the unit exceed the allowed dimensions,
the courier has the right to refuse to fulfill the order on site.
In this case, the minimum fee will be withheld.

Courier: up to 0.80 m Ɨ 0.50 m Ɨ 0.50 Š¼
Express: up to 1.00 m Ɨ 0.60 m Ɨ 0.50 m
Cargo:

  • Small body: up to 1.70 m Ɨ 0.96 m Ɨ 0.90 m
  • Medium body: up to 2.60 m Ɨ 1.30 m Ɨ 1.50 m
  • Large body: up to 3.80 m Ɨ 1.80 m Ɨ 1.80 m

Name

Description

height*

Type: number

Height in meters

Example: 0.3

length*

Type: number

Length in meters

Example: 0.1

width*

Type: number

Width in meters

Example: 0.2

CargoPointAddress

Point address

Name

Description

fullname*

Type: string

Full address with an indication of the city, street, and house number.
You don't need to specify the flat, the entrance number, or the floor.

Example: One Central Building 5, Trade Center Second, Dubai

building

Type: string

Building

Example: building number

building_name

Type: string

Apartment building name

Example: Dubai

city

Type: string

City

Example: Dubai

comment

Type: string

Comment for the courier.

For the dispatch point, use the template: "Delivery from store <>. Inform the manager that the order is for Yango Delivery. Provide your order number <> and collect the parcel. The order was paid using cashless payment. So, there's no need to ask the recipient to pay for the delivery when handing over the order."

For delivery points, leave the recipient's wishes in the comments. For example, "the intercom doesn't work" / "the gate is closed, call 10 minutes in advance" / "don't call, the baby is asleep".

Example: The intercom doesn't work

Max length: 7000

coordinates

Type: number[]

Coordinates of points in the form of an array of two real numbers: longitude and latitude ā€” exactly in that order.
Rounded coordinate values are specified.

Max items: 2

Min items: 2

country

Type: string

Country

Example: UAE

description

Type: string

A geographic area that turns a short address into a global match

Example: Yango Dubai Office, One Central Building 5, Trade Center Second, Dubai

door_code

Type: string

Intercom code

Example: 169

door_code_extra

Type: string

Additional instructions for intercoms

Example: courtyard entrance code #1234, apartment code #4321

doorbell_name

Type: string

Name on the doorbell

Example: Magidovich

porch

Type: string

Entrance (may be A)

Example: A

sflat

Type: string

Flat

Example: 1

sfloor

Type: string

Floor

Example: 1

shortname

Type: string

Short address within the city (like on a Taximeter)

Example: One Central Building 5, Trade Center Second

street

Type: string

Street

Example: Trade Center Second

uri

Type: string

URI of the geo object on maps

Example: ymapsbm1://geo?ll=38.805%2C55.084

ContactOnPoint

Information about the contact person

Name

Description

name*

Type: string

Name of the contact person

Example: Bryan Burns

phone*

Type: string

Phone number of the contact person

Example: +97142774444

Max length: 30

Pattern: [0-9 \\(\\)\\-\\+]+

email

Type: string

Email is a mandatory parameter for source and return points

Example: customer-BryanBurns@yango.com

Max length: 320

Pattern: \S+@\S+.\S+

phone_additional_code

Type: string

Extension number to call the courier

Example: 602 17 500

PointType

Point type:

  • source: the point of departure where the courier picks up the item
  • destination: destination points where the courier delivers the items
  • return: item return point (added automatically and matches the point of departure by default, but a different point can also be selected)

Type

Description

PointType

Example: source

Enum: source, destination, return

RequestBuyout

Information on item buyout by the courier at the point of departure (relevant if payment upon receipt is enabled for all destination points on the route).

Name

Description

payment_method*

Type: PaymentMethod

Only cash can be used at the moment

Enum: card, cash

ExternalOrderCost

Cost of the external order linked to the point

Name

Description

currency*

Type: string

Currency

Example: AED

currency_sign*

Type: string

Currency symbol

Example: currency sign (if exists)

value*

Type: string

Cost

Example: 100.0

RequestPaymentOnDelivery

Information about payment upon receipt (relevant for payment upon receipt)

Name

Description

payment_method*

Type: PaymentMethod

Selected payment method.
card ā€” payment by card.
cash ā€” cash payment (not yet available).

Enum: card, cash

customer

Type: RequestCustomerFiscalization

Information about the recipient

CargoType

Body type (size) for the cargo rate.
Possible values:
- van ("Small body")
- lcv_m ("Medium body")
- lcv_l ("Large body").

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Type

Description

CargoType

Example: lcv_m

Enum: van, lcv_m, lcv_l, lcv_xl

ItemType

Name type: product or service.
Default value: product

Type

Description

ItemType

Enum: product, service

ItemMark

Unique item code (control identification sign). Valid for Russia.
If items have a unique code, a separate block must be created for each of them

Name

Description

code*

Type: string

Unit marking code in accordance with the format ''kind''

Example: 444D00000000003741

kind*

Type: string

Marking type.
Possible values:

  1. compiled ā€” disassembled stamp with dedicated GTIN and Serial.
    Example:
    - 444D00000000003741
  2. gs1_data_matrix_base64 ā€” unit code in GS1 Data Matrix format
    subject to marking using identification.
    Maximum 200 characters.
    The unit code must be entered in full
    by encoding the string in base64 format.

Example: gs1_data_matrix_base64

PaymentMethod

Selected payment method.
card ā€” payment by card.
cash ā€” cash payment (not yet available).

Type

Description

PaymentMethod

Enum: card, cash

RequestCustomerFiscalization

Information about the recipient

Name

Description

email

Type: string

User's email address in customer-BryanBurns@yango.com format.
If not specified, the recipient's email address from the destination point will be used

Example: customer-BryanBurns@yango.com

Max length: 320

Pattern: \S+@\S+.\S+

inn

Type: string

User's ITN (10 or 12 digits)

Example: 3664069397

Pattern: ^(\d{10}<code>&#124;</code>\d{12})$

phone

Type: string

User's phone number in +X XXX XXX XX XX format. If not specified, the recipient's phone number from the destination point will be used

Example: +97142774444

Max length: 30

Pattern: [0-9 \\(\\)\\-\\+]+

Responses

200 OK

Ok, claim created

Body

application/json
{
    "id": "741cedf82cd464fa6fa16d87155c636",
    "corp_client_id": "cd8cc018bde34597932855e3cfdce927",
    "items": [
        {
            "extra_id": "BP-208",
            "pickup_point": 1,
            "droppof_point": 2,
            "title": "Plumbus",
            "size": {
                "length": 0.1,
                "width": 0.2,
                "height": 0.3
            },
            "weight": 2,
            "cost_value": "2.00",
            "cost_currency": "AED",
            "quantity": 1,
            "fiscalization": {
                "excise": "12.50",
                "vat_code_str": "vat_none",
                "supplier_inn": 3664069397,
                "article": "20ML50OWKY4FC86",
                "mark": {
                    "kind": "gs1_data_matrix_base64",
                    "code": "444D00000000003741"
                },
                "item_type": "product"
            }
        }
    ],
    "route_points": [
        {
            "id": 1,
            "contact": {
                "name": "Bryan Burns",
                "phone": "+97142774444",
                "phone_additional_code": "602 17 500",
                "email": "customer-BryanBurns@yango.com"
            },
            "address": {
                "fullname": "One Central Building 5, Trade Center Second, Dubai",
                "shortname": "One Central Building 5, Trade Center Second",
                "coordinates": [
                    0
                ],
                "country": "UAE",
                "city": "Dubai",
                "building_name": "Dubai",
                "street": "Trade Center Second",
                "building": "building number",
                "porch": "A",
                "sfloor": "1",
                "sflat": "1",
                "door_code": "169",
                "door_code_extra": "courtyard entrance code #1234, apartment code #4321",
                "doorbell_name": "Magidovich",
                "comment": "The intercom doesn't work",
                "uri": "ymapsbm1://geo?ll=38.805%2C55.084",
                "description": "Yango Dubai Office, One Central Building 5, Trade Center Second, Dubai"
            },
            "type": "source",
            "visit_order": 1,
            "visit_status": "pending",
            "skip_confirmation": false,
            "leave_under_door": false,
            "meet_outside": false,
            "no_door_call": false,
            "payment_on_delivery": {
                "payment_ref_id": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
                "client_order_id": "100",
                "is_paid": false,
                "customer": {
                    "full_name": "Morty",
                    "inn": 3664069397,
                    "email": "customer-BryanBurns@yango.com",
                    "phone": "+97142774444"
                },
                "payment_method": "card",
                "invoice_link": "url"
            },
            "external_order_id": "100",
            "external_order_cost": {
                "value": "100.0",
                "currency": "AED",
                "currency_sign": "currency sign (if exists)"
            },
            "expected_visit_interval": {
                "from": "2020-01-01T00:00:00+00:00",
                "to": "2020-01-02T00:00:00+00:00"
            },
            "pickup_code": "893422",
            "return_reasons": [
                "string"
            ],
            "return_comment": "string",
            "visited_at": {
                "expected": "2022-12-29T18:02:01Z",
                "expected_waiting_time_sec": 0,
                "actual": "2022-12-29T18:02:01Z"
            }
        }
    ],
    "current_point_id": 372036854775807,
    "status": "new",
    "version": 0,
    "user_request_revision": "string",
    "error_messages": [
        {
            "code": "some_error",
            "message": "Some error"
        }
    ],
    "emergency_contact": {
        "name": "Rick",
        "phone": "+97142772222",
        "phone_additional_code": "602 17 500"
    },
    "skip_door_to_door": false,
    "skip_client_notify": false,
    "skip_emergency_notify": false,
    "skip_act": false,
    "optional_return": false,
    "eta": 10,
    "created_ts": "2020-01-01T00:00:00+00:00",
    "updated_ts": "2020-01-01T00:00:00+00:00",
    "pricing": {
        "offer": {
            "offer_id": "28ae5f1d72364468be3f5e26cd6a66bf",
            "price": "12.50",
            "valid_until": "2020-01-01T00:00:00+00:00",
            "price_with_vat": "12.50"
        },
        "currency": "AED",
        "currency_rules": {
            "code": "AED",
            "text": "AED",
            "template": "$VALUE$ $SIGN$$CURRENCY$",
            "sign": "ā‚½"
        },
        "final_pricing_calc_id": "string",
        "final_price": "12.50"
    },
    "client_requirements": {
        "taxi_class": "express",
        "cargo_type": "lcv_m",
        "cargo_loaders": 0,
        "cargo_options": [
            "thermobag"
        ],
        "pro_courier": false
    },
    "matched_cars": [
        {
            "taxi_class": "express",
            "client_taxi_class": "cargo",
            "cargo_type": "lcv_m",
            "cargo_type_int": "2 is equal to \"lcv_m\"",
            "cargo_loaders": 0,
            "door_to_door": false,
            "pro_courier": false
        }
    ],
    "warnings": [
        {
            "source": "client_requirements",
            "code": "not_fit_in_car",
            "message": "warning"
        }
    ],
    "performer_info": {
        "courier_name": "Mark Smith",
        "legal_name": "Individual entrepreneur Mark Smith",
        "car_model": "Hyundai Solaris",
        "car_number": "71673",
        "car_color": "red",
        "car_color_hex": "FF00000",
        "transport_type": "car"
    },
    "callback_properties": {
        "callback_url": "https://www.example.com/"
    },
    "due": "2020-01-01T00:00:00+00:00",
    "shipping_document": "string",
    "comment": "Restaurant",
    "revision": 1,
    "route_id": "string",
    "same_day_data": {
        "delivery_interval": {
            "from": "2020-01-01T07:00:00+00:00",
            "to": "2020-01-01T07:00:00+00:00"
        }
    }
}

Name

Description

created_ts*

Type: string<date-time>

Date and time of claim creation

Example: 2020-01-01T00:00:00+00:00

id*

Type: string

Claim ID obtained at the claim creation stage

Example: 741cedf82cd464fa6fa16d87155c636

Min length: 32

Max length: 64

items*

Type: V2CargoItem[]

Item parameters

Min items: 1

revision*

Type: integer<int64>

Revision (int64)

Example: 1

route_points*

Type: V2ResponseCargoPoint[]

Route point information
Route point information

Min items: 2

status*

Type: ClaimStatus

Claim status. To learn more, see Status model

Example: new

Enum: new, estimating, estimating_failed, ready_for_approval, accepted, performer_lookup, performer_draft, performer_found, performer_not_found, pickup_arrived, ready_for_pickup_confirmation, pickuped, delivery_arrived, ready_for_delivery_confirmation, delivered, delivered_finish, returning, return_arrived, ready_for_return_confirmation, returned, returned_finish, failed, cancelled, cancelled_with_payment, cancelled_by_taxi, cancelled_with_items_on_hands

updated_ts*

Type: string<date-time>

Date and time of the last claim update

Example: 2020-01-01T00:00:00+00:00

user_request_revision*

Type: string

The current version of changes in the claim entered by the user

version*

Type: integer<int64>

Version (int64)

callback_properties

Type: CallbackProperties

Parameters for notifying the client's server about the claim status change.

A notification is a POST request to the specified URL to
which information about the date of the last claim change
and claim ID in the format
'updated_ts=&claim_id=' will be added. Which means that this URL
'https://example.com/?my_order_id=123&' format will be expanded into
'https://example.com/?my_order_id=123&updated_ts=...&claim_id=...'.

Note that parameters are added by concatenation to callback_url, which means that the
URL such as 'https://example.com' will turn into this invalid format:
'https://example.comupdated_ts=...&claim_id=...'.

Only HTTP and HTTPS are supported. In the case of HTTPS, an SSL certificate must
be issued by a certification authority known to the server.

Notifications should be viewed as a push ahead of polling, a way
of speeding up information on status changes. The server expects
the 200 response, and if there are timeouts or any other response, it will attempt
to deliver the notification and then stop the attempts.
So in order to reliably obtain the claim status, the client
needs to request information using the method claims/info.

The client should note that the response of the claims/info operation may
contain an older claim state (the value of the
updated_ts field should be used as a reference). In this case, the operation
call must be repeated after some time (from 5 to 30 seconds).

client_requirements

Type: ClientRequirements

Customer requirements specified when creating or editing a claim

comment

Type: string

General comment to the order

Example: Restaurant

Max length: 7000

corp_client_id

Type: string

Yango Delivery corporate client ID (from the OAuth token)

Example: cd8cc018bde34597932855e3cfdce927

Min length: 32

Max length: 32

current_point_id

Type: integer<int64>

Integer point ID (int64) generated
on the Yango Delivery side.
It is in the route_points[].id field. Applicable to
source, destination, and return points.

Example: 372036854775807

due

Type: string<date-time>

Estimated time of arrival of the courier.
If this parameter isn't specified, we will look for a courier as soon as possible.

Example: 2020-01-01T00:00:00+00:00

emergency_contact

Type: ContactWithPhone

Information about the contact person with a phone number

error_messages

Type: HumanErrorMessage[]

List of error messages
Error code and description

eta

Type: integer<int64>

Estimated order fulfillment time in minutes (int64)

Example: 10

matched_cars

Type: MatchedCar[]

Information about the selected rate

optional_return

Type: boolean

Disable item return in case of order cancellation.

Possible values:

  • true (the courier keeps the item)
  • false (by default, the item must be returned)

performer_info

Type: PerformerInfo

Information about the executor

pricing

Type: ClaimPricing

Information about the order cost

route_id

Type: string

ID of the route within which the order is delivered
If multiple orders are delivered by one courier,
all of them will have the same route_id
(Relevant only for the "Same-day delivery")

same_day_data

Type: SameDayData

Additional information for "Same-day delivery" claims

shipping_document

Type: string

Shipping documents

skip_act

Type: boolean

Don't show an acceptance certificate

skip_client_notify

Type: boolean

Don't send SMS notifications to the sender/recipient
when a courier is on their way.

Default value: false (send notifications)

skip_door_to_door

Type: boolean

Disable door-to-door delivery (disable the "Door-to-door" option).

Possible values:

  • true (the courier will deliver the order only at the entrance outside)
  • false (the courier will deliver the order to the door) - default value

skip_emergency_notify

Type: boolean

Don't send a notification to the emergency contact person

Default value: false (send notifications)

warnings

Type: ClaimWarning[]

Warnings during claim processing

V2ResponseCargoPoint

Route point information

Name

Description

address*

Type: CargoPointAddress

Point address

contact*

Type: ContactOnPoint

Information about the contact person

id*

Type: integer<int64>

Integer point ID (int64)

Example: 1

type*

Type: PointType

Point type:

  • source: the point of departure where the courier picks up the item
  • destination: destination points where the courier delivers the items
  • return: item return point (added automatically and matches the point of departure by default, but a different point can also be selected)

Example: source

Enum: source, destination, return

visit_order*

Type: integer<int64>

The order in which the points are visited (numbering starts with 1) (int64)

Example: 1

visit_status*

Type: PointVisitStatus

Point visit status:

  • pending ā€” not yet visited.
  • arrived ā€” the courier arrived at the point.
  • visited ā€” the courier handed over/picked up the cargo at the point.
  • skipped ā€” skipped (if the item wasn't accepted).

Example: pending

Enum: pending, arrived, visited, skipped

visited_at*

Type: PointVisitTime

Information about the point visit time

expected_visit_interval

Type: ExpectedVisitInterval

Time interval of the courier's visit to the point according to the selected offer

external_order_cost

Type: ExternalOrderCost

Cost of the external order linked to the point

external_order_id

Type: string

Order number from the customer's system.
Entered for destination points

Example: 100

leave_under_door

Type: boolean

Leave the parcel at the door

meet_outside

Type: boolean

The courier will be met outside, at the entrance

no_door_call

Type: boolean

Don't ring the doorbell

payment_on_delivery

Type: ResponsePaymentOnDelivery

Parameters of payment upon receipt

pickup_code

Type: string

Parcel pick-up code.
The courier needs to enter this code to confirm that they have picked up the parcel.
This requires your employees to be at the point of dispatch to provide this code to the courier.
Relevant for source points.
Code format: 6 digits
|
Item pick-up code (pick-up point)

Example: 893422

Min length: 6

Max length: 6

Pattern: \d{6}

return_comment

Type: string

Comments on the reasons for returning the cargo

return_reasons

Type: string[]

Reasons for returning the cargo

skip_confirmation

Type: boolean

Skip SMS confirmation at the given point

Default value: false (confirmation required).

ClaimStatus

Claim status. To learn more, see Status model

Type

Description

ClaimStatus

Example: new

Enum: new, estimating, estimating_failed, ready_for_approval, accepted, performer_lookup, performer_draft, performer_found, performer_not_found, pickup_arrived, ready_for_pickup_confirmation, pickuped, delivery_arrived, ready_for_delivery_confirmation, delivered, delivered_finish, returning, return_arrived, ready_for_return_confirmation, returned, returned_finish, failed, cancelled, cancelled_with_payment, cancelled_by_taxi, cancelled_with_items_on_hands

HumanErrorMessage

Error code and description

Name

Description

code*

Type: string

Error code

Example: some_error

message*

Type: string

Error description

Example: Some error

MatchedCar

Name

Description

taxi_class*

Type: string

Delivery rate. Possible values: courier, express, cargo

Example: express

cargo_loaders

Type: integer<int64>

Required number of loaders (int64)

cargo_type

Type: string

Body type

Example: lcv_m

cargo_type_int

Type: integer<int64>

Body type (int64)

Example: 2 is equal to "lcv_m"

client_taxi_class

Type: string

Customer rate

Example: cargo

door_to_door

Type: boolean

The "door-to-door" option for the "Express" rate

pro_courier

Type: boolean

Enable the "Pro" option for "Express" and "Courier" rates.
In this case, we will look only for experienced couriers.

PerformerInfo

Information about the courier

Name

Description

courier_name*

Type: string

Name of the courier who is delivering a parcel

Example: Mark Smith

legal_name*

Type: string

Data on the legal entity that performs the delivery

Example: Individual entrepreneur Mark Smith

car_color

Type: string

Vehicle color

Example: red

car_color_hex

Type: string

RGB code of the vehicle color

Example: FF00000

car_model

Type: string

Vehicle model

Example: Hyundai Solaris

car_number

Type: string

License plate number of the vehicle

Example: 71673

transport_type

Type: string

Type of courier transport

Example: car

ClaimPricing

Information about the order cost

Name

Description

currency

Type: string

Three-digit code of the payment currency

Example: AED

currency_rules

Type: CurrencyRules

Currency display rules

final_price

Type: string

Final delivery price, including VAT.
Filled in after the delivery/return is completed.

Example: 12.50

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

final_pricing_calc_id

Type: string

Cost calculation ID

offer

Type: TaxiOffer

Offer from Yango Delivery (valid for some time).

ClaimWarning

Name

Description

code*

Type: string

Warning type:

  • not_fit_in_car: the cargo may not fit in the vehicle.
  • requirement_unavailable: the specified requirement isn't available and has been ignored.
  • address_not_found - the specified address wasn't found in maps.
  • address_too_far: the coordinates from maps the specified address are far from the transmitted coordinates.

Example: not_fit_in_car

source*

Type: string

Warning source:

  • client_requirements ā€” the warning is related to customer requirements.
  • route_points ā€” the warning is related
    to the transmitted addresses.

Example: client_requirements

message

Type: string

Warning description

Example: warning

PointVisitStatus

Point visit status:

  • pending ā€” not yet visited.
  • arrived ā€” the courier arrived at the point.
  • visited ā€” the courier handed over/picked up the cargo at the point.
  • skipped ā€” skipped (if the item wasn't accepted).

Type

Description

PointVisitStatus

Example: pending

Enum: pending, arrived, visited, skipped

PointVisitTime

Information about the point visit time

Name

Description

actual

Type: string<date-time>

Actual point visit time.
Filled in only for visited points.

expected

Type: string<date-time>

Estimated time of arrival. Can be filled in
only for unvisited points.

expected_waiting_time_sec

Type: integer<int64>

Estimated waiting time at the point. (int64)

ExpectedVisitInterval

Time interval of the courier's visit to the point according to the selected offer

Name

Description

from*

Type: string<date-time>

Interval start

Example: 2020-01-01T00:00:00+00:00

to*

Type: string<date-time>

Interval end

Example: 2020-01-02T00:00:00+00:00

ResponsePaymentOnDelivery

Parameters of payment upon receipt

Name

Description

is_paid*

Type: boolean

Order payment indication

client_order_id

Type: string

customer order's external ID

Example: 100

customer

Type: CustomerFiscalization

Information about the customer (recipient)

invoice_link

Type: string

Invoice link

Example: url

payment_method

Type: PaymentMethod

Selected payment method.
card ā€” payment by card.
cash ā€” cash payment (not yet available).

Enum: card, cash

payment_ref_id

Type: string<uuid>

Payment ID

CurrencyRules

Currency display rules

Name

Description

code*

Type: string

Three-digit code of the payment currency

Example: AED

Min length: 3

Max length: 3

template*

Type: string

Currency display template

Example: $VALUE$ $SIGN$$CURRENCY$

text*

Type: string

Short currency name

Example: AED

sign

Type: string

Currency symbol

Example: ā‚½

TaxiOffer

Offer from Yango Delivery (valid for some time).

Name

Description

offer_id*

Type: string

Offer ID

Example: 28ae5f1d72364468be3f5e26cd6a66bf

price*

Type: string

Offer price without VAT

Example: 12.50

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

price_with_vat

Type: string

Delivery cost in Decimal(18, 4) format

Example: 12.50

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

valid_until

Type: string<date-time>

Time until which the offer to accept the claim is valid. If there is no value, there are no limits on the offer duration

Example: 2020-01-01T00:00:00+00:00

CustomerFiscalization

Information about the customer (recipient)

Name

Description

email

Type: string

User's email address. If not specified, the recipient's email address from the destination point will be used

Example: customer-BryanBurns@yango.com

full_name

Type: string

For legal entities ā€” organization name, for individual entrepreneurs and individuals ā€” full name

Example: Morty

inn

Type: string

User's ITN (10 or 12 digits)

Example: 3664069397

Pattern: ^(\d{10}<code>&#124;</code>\d{12})$

phone

Type: string

User's phone number in +X XXX XXX XX XX format. If not specified, the recipient's phone number from the destination point will be used

Example: +97142774444

400 Bad Request

Invalid request

Body

application/json
{
    "code": "bad_request",
    "message": "Incorrect request body"
}

Name

Description

code*

Type: string

Error code

Example: bad_request

Enum: validation_error, sdd_items_without_parameters_forbidden, items_without_parameters_forbidden, sdd_multipoints_not_supported, address_too_far, address_not_found, bad_request, invalid_post_payment, sdd_client_requirements_forbidden, invalid_delivery_interval, wrong_pickup_code_format, wrong_pickup_code_usage, unknown_zone, invalid_time_intervals, unsupported_points_count, invalid_phone_incorrect_symbol, invalid_phone_must_start_plus_symbol, country_phone_code_not_supported, invalid_phone_size_incorrect, item_destination_point_not_found, invalid_destination_point, due_in_past, delay_too_long, external_order_id_not_allowed, address_outside_delivery_zone, invalid_buyout_point_type, payment_on_delivery_missed, payment_on_delivery_invalid_request, max_order_cost_exceeded, invalid_post_payment_payment_method, invalid_buyout_payment_method, invalid_source_point, invalid_point_phone, invalid_item_destination_point, invalid_item_source_point, different_cost_currencies

message*

Type: string

The person understood the error message

Example: Incorrect request body

403 Forbidden

Identification error or payment on receipt isn't available

Body

application/json
{
    "code": "payment_on_delivery_disabled",
    "message": "Incorrect request body"
}

Name

Description

code*

Type: string

Error code

Example: payment_on_delivery_disabled

Enum: buyout_disabled, payment_on_delivery_disabled, forbidden_by_antifake

message*

Type: string

The person understood the error message

Example: Incorrect request body

429 Too Many Requests

Too many claims created in a period of time

Body

application/json
{
    "code": "too_many_requests",
    "message": "Too many requests"
}

Name

Description

code*

Type: string

Error code

Example: too_many_requests

Enum: too_many_requests

message*

Type: string

Error description

Example: Too many requests