{"name":"RetailCRM API v5","vendor":"RetailCRM","industry":"crm","summary":"REST API CRM для интернет-магазинов и ритейла RetailCRM: заказы и их история, клиенты, товары и остатки, оплаты, справочники, доставка, телефония, задачи. Запросы выполняются к поддомену аккаунта, ключ передаётся параметром `apiKey`. Актуальная версия — v5, предыдущие сохранены для совместимости и не рекомендуются.","docsUrl":"https://rest-api-docs.retailcrm.ru/v5/","coverage":{"included":[],"excluded":[]},"scenarios":[{"id":"peredat-zakaz-s-sayta-v-retailcrm","title":"Передать заказ с сайта в RetailCRM","summary":"Каждый заказ интернет-магазина сразу попадает в CRM с клиентом, товарами, доставкой и оплатой.","steps":["Создай API-ключ в RetailCRM (Настройки → Интеграция → Ключи доступа к API). Запросы идут на https://<поддомен>.retailcrm.ru/api/v5/, ключ — в параметре apiKey. Если ключ видит несколько магазинов, передавай site — символьный код магазина.","Отправь заказ: POST /api/v5/orders/create. Тело — application/x-www-form-urlencoded, а сам order — JSON-строкой в поле формы. Внутри: externalId (номер у тебя), firstName, lastName, phone, email, items (offer с externalId товара и quantity), delivery и customerComment.","Клиента RetailCRM создаст по данным заказа. Если клиент у тебя уже есть, создай его заранее через POST /api/v5/customers/create с customer.externalId и привяжи к заказу через order.customer.","В ответе — id заказа в RetailCRM. Сохрани его рядом с externalId.","Лимит — 10 запросов в секунду с одного IP; при превышении придёт 503."],"code":"curl -X POST \"https://<поддомен>.retailcrm.ru/api/v5/orders/create\" \\\n  --data-urlencode \"apiKey=$RCRM_KEY\" \\\n  --data-urlencode 'site=my-shop' \\\n  --data-urlencode 'order={\n    \"externalId\": \"1042\",\n    \"orderMethod\": \"shopping-cart\",\n    \"firstName\": \"Иван\",\n    \"lastName\": \"Петров\",\n    \"phone\": \"+79990001122\",\n    \"email\": \"ivan@example.ru\",\n    \"items\": [{\"offer\": {\"externalId\": \"SKU-17\"}, \"quantity\": 2, \"initialPrice\": 990}],\n    \"delivery\": {\"address\": {\"text\": \"Москва, ул. Тверская, 1, кв. 5\"}, \"cost\": 300},\n    \"customerComment\": \"Позвонить за час\"\n  }'","language":"bash","methods":["POST /api/v5/orders/create","POST /api/v5/customers/create"]},{"id":"zabirat-izmeneniya-zakazov-bez-polnoy","title":"Забирать изменения заказов без полной перевыгрузки","summary":"Синхронизация статусов и состава заказов из RetailCRM в свою систему.","steps":["Запроси историю: GET /api/v5/orders/history с filter[sinceId] — id последнего обработанного изменения (в первый раз можно начать с filter[startDate]).","Каждая запись истории — одно изменённое поле: field, oldValue, newValue и order, к которому оно относится. Применяй изменения по порядку.","Сохрани id последней записи и в следующий раз передай его в filter[sinceId]. Листай страницы, пока currentPage меньше totalPageCount.","Если нужен заказ целиком, получи его: GET /api/v5/orders/{externalId} с by = externalId (или by = id для внутреннего номера).","Не перевыгружай весь список GET /api/v5/orders по расписанию — история быстрее и не упирается в лимит запросов."],"code":"curl -G \"https://<поддомен>.retailcrm.ru/api/v5/orders/history\" \\\n  --data-urlencode \"apiKey=$RCRM_KEY\" \\\n  -d 'filter[sinceId]=15230' \\\n  -d limit=100","language":"bash","methods":["GET /api/v5/orders","GET /api/v5/orders/{externalId}","GET /api/v5/orders/history"]},{"id":"smenit-status-zakaza-i-otmetit-oplatu","title":"Сменить статус заказа и отметить оплату","summary":"Оплата пришла в платёжной системе — заказ в CRM переходит в нужный статус, оплата отмечается.","steps":["Измени заказ: POST /api/v5/orders/{externalId}/edit с by = externalId и order — JSON-строкой только с изменяемыми полями, например status. Коды статусов видны в настройках RetailCRM.","Добавь оплату: POST /api/v5/orders/payments/create с payment — JSON-строкой: order (externalId или id заказа), type (код типа оплаты из справочника), amount, status и paidAt.","Если оплата уже создана и нужно поменять её статус, используй /api/v5/orders/payments/{id}/edit.","Ошибки валидации приходят с кодом 400 и списком errors — по нему видно, какое поле не прошло."],"code":"curl -X POST \"https://<поддомен>.retailcrm.ru/api/v5/orders/1042/edit\" \\\n  --data-urlencode \"apiKey=$RCRM_KEY\" \\\n  --data-urlencode 'by=externalId' \\\n  --data-urlencode 'site=my-shop' \\\n  --data-urlencode 'order={\"status\": \"assembling\"}'\n\ncurl -X POST \"https://<поддомен>.retailcrm.ru/api/v5/orders/payments/create\" \\\n  --data-urlencode \"apiKey=$RCRM_KEY\" \\\n  --data-urlencode 'site=my-shop' \\\n  --data-urlencode 'payment={\"order\": {\"externalId\": \"1042\"}, \"type\": \"bank-card\", \"amount\": 2280, \"status\": \"paid\", \"paidAt\": \"2026-10-24 18:30:00\"}'","language":"bash","methods":["POST /api/v5/orders/{externalId}/edit","POST /api/v5/orders/payments/create"]},{"id":"zagruzit-ostatki-tovarov","title":"Загрузить остатки товаров","summary":"Синхронизировать остатки со склада, чтобы операторы видели, что есть в наличии.","steps":["Отправь остатки: POST /api/v5/store/inventories/upload с offers — JSON-строкой: для каждого торгового предложения его externalId (или id) и stores — склады с code и available.","За один запрос можно передать много предложений — отправляй изменения пачками, а не по одному товару.","Проверь результат: GET /api/v5/store/products с фильтром по товару покажет актуальные остатки."],"code":"curl -X POST \"https://<поддомен>.retailcrm.ru/api/v5/store/inventories/upload\" \\\n  --data-urlencode \"apiKey=$RCRM_KEY\" \\\n  --data-urlencode 'site=my-shop' \\\n  --data-urlencode 'offers=[\n    {\"externalId\": \"SKU-17\", \"stores\": [{\"code\": \"main\", \"available\": 25}]},\n    {\"externalId\": \"SKU-18\", \"stores\": [{\"code\": \"main\", \"available\": 0}]}\n  ]'","language":"bash","methods":["GET /api/v5/store/products","POST /api/v5/store/inventories/upload"]}],"baseUrls":[{"label":"Боевой","url":"https://{your-subdomain}.retailcrm.ru/api/v5/"}],"auth":{"type":"api_key","description":"API-ключ создаётся в аккаунте RetailCRM и передаётся в параметре `apiKey` (GET или POST). Если ключ даёт доступ к нескольким магазинам, части методов нужен параметр `site` — символьный код магазина. Запросы — только по HTTPS, кодировка UTF-8.","example":""},"methods":[{"id":"GET /api/v5/orders","title":"Список заказов","httpMethod":"GET","path":"/api/v5/orders","description":"","params":[{"name":"apiKey","in":"query","type":"string","required":true,"description":"API-ключ"},{"name":"filter","in":"query","type":"object","required":false,"description":"Фильтр: filter[numbers][], filter[externalIds][], filter[customerId], filter[email], filter[minPrice], filter[maxPrice], filter[trackNumber] и др."},{"name":"limit","in":"query","type":"integer","required":false,"description":"Количество записей на странице"},{"name":"page","in":"query","type":"integer","required":false,"description":"Номер страницы, по умолчанию 1"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"GET /api/v5/orders/{externalId}","title":"Получить заказ","httpMethod":"GET","path":"/api/v5/orders/{externalId}","description":"","params":[{"name":"externalId","in":"path","type":"string","required":true,"description":"Внешний или внутренний ID заказа"},{"name":"by","in":"query","type":"string","required":false,"description":"externalId или id"},{"name":"site","in":"query","type":"string","required":false,"description":"Код магазина"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/orders/create","title":"Создать заказ","httpMethod":"POST","path":"/api/v5/orders/create","description":"Тело — `application/x-www-form-urlencoded`; объект `order` передаётся JSON-строкой.","params":[{"name":"apiKey","in":"body","type":"string","required":true,"description":"API-ключ"},{"name":"site","in":"body","type":"string","required":false,"description":"Код магазина"},{"name":"order","in":"body","type":"string (JSON)","required":true,"description":"Заказ"},{"name":"order.externalId","in":"body","type":"string","required":false,"description":"Внешний ID"},{"name":"order.number","in":"body","type":"string","required":false,"description":"Номер заказа"},{"name":"order.orderType","in":"body","type":"string","required":false,"description":"Тип заказа"},{"name":"order.orderMethod","in":"body","type":"string","required":false,"description":"Способ оформления, например phone"},{"name":"order.status","in":"body","type":"string","required":false,"description":"Статус, например assembling"},{"name":"order.firstName","in":"body","type":"string","required":false,"description":"Имя"},{"name":"order.lastName","in":"body","type":"string","required":false,"description":"Фамилия"},{"name":"order.patronymic","in":"body","type":"string","required":false,"description":"Отчество"},{"name":"order.phone","in":"body","type":"string","required":false,"description":"Телефон"},{"name":"order.email","in":"body","type":"string","required":false,"description":"Email"},{"name":"order.customer","in":"body","type":"object","required":false,"description":"Привязка к клиенту (id и тип)"},{"name":"order.managerId","in":"body","type":"integer","required":false,"description":"Менеджер"},{"name":"order.items","in":"body","type":"array","required":false,"description":"Позиции: offer, quantity, priceType, purchasePrice и др."},{"name":"order.delivery","in":"body","type":"object","required":false,"description":"Доставка: address, cost, netCost и др."},{"name":"order.payments","in":"body","type":"array","required":false,"description":"Оплаты: type, status, amount, paidAt"},{"name":"order.customFields","in":"body","type":"object","required":false,"description":"Пользовательские поля"},{"name":"order.shipmentStore","in":"body","type":"string","required":false,"description":"Склад отгрузки"},{"name":"order.shipmentDate","in":"body","type":"string","required":false,"description":"Дата отгрузки"},{"name":"order.customerComment","in":"body","type":"string","required":false,"description":"Комментарий клиента"},{"name":"order.managerComment","in":"body","type":"string","required":false,"description":"Комментарий оператора"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/orders/{externalId}/edit","title":"Изменить заказ","httpMethod":"POST","path":"/api/v5/orders/{externalId}/edit","description":"","params":[{"name":"externalId","in":"path","type":"string","required":true,"description":"Внешний или внутренний ID заказа"},{"name":"by","in":"body","type":"string","required":false,"description":"externalId или id"},{"name":"site","in":"body","type":"string","required":false,"description":"Код магазина"},{"name":"order","in":"body","type":"string (JSON)","required":true,"description":"Изменяемые поля заказа"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"GET /api/v5/orders/history","title":"История изменений заказов","httpMethod":"GET","path":"/api/v5/orders/history","description":"","params":[{"name":"filter","in":"query","type":"object","required":false,"description":"Фильтр истории"},{"name":"limit","in":"query","type":"integer","required":false,"description":"Количество записей"},{"name":"page","in":"query","type":"integer","required":false,"description":"Страница"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"GET /api/v5/orders/statuses","title":"Статусы заказов","httpMethod":"GET","path":"/api/v5/orders/statuses","description":"Статусы заказов по списку ID или внешних ID.","params":[],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/orders/payments/create","title":"Создать оплату заказа","httpMethod":"POST","path":"/api/v5/orders/payments/create","description":"Добавляет оплату к заказу. Изменение — `POST /api/v5/orders/payments/{id}/edit`, удаление — `POST /api/v5/orders/payments/{id}/delete`.","params":[],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/orders/upload","title":"Пакетная загрузка заказов","httpMethod":"POST","path":"/api/v5/orders/upload","description":"Загружает несколько заказов за раз. При частичных ошибках возвращает нестандартный код `460` с `uploadedOrders` и `errors`.","params":[],"requestExample":"","responseExample":"","docsUrl":""},{"id":"GET /api/v5/customers","title":"Список клиентов","httpMethod":"GET","path":"/api/v5/customers","description":"","params":[{"name":"filter","in":"query","type":"object","required":false,"description":"Фильтр"},{"name":"limit","in":"query","type":"integer","required":false,"description":"Количество записей"},{"name":"page","in":"query","type":"integer","required":false,"description":"Страница"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/customers/create","title":"Создать клиента","httpMethod":"POST","path":"/api/v5/customers/create","description":"","params":[{"name":"site","in":"body","type":"string","required":false,"description":"Код магазина"},{"name":"customer","in":"body","type":"string (JSON)","required":true,"description":"Клиент"},{"name":"customer.externalId","in":"body","type":"string","required":false,"description":"Внешний ID"},{"name":"customer.firstName","in":"body","type":"string","required":false,"description":"Имя"},{"name":"customer.lastName","in":"body","type":"string","required":false,"description":"Фамилия"},{"name":"customer.email","in":"body","type":"string","required":false,"description":"Email"},{"name":"customer.phones","in":"body","type":"array","required":false,"description":"Телефоны"},{"name":"customer.address","in":"body","type":"object","required":false,"description":"Адрес"},{"name":"customer.managerId","in":"body","type":"integer","required":false,"description":"Менеджер"},{"name":"customer.customFields","in":"body","type":"object","required":false,"description":"Пользовательские поля"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/customers/{externalId}/edit","title":"Изменить клиента","httpMethod":"POST","path":"/api/v5/customers/{externalId}/edit","description":"","params":[{"name":"externalId","in":"path","type":"string","required":true,"description":"Внешний или внутренний ID клиента"},{"name":"by","in":"body","type":"string","required":false,"description":"externalId или id"},{"name":"site","in":"body","type":"string","required":false,"description":"Код магазина"},{"name":"customer","in":"body","type":"string (JSON)","required":true,"description":"Изменяемые поля"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"GET /api/v5/store/products","title":"Список товаров","httpMethod":"GET","path":"/api/v5/store/products","description":"","params":[{"name":"filter","in":"query","type":"object","required":false,"description":"Фильтр"},{"name":"limit","in":"query","type":"integer","required":false,"description":"Количество записей"},{"name":"page","in":"query","type":"integer","required":false,"description":"Страница"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /api/v5/store/inventories/upload","title":"Загрузка остатков","httpMethod":"POST","path":"/api/v5/store/inventories/upload","description":"","params":[{"name":"offers","in":"body","type":"string (JSON)","required":true,"description":"Торговые предложения с остатками"},{"name":"site","in":"body","type":"string","required":false,"description":"Код магазина"}],"requestExample":"","responseExample":"","docsUrl":""}],"codeExamples":[],"errors":[{"code":"400","description":"Неверные параметры запроса; детали в errors"},{"code":"403","description":"Не передан или неверен apiKey, либо ограничение по IP"},{"code":"404","description":"Аккаунт не найден"},{"code":"460","description":"Заказы загружены с ошибками (uploadedOrders, errors)"},{"code":"500","description":"Ошибка приложения"},{"code":"503","description":"Превышен лимит запросов или сервис перегружен"}],"limits":"- 10 запросов в секунду с одного IP для общих методов.\n- 40 запросов в секунду с одного IP для методов телефонии `/api/telephony/*`.\n- При превышении — `HTTP/1.1 503 Service Temporarily Unavailable`.","gotchas":["POST-запросы отправляются как `application/x-www-form-urlencoded`, а вложенные структуры (`order`, `customer`, `offers`) — JSON-строкой внутри поля формы.","Для ключа с доступом к нескольким магазинам часть методов требует `site`.","Ответы списков содержат метаданные пагинации: `limit`, `totalCount`, `currentPage`, `totalPageCount`.","Для синхронизации изменений используйте `/orders/history` и `/customers/history`, а не полную перевыгрузку списков.","Код `460` при пакетной загрузке означает, что часть заказов загружена с ошибками; загруженные перечислены в `uploadedOrders`."],"slug":"retailcrm","version":2,"updatedAt":"2026-10-24T17:05:35.604Z","sources":[{"title":"Документация REST API v5","url":"https://rest-api-docs.retailcrm.ru/v5/","kind":"research","addedAt":"2026-10-12T11:04:16.523Z"},{"title":"Правила работы с API","url":"https://help.retailcrm.ru/Developers/ApiRules","kind":"research","addedAt":"2026-10-12T11:04:16.523Z"},{"title":"Официальный PHP-клиент (маршруты и модели запросов)","url":"https://github.com/retailcrm/api-client-php","kind":"research","addedAt":"2026-10-12T11:04:16.523Z"},{"title":"Вставленный текст","url":"","kind":"import","addedAt":"2026-10-12T11:04:16.523Z"},{"title":"scenarios-retailcrm.md","url":"","kind":"import","addedAt":"2026-10-24T17:05:26.298Z"}],"logoUrl":null}