Yandex.Delivery API Integration: Cost Calculation to Tracking
After placing an order, the customer receives no SMS about delivery status, the tracking number is missing, and the courier arrives without notice. This is a familiar scenario for many online stores. Integrating a delivery service is not just "adding a button". It involves linking several APIs, synchronizing statuses, handling errors, caching, and webhooks. We implemented such integration for an apparel online store—here's how it works and what's important to consider. With improper setup, the store loses money: customers leave due to uninformative statuses, and logistics costs rise. The Yandex.Delivery API can automate cost calculation, claim creation, and real-time tracking.
Problem: Why Simple Integration Doesn't Work
Yandex.Delivery API is a powerful REST tool, but without proper architecture it becomes a source of errors. Typical problems:
- Incorrect coordinates. The store sends an address as text, but the API requires [lng, lat]. The geocoder is not always accurate—a 100-meter difference leads to rejection.
- Dimensions and weight. If the product behaves non-standardly (e.g., a bag with variable dimensions), cost calculation fails.
- Timeouts. Yandex.Delivery API takes up to 10 seconds to respond—if calculations are not cached, the checkout page hangs.
- Statuses not arriving. Webhooks are misconfigured—the buyer sees "waiting for courier" a day after delivery.
How We Implemented It: Stack and Configuration
We use Laravel 11 with Redis queues for asynchronous requests. The HTTP client is Guzzle with retries (3 attempts with delay). Cost calculations are cached for 20 minutes in Memcached.
Example request to create a claim:
POST /b2b/cargo/integration/v2/claims/create { "items": [{ "quantity": 1, "size": {"length": 0.3, "width": 0.2, "height": 0.1}, "weight": 1.5, "cost_value": "1500", "cost_currency": "RUB" }], "route_points": [ { "address": {"fullname": "Moscow, ul. Skladskaya, 1"}, "contact": {"name": "Ivan", "phone": "+79001234567"}, "point_id": 1, "type": "source", "pick_up_time": { "from": "2023-03-15T10:00:00+03:00", "to": "2023-03-15T12:00:00+03:00" } }, { "address": {"fullname": "Moscow, ul. Pokupatelskaya, 5, apt. 10"}, "contact": {"name": "Maria", "phone": "+79007654321"}, "point_id": 2, "type": "destination" } ] } The response returns the claim ID and a details link. Then webhooks come into play: we create routes that accept POST notifications from Yandex.Delivery and update the order status in our database.
How Status Synchronization Works
Webhooks are the only reliable way to receive statuses in real time. After each status change, Yandex sends a POST request to our endpoint with a JSON body. We process it, update the database record, and send a notification to the customer (SMS, email, or push). If a webhook doesn't arrive, we poll the API every 5 minutes. This hybrid approach achieves 99.9% accuracy.
Why Caching Calculations Matters
The Yandex.Delivery API has a limit of 100 requests per minute. Without caching, every cart view generates a request—during peak sales, the store quickly hits the limit. We cache the cost for 20 minutes: this reduces load by 95% and speeds up page response by 300 ms. The customer doesn't wait, and purchases don't fail.
Comparison: Why API is Better Than Custom Module
| Criterion | API Integration | Custom Module |
|---|---|---|
| Implementation speed | 3–10 days | 2–3 weeks |
| Status support | 15 statuses + webhooks | Only basic |
| Error handling | Built-in caching | Requires implementation |
| Scalability | Cloud infrastructure | Server rental |
Implementation time via API is 3–5 times lower, and error count is 40% less (by our measurements). Clients save up to 30% on logistics costs due to tariff optimization. Contact us to evaluate your integration.
Work Process: From Analysis to Deployment
- Analysis—understand business logic: which statuses to display, when to charge, how to handle returns.
- Design—architect the system: request sequence, caching, webhook scheme.
- Implementation—write code: controllers, services, tests. Use Repository pattern for API abstraction.
- Testing—test on staging: create claims, cancel them, verify webhooks via ngrok.
- Deployment—deploy to production, configure monitoring (logs, Telegram alerts).
Typical Integration Mistakes
- Improper CORS handling—browser blocks requests to Yandex.Delivery API if no proxy server is configured.
- No retries on timeouts—order loss during peak hours.
- Ignoring API rate limits (100 requests per minute)—key blocking.
What's Included in the Work
- Documentation—endpoint descriptions, data schema, instructions for adding new tariffs.
- Access—API key setup, webhook configuration, security policies.
- Code—repository with the integration (Laravel, Node.js, or other stack by agreement).
- Support—free support for 1 month after launch (consultations, fixes).
Estimated Timelines
| Stage | Duration |
|---|---|
| Basic integration (cost + claim + tracking) | 3–4 business days |
| Full integration (webhooks + map + auto-cancel) | 1–1.5 weeks |
| Expansion (multiple warehouses, returns) | from 2 weeks |
Integration cost is calculated individually.
How We Guarantee Quality
We have 5 years of experience with logistics API integrations and 30+ successful projects with Yandex.Delivery, CDEK, Boxberry. We test every scenario: from cost calculation to driver order cancellation. We guarantee data security and 24/7 operation.
We are ready to discuss your project. Contact us—we'll assess the complexity and offer the optimal solution. Request a consultation to evaluate your project.