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>\|</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:

compiled — disassembled stamp with dedicated GTIN and Serial.
Example:
- 444D00000000003741
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>\|</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>\|</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

Create claim

Request

Query parameters

Learn more

Headers

Body

V2CargoItem

V2CargoPoint

CallbackProperties

ClientRequirements

ContactWithPhone

SameDayData

ItemFiscalization

CargoItemSizes

CargoPointAddress

ContactOnPoint

PointType

RequestBuyout

ExternalOrderCost

RequestPaymentOnDelivery

CargoType

ItemType

ItemMark

PaymentMethod

RequestCustomerFiscalization

Responses

200 OK

Body

V2ResponseCargoPoint

ClaimStatus

HumanErrorMessage

MatchedCar

PerformerInfo

ClaimPricing

ClaimWarning

PointVisitStatus

PointVisitTime

ExpectedVisitInterval

ResponsePaymentOnDelivery

CurrencyRules

TaxiOffer

CustomerFiscalization

400 Bad Request

Body

403 Forbidden

Body

429 Too Many Requests

Body

Was the article helpful?