# СДЭК API v2: Показать пункты выдачи в городе покупателя

Сценарий из mcp-everything. Актуально на 2026-10-24.

Список ПВЗ и постаматов СДЭК для выбора на странице оформления заказа.

1. Найди код населённого пункта СДЭК: GET /v2/location/cities по названию города. Код нужен и для расчёта, и для списка пунктов.
2. Запроси пункты выдачи: GET /v2/deliverypoints с city_code и type (PVZ, POSTAMAT или ALL). Для приёма оплаты при получении добавь allowed_cod=true, для крупных посылок — weight_max.
3. Покажи пункты на карте или списком и сохрани код выбранного пункта — он пойдёт в delivery_point заказа.
4. Обновляй список раз в сутки: пункты открываются и закрываются, хранить его статично нельзя.

```bash
# Код города
curl -G https://api.cdek.ru/v2/location/cities \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'city=Казань' \
  --data-urlencode 'country_codes=RU'

# Пункты выдачи и постаматы в этом городе
curl -G https://api.cdek.ru/v2/deliverypoints \
  -H "Authorization: Bearer $TOKEN" \
  -d city_code=<код города> \
  -d type=ALL \
  -d is_handout=true
```

## Базовые URL

- Боевой: `https://api.cdek.ru`
- Тестовый: `https://api.edu.cdek.ru`

## Авторизация

Тип: OAuth 2.0

OAuth 2.0 (client credentials). Токен получают запросом `POST /v2/oauth/token` с `grant_type=client_credentials`, `client_id` (Account) и `client_secret` (Secure password) из личного кабинета СДЭК (раздел интеграции) и передают в заголовке `Authorization: Bearer <token>` (JWT). Для интеграции нужен договор со СДЭК.

Тестовая учётная запись для `api.edu.cdek.ru` (из документации):

## Методы сценария

### GET /v2/deliverypoints — Список офисов

Список действующих ПВЗ и постаматов. Обновляйте список раз в сутки, не храните статично.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `code` | query | string | нет | Код ПВЗ |
| `type` | query | string | нет | POSTAMAT, PVZ, ALL |
| `postal_code` | query | string | нет | Почтовый индекс |
| `city_code` | query | integer | нет | Код населённого пункта СДЭК |
| `country_code` | query | string | нет | Код страны ISO 3166-1 alpha-2 |
| `region_code` | query | integer | нет | Код региона СДЭК |
| `have_cashless` | query | boolean | нет | Есть терминал оплаты |
| `allowed_cod` | query | boolean | нет | Разрешён наложенный платёж |
| `weight_max` | query | integer | нет | Макс. вес, кг |
| `is_handout` | query | boolean | нет | Пункт выдачи |
| `is_reception` | query | boolean | нет | Приём заказов |
| `size` | query | integer | нет | Размер страницы |
| `page` | query | integer | нет | Номер страницы |

### GET /v2/location/cities — Список населённых пунктов

Справочник населённых пунктов СДЭК с кодами. Поиск по названию — `GET /v2/location/suggest/cities`.

## Нюансы

- Создание сущностей асинхронное: статус запроса `ACCEPTED` означает только первичную валидацию, итог — `SUCCESSFUL` или `INVALID`. Обычно 200–500 мс, при пиковой нагрузке до 30–60 секунд; опрашивайте с паузой 2–3 секунды.
- В `POST /v2/orders` нельзя одновременно передавать `shipment_point` и `from_location`, а также `delivery_point` и `to_location`.
- Вес в граммах, габариты в сантиметрах.
- Изменять заказ можно только в статусах `CREATED` и `ACCEPTED`.
- Вебхуки: таймаут подключения 15 секунд, при ошибках — до 12 повторов за 75 минут, потом доставка прекращается.
- Данные о сущностях, созданных через API, хранятся 1 год.
- Сообщения — в UTF-8; обязательные поля не могут быть пустыми.

## Другие сценарии

- [Рассчитать стоимость и сроки доставки](https://mcp-everything.ru/integrations/cdek/scenarios/rasschitat-stoimost-i-sroki-dostavki.md)
- [Создать заказ и дождаться его регистрации](https://mcp-everything.ru/integrations/cdek/scenarios/sozdat-zakaz-i-dozhdatsya-ego.md)
- [Напечатать квитанцию и вызвать курьера](https://mcp-everything.ru/integrations/cdek/scenarios/napechatat-kvitantsiyu-i-vyzvat-kurera.md)
- [Получать статусы заказов вебхуком](https://mcp-everything.ru/integrations/cdek/scenarios/poluchat-statusy-zakazov-vebhukom.md)

---

Если этого недостаточно — официальная документация: https://apidoc.cdek.ru/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/cdek.md