API логистики OD

1. С чего начать

Вы отправляете заказ с данными клиента и составом посылки, в ответ получаете Order ID — короткий код, который показываете покупателю. С этим кодом он получает посылку у курьера или в пункте выдачи.

Начинайте с тестовой: она работает так же, как боевая, включая выдачу Order ID. Переключение — только смена адреса и ключа, код менять не придётся.

2. Авторизация

Каждый запрос несёт два заголовка. Первый общий для платформы, второй — ваш личный: по нему мы понимаем, чей это заказ.

Ключ утёк — скажите нам. Мы отзовём только ваш, остальные партнёры продолжат работать. Новый выдаём в тот же день.

3. Создать отправление

Единственный обязательный вызов интеграции.

Запрос

curl -X POST \
  https://api.odsell.com/logistics/api/v1/b2b/shipments \
  -H "X-API-Key: <ключ платформы>" \
  -H "X-Partner-Token: <ваш ключ>" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerName": "Somon.tj",
    "clientName": "Фируза Азизова",
    "clientPhone": "+992900112233",
    "clientAddress": "Душанбе, Айни 12, кв. 4",
    "deliveryType": "COURIER",
    "goodsPaid": false,
    "codAmount": "250.00",
    "items": [
      { "name": "Кроссовки", "quantity": 1, "price": "200.00" },
      { "name": "Носки", "quantity": 2 }
    ]
  }'

Ответ · 201

{
  "orderId": "WGAKZT",
  "barcode": "OD0985159694",
  "status": "CREATED"
}

• orderId — покажите покупателю и продублируйте в SMS или письме. Это одновременно номер заказа и код получения: без него посылку не выдадут.
• barcode — код на коробке для нашего склада. Покупателю он не нужен.

Order ID выдаётся один раз и не меняется. Повторный запрос создаёт новое отправление с новым кодом, поэтому не отправляйте заказ дважды при таймауте — сначала уточните у нас.

4. Поля запроса

Всё, чего нет в таблицах, мы игнорируем — присылать лишнее безопасно.

Заказ

Позиция

5. Что дальше

Отправление проходит эти состояния. Порядок фиксированный — каждое следующее наступает только после предыдущего.

Если получатель отказался или не вышел на связь, отправление переходит в RETURNED с указанной причиной, а товар возвращается вам.

6. Ошибки

Формат ответа одинаковый для всех ошибок. Читайте detail.message — там человеческая формулировка, её можно показывать оператору как есть.

{
  "detail": {
    "message": "Неизвестный партнёрский токен",
    "code": "unauthorized"
  }
}

7. Правила расчётов

Три вещи, из-за которых чаще всего возникают вопросы. Лучше знать их до запуска.

Доставку считаем по факту, а не по вашему весу

Стоимость фиксируется после того, как посылку взвесили и замерили у нас. Присланный declaredWeightKg — только ориентир для склада. Берём больший из фактического и объёмного веса, как это делает любой перевозчик.

Несколько посылок одному человеку — доставка одна

Если покупатель получает сразу несколько коробок, они объединяются в партию и доставка считается один раз по суммарному весу. Отдельно за каждую коробку покупатель не платит.

Покупатель платит при получении

При goodsPaid: false курьер соберёт стоимость доставки и сумму codAmount за товар. Если товар уже оплачен у вас, укажите goodsPaid: true — тогда с покупателя возьмут только доставку.

Заказ закрывается только вручную. Статус DELIVERED ставит сотрудник после того, как пересчитал деньги. Автоматически по времени или по факту доставки он не выставляется.

8. Подключение

Порядок такой же, как у любого перевозчика, только быстрее.

За ключами и списком пунктов выдачи — к вашему менеджеру OD.