Special considerations and limitations

  1. API request policy
  2. API limitations
  3. Order changes
  4. Phone number format
  5. Order for loading data
  6. Recommended method for loading data
  7. Data storage period

API request policy

  • The API response timeout is 60 seconds.
  • A single batch request can contain up to one thousand objects. If you need to send more data, divide it into several requests.
  • In rare cases (less than 1% of requests), the Track & Trace API returns a 504 Gateway Timeout error. If you receive this error, try sending repeat requests with progressively longer delays. For more information, see Service errors.

API limitations

  • The accuracy of order address geocoding is not checked. The address in text format (set with the address parameter) and the order coordinates (set with the lat and lon parameters) must match each other.

    Geographic coordinates are used to set the route. If the geolocation is not very accurate, the app may bring the courier to the wrong location instead of the one specified in text in the app. A common error is an address is given up to a house number but the coordinates location to the middle of the street.

  • Cascade deletion of entities is not supported. You don't have to delete unnecessary entities with dependencies on other entities, because they don't interfere with anything.

Order changes

  • When you move a canceled order to another day, assign it the new status. Otherwise, the order gets added to the route on another day with the cancelled status.
  • When changing an order, only update the changed attributes. Otherwise, the data received from the courier will be overwritten. For example, the courier already delivered the order, but the system re-assigned the new status to the order when updating another field.
  • After uploading orders, check them using the verification resource. This ensures that there are no errors. Otherwise, the courier might not receive part of the orders. This verification must be performed daily and offline before the first courier departs.
  • The route_number value must be unique while using the API.
  • Number and integer fields should be sent without quotation marks, while string fields should be sent in quotation marks. String fields must be UTF-8 encoded.

Phone number format

  • Phone numbers must be given in the format supported by the mobile employee terminal. For example, some terminals don't support phone numbers that start with 7. The app can't be used to make calls to this phone number. We recommend phone numbers starting with +7 or 8.

Order for loading data

We recommend loading data in the following order:

  1. Depots.
  2. Couriers.
  3. Routes.
  4. Orders.

A different order may cause errors when accessing objects that haven't been loaded yet.

Recommended method for loading data

To upload and update your data, use batch requests that load data arrays: depots-batch, couriers-batch, routes-batch, orders-batch.

Each uploaded object is assigned:

  • A unique number used in requests to the Track & Trace API. Written in fields with the _id postfix, such as depot_id.
  • Unique number that matches the number in the delivery company's database. Written in fields with the _number postfix, such as depot_number.

Batch loading also updates existing data.

Note.

Each call is an ACID transaction. If an error calling the batch resource occurs, it cancels all the changes made to the call.

To minimize losses, split the data into several packages. In this case, only the changes in the package with the error will be lost.

Data storage period

Yandex servers store data for a limited time:

  • Courier tracks: 3 months from the date of the route.
  • Courier delivery confirmation photos: 3 months from the date of the photo upload.
  • Monitoring data (orders, routes): 1 year after the end of the paid period or testing period.

Once the storage period expires, the data can be permanently deleted.

Contact support