Документы — заказы, отгрузки, приёмки — это сущности с обязательными ссылками на организацию и контрагента и массивом позиций. Разберём их создание и связи через JSON API 1.2.
Основные документы продаж
Документооборот МойСклад покрывает весь путь сделки. Наиболее востребованы в интеграциях:
| Документ | Ресурс | Роль |
|---|---|---|
| Заказ покупателя | /entity/customerorder | Фиксация заказа |
| Отгрузка | /entity/demand | Списание товара |
| Счёт покупателю | /entity/invoiceout | Выставление счёта |
| Входящий платёж | /entity/paymentin | Учёт оплаты |
Все документы устроены по общему шаблону: шапка со ссылками на участников, массив позиций positions и служебные поля вроде moment (дата документа).
Обязательные ссылки документа
Любой документ продажи требует двух ссылок в шапке — на свою организацию и на контрагента. Обе передаются объектом meta:
{
"organization": { "meta": { "href": ".../organization/{id}", "type": "organization" } },
"agent": { "meta": { "href": ".../counterparty/{id}", "type": "counterparty" } }
}
organization— юрлицо, от имени которого оформляется документ.agent— контрагент (покупатель).store— склад; обязателен для отгрузки.
GET /entity/organization и GET /entity/store, а затем кэшировать.Создание заказа покупателя
Заказ создаётся POST-запросом. В теле — шапка и массив позиций, где каждая позиция ссылается на товар через assortment:
POST /entity/customerorder
{
"organization": { "meta": {...} },
"agent": { "meta": {...} },
"positions": [{
"quantity": 3,
"price": 45000,
"assortment": { "meta": { "href": ".../product/{id}", "type": "product" } }
}]
}
Поле price — в копейках. Если цену не указать, МойСклад подставит цену продажи товара по умолчанию. Сумма документа считается автоматически.
Работа с позициями
Позиции документа — это вложенная коллекция, доступная и отдельным URL:
GET /entity/customerorder/{id}/positions
С позициями можно работать точечно, не переотправляя весь документ:
POST /entity/customerorder/{id}/positions— добавить строки;PUT /entity/customerorder/{id}/positions/{posId}— изменить строку;DELETE /entity/customerorder/{id}/positions/{posId}— удалить строку.
| Поле позиции | Смысл |
|---|---|
quantity | Количество |
price | Цена за единицу, копейки |
discount | Скидка, % |
vat | Ставка НДС |
Статусы и проведение
У документов есть статус (state) и признак проведения (applicable). Статус — это ссылка на элемент из метаданных документа:
"state": { "meta": { "href": ".../metadata/states/{id}", "type": "state" } }
- applicable: true — документ проведён и влияет на остатки/взаиморасчёты.
- applicable: false — черновик, не влияющий на учёт.
- Статусы (state) настраиваются в аккаунте и берутся из
/entity/customerorder/metadata.
Связи между документами
Документы можно связывать: отгрузка создаётся на основании заказа и хранит ссылку на него. Это позволяет строить цепочку сделки.
В отгрузке связь с заказом задаётся полем customerOrder:
"customerOrder": { "meta": { "href": ".../customerorder/{id}", "type": "customerorder" } }
Обратные ссылки — например, какие отгрузки созданы по заказу — доступны в самом заказе в полях вроде demands. Чтобы развернуть связанные документы сразу, применяйте expand:
GET /entity/customerorder/{id}?expand=demands,positions.assortment
Итог
Документы МойСклад через JSON API создаются по общему шаблону: обязательные ссылки на организацию и контрагента, массив позиций со ссылкой на ассортимент, цены в копейках, статус и признак проведения. Позициями можно управлять точечно, а документы связываются между собой ссылками, образуя цепочку заказ → отгрузка → оплата.
Мы реализуем такой документооборот как часть интеграции сайта на 1С-Битрикс с МойСклад: заказ с сайта превращается в корректный документ, статусы синхронизируются в обе стороны, а проведение отгрузок не ломает учёт остатков. Если нужен надёжный обмен заказами, поможем выстроить его под ваши процессы.
Частые вопросы
Какие ссылки обязательны в документе продажи?
Ссылки на организацию (organization) и контрагента (agent), обе через объект meta. Для отгрузки дополнительно обязателен склад (store).
Как добавить товары в заказ?
В массиве positions каждая строка ссылается на товар через assortment.meta и содержит quantity и price. Цена указывается в копейках.
Можно ли менять позиции без переотправки документа?
Да, позиции доступны отдельным URL: их можно добавлять, изменять и удалять через /entity/{тип}/{id}/positions, не трогая остальной документ.
Что означает поле applicable?
Это признак проведения. applicable: true означает, что документ проведён и влияет на остатки и взаиморасчёты, false — что это черновик.
Как связать отгрузку с заказом?
В отгрузке (demand) указывают поле customerOrder со ссылкой meta на заказ. Так документы образуют цепочку сделки.
Откуда брать статусы документа?
Из метаданных документа: GET /entity/customerorder/metadata. Статус в документе задаётся ссылкой meta на нужный элемент states.
Что будет, если не указать цену позиции?
МойСклад подставит цену продажи товара по умолчанию. Сумма документа при этом пересчитается автоматически.
Как сразу получить связанные отгрузки заказа?
Использовать expand, например ?expand=demands. Это разворачивает связанные документы в одном ответе без дополнительных запросов.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.