Колбеки

Автоматические уведомления о изменении статуса заказов через HTTP колбеки.

Обзор

Колбеки позволяют получать уведомления о статусе заказов в реальном времени без необходимости периодически опрашивать API.

Получение информации о настройках колбеков

Для получения информации о текущих настройках колбеков используйте эндпоинт получения информации о складе:

cURL

curl -X GET "https://api.razvezu.pro/integration/v2/depots/14" \
  -H "X-API-Key: ваш_api_ключ"

JavaScript

const response = await fetch('https://api.razvezu.pro/integration/v2/depots/14', {
  headers: {
    'X-API-Key': 'ваш_api_ключ'
  }
});

const data = await response.json();
console.log('URL колбека:', data.result.callbacks_url);

Python

import requests

headers = {
    'X-API-Key': 'ваш_api_ключ'
}

response = requests.get(
    'https://api.razvezu.pro/integration/v2/depots/14',
    headers=headers
)

data = response.json()
print('URL колбека:', data['result']['callbacks_url'])

В ответе будет поле callbacks_url, которое содержит текущий URL для колбеков или null, если колбеки не настроены.

Настройка колбеков

Для настройки колбеков укажите callbacks_url в настройках склада. Этот URL будет использоваться для отправки уведомлений о всех заказах данного склада.

Сценарии отправки

Колбеки отправляются в следующих случаях:

1. После успешной доставки — когда заказ получает статус finished
2. При отмене заказа — когда заказ получает статус cancelled
3. Повторная отправка — в некоторых случаях возможна повторная отправка колбека для одного заказа

Внимание

Для одного и того же заказа возможна повторная отправка колбека. Например, если клиент сначала отказался от доставки, но впоследствии заказ всё же был доставлен.

Структура колбека

Колбек отправляется методом POST на указанный URL.

Запрос

POST {your_url}
Content-Type: application/json

Тело запроса:

{
  "order_id": "ORDER-123",
  "status": "finished",
  "number": "ORDER-123",
  "route_id": "J8nJ",
  "date": "10.08.2023",
  "delivery_time": "11:23",
  "confirmation_methods": "client_system",
  "reason_cancellation": null,
  "message": null,
  "custom_props": {
    "code": "1234"
  }
}

Параметры

Поле	Тип	Описание
order_id	string	Идентификатор заказа
status	string	Статус заказа: finished или cancelled
number	string	Номер заказа
route_id	string	Идентификатор маршрута
date	string	Дата доставки в формате d.m.Y
delivery_time	string	Фактическое время доставки в формате H:i
confirmation_methods	string | null	Способ подтверждения доставки
reason_cancellation	string | null	Причина отмены (только для cancelled)
message	string | null	Служебное сообщение по заказу
custom_props	object | null	Данные для подтверждения в вашей системе

Статусы

Статус	Описание
finished	Заказ успешно завершён
cancelled	Заказ отменён

Способы подтверждения

Метод	Описание
code	SMS-код через сервис Развезу
sign	Подпись клиента
client_system	Подтверждение через вашу систему (например, QR)
client_code	Подтверждение 4‑значным кодом вашей системы
trusted_people	Передача доверенному лицу

Примеры колбеков

Успешная доставка

{
  "order_id": "ORDER-123",
  "status": "finished",
  "number": "ORDER-123",
  "route_id": "J8nJ",
  "date": "10.08.2023",
  "delivery_time": "11:23",
  "confirmation_methods": "client_system",
  "custom_props": {
    "code": "1234"
  }
}

Отменённый заказ

{
  "order_id": "ORDER-456",
  "status": "cancelled",
  "number": "ORDER-456",
  "route_id": "K9mK",
  "date": "10.08.2023",
  "delivery_time": "14:00",
  "reason_cancellation": "Указан неверный адрес",
  "message": "У клиента другой адрес, а именно Донская 2/11. Заезды с разных дорог"
}

Обработка колбеков

Обязательное подтверждение

Если для заказа установлено:

• need_confirmation = true
• confirmation_methods = client_system или client_code

То заказ обязательно будет подтверждаться через вашу систему. В custom_props передаются данные для подтверждения:

• Для QR-кода: данные в формате JSON
• Для кода: 4-значный код в поле code

Важно

Если данные в custom_props не в формате JSON (для QR), обязательное подтверждение будет проигнорировано.

Необязательное подтверждение

Если need_confirmation = false, но указаны confirmation_methods, заказ может быть подтверждён любым перечисленным способом, включая стандартное подтверждение.

Пример обработчика

Node.js/Express

const express = require('express');
const app = express();

app.use(express.json());

app.post('/api/razvezu/callback', (req, res) => {
  const { order_id, status, number, delivery_time, reason_cancellation } = req.body;
  
  console.log(`Заказ ${number}: ${status}`);
  
  if (status === 'finished') {
    // Обработка успешной доставки
    console.log(`Доставлен в ${delivery_time}`);
    // Обновите статус в вашей системе
  } else if (status === 'cancelled') {
    // Обработка отмены
    console.log(`Отменён: ${reason_cancellation}`);
    // Обновите статус в вашей системе
  }
  
  // Всегда возвращайте 200 для успешной обработки
  res.status(200).json({ ok: true });
});

app.listen(3000);

Python/Flask

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/razvezu/callback', methods=['POST'])
def handle_callback():
    data = request.json
    order_id = data.get('order_id')
    status = data.get('status')
    number = data.get('number')
    delivery_time = data.get('delivery_time')
    reason_cancellation = data.get('reason_cancellation')
    
    print(f'Заказ {number}: {status}')
    
    if status == 'finished':
        # Обработка успешной доставки
        print(f'Доставлен в {delivery_time}')
        # Обновите статус в вашей системе
    elif status == 'cancelled':
        # Обработка отмены
        print(f'Отменён: {reason_cancellation}')
        # Обновите статус в вашей системе
    
    # Всегда возвращайте 200 для успешной обработки
    return jsonify({'ok': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

PHP

<?php
header('Content-Type: application/json');

$data = json_decode(file_get_contents('php://input'), true);

$order_id = $data['order_id'];
$status = $data['status'];
$number = $data['number'];
$delivery_time = $data['delivery_time'] ?? null;
$reason_cancellation = $data['reason_cancellation'] ?? null;

error_log("Заказ {$number}: {$status}");

if ($status === 'finished') {
    // Обработка успешной доставки
    error_log("Доставлен в {$delivery_time}");
    // Обновите статус в вашей системе
} elseif ($status === 'cancelled') {
    // Обработка отмены
    error_log("Отменён: {$reason_cancellation}");
    // Обновите статус в вашей системе
}

// Всегда возвращайте 200 для успешной обработки
http_response_code(200);
echo json_encode(['ok' => true]);
?>

Требования к обработчику

1. HTTP статус 200 — ваш сервер должен возвращать статус 200 OK для успешной обработки
2. Таймаут — обработка должна выполняться быстро (рекомендуется < 5 секунд)
3. Идемпотентность — обработчик должен корректно обрабатывать повторные запросы
4. Логирование — рекомендуется логировать все входящие колбеки для отладки

Безопасность

Важно

• Используйте HTTPS для приёма колбеков
• Проверяйте подлинность запросов (например, через проверку IP или подписи)
• Валидируйте входящие данные
• Обрабатывайте ошибки gracefully

Тестирование

Для тестирования колбеков можно использовать инструменты вроде:

• ngrok — для создания туннеля к локальному серверу
• webhook.site — для временного URL для тестирования
• Postman — для ручной отправки тестовых запросов

Отладка

Если колбеки не приходят:

1. Проверьте, что callbacks_url правильно настроен в настройках склада
2. Убедитесь, что URL доступен извне (не localhost)
3. Проверьте логи вашего сервера на наличие запросов
4. Убедитесь, что сервер возвращает статус 200 OK
5. Обратитесь в поддержку Развезу при необходимости