Создание прихода через API

Доступ к API и URL

Для работы с API используется персональный токен. Его можно получить в разделе Настройка → API сервер. Токен подтверждает, что запрос отправлен от имени вашей фирмы и имеет доступ к соответствующим данным.

В каждом запросе необходимо передавать токен в параметре token строки запроса (query string).

Маршрут API:

public/firm-api/prih-docs.json

Полный вид URL:

…/api/public/index.php?route=public/firm-api/prih-docs.json&token=…

Вместо многоточия в начале URL указывается адрес вашего сервера Mercury-ИИ, а вместо … после token= — ваш персональный токен.

Один и тот же маршрут поддерживает два HTTP-метода:

• GET — получить журнал приходных накладных и их содержимое.
• POST — создать новую приходную накладную.

Для GET-запроса дополнительно передаются параметры периода, за который нужно получить документы. Для POST-запроса вместо них передаётся JSON-тело с данными создаваемой накладной.

Подробности получения токена, включения API и примеры команд приведены в справке «API сервер → Приходы».

GET — получение журнала приходов

Метод GET возвращает список приходных накладных фирмы за указанный период. Вместе с документами возвращаются сведения о складах, поставщиках и товарных строках.

Параметры запроса

Помимо обязательного параметра token, для GET-запроса необходимо передать следующие параметры:

• date_from — начало периода. Формат даты: YYYY-MM-DD. Обязательный параметр.
• date_to — конец периода. Формат даты: YYYY-MM-DD. Обязательный параметр.
• store_id — идентификатор склада, по которому нужно получить документы. Необязательный параметр. Допускается также имя id_sklad.

Параметры date_from и date_to задают границы периода, но максимальная его продолжительность не может превышать 366 дней.

Если store_id не передан, метод возвращает документы по всем складам фирмы. Если указан идентификатор склада, выборка ограничивается этим складом.

Какие документы попадают в результат

При получении журнала действуют разные правила для черновиков и проведённых накладных:

• Черновики возвращаются независимо от указанных дат. Поэтому в ответ могут попасть непроведённые документы, созданные раньше начала запрошенного периода.
• Проведённые накладные возвращаются только в пределах указанного периода.
• Производственные приходы в результат GET не включаются.

Учитывайте это при обработке ответа: если вы используете GET для синхронизации документов с другой системой, черновики могут иметь даты за пределами запрошенного периода.

Структура ответа

В корне JSON-ответа находятся следующие поля:

• updated_at — информация об обновлении данных.
• filter — параметры фильтрации, применённые к запросу. Позволяет увидеть, с какими условиями была сформирована выборка.
• store — выбранный склад. Если запрос выполнен без ограничения по складу, значение равно null.
• stores[] — список складов фирмы.
• docs[] — массив приходных накладных, попавших в выборку.

Поля приходной накладной в docs[]

Каждый элемент массива docs[] представляет собой отдельный приходный документ. В нём содержатся следующие поля:

• id — внутренний идентификатор документа.
• date_prih — дата прихода в программе.
• nomer_nakl — номер накладной поставщика.
• date_nakl — дата накладной поставщика.
• store_id — идентификатор склада.
• store_name — название склада.
• contragent_id — идентификатор контрагента-поставщика.
• contragent_name — название поставщика.
• posted — признак проведения документа.
• summa — общая сумма приходной накладной.
• dolg — сумма задолженности по документу.
• is_return — признак возврата поставщику.
• is_auto — признак автоматического документа.
• rows[] — массив товарных строк накладной.

По этим полям можно определить, какой документ получен, к какому складу и поставщику он относится, проведён ли он и на какую сумму сформирован.

Поля товарной строки в rows[]

Вложенный массив rows[] содержит товары, включённые в накладную. Каждая строка содержит:

• id — идентификатор строки документа.
• product_id — идентификатор товара в каталоге.
• product_name — название товара.
• unit — единица измерения.
• qty — количество товара.
• nds — значение НДС.
• price — закупочная цена за единицу.
• retail_price — розничная цена.
• summa — сумма по строке.

Таким образом, для получения полной информации о приходе достаточно обработать массив docs[] и вложенные в каждый документ массивы rows[].

POST — создание приходной накладной

Метод POST создаёт новую приходную накладную в Mercury-ИИ. Данные документа передаются в теле HTTP-запроса в формате JSON.

Используется тот же маршрут:

public/firm-api/prih-docs.json

В отличие от GET, для POST не нужно передавать параметры date_from и date_to. Вместо них в теле запроса указываются склад, поставщик и товарные строки будущей накладной.

При успешном создании сервер возвращает HTTP-статус 201 Created и объект созданного документа в структуре:

{ "doc": { … } }

Объект doc имеет формат элемента журнала приходов, описанный выше в разделе GET. Поэтому после создания документа его данные можно обрабатывать тем же способом, что и данные, полученные при запросе журнала.

Обязательные поля документа

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

• store_id — идентификатор склада, на который поступает товар. Допускается алиас id_sklad. Идентификатор склада можно предварительно получить методом stores.json.
• contragent_id — идентификатор поставщика. Допускается алиас id_contragent. Идентификатор контрагента можно получить методом contragents.json.
• rows — массив товарных строк. В массиве должна быть как минимум одна строка.

Обратите внимание: в запросе передаются именно идентификаторы существующих записей склада и контрагента. Поэтому перед созданием прихода обычно сначала получают необходимые справочные данные через соответствующие методы API, а затем используют их ID в POST-запросе.

Необязательные поля документа

Дополнительно можно передать следующие параметры:

• date_prih — дата прихода в программе. Допускается алиас date. Если поле не передано, используется текущая дата.
• nomer_nakl — номер накладной поставщика. Допускается алиас nomer.
• date_nakl — дата накладной поставщика.
• posted — признак проведения документа. По умолчанию false, то есть создаётся черновик. Если передать true, накладная будет создана сразу проведённой. Для проведения также предусмотрен алиас valid_flag со значением 1.
• is_return — признак возврата поставщику. Принимает значение 0 или 1.

Если необязательное поле не передано, применяется указанное значение по умолчанию, если оно предусмотрено. Например, если не передать date_prih, документ получит текущую дату, а если не передать posted, он останется черновиком.

Строки документа: rows[]

Массив rows[] содержит товары, которые нужно включить в приходную накладную. Каждая запись массива описывает один товар и количество, поступившее на склад.

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

Поля строки

• product_id — идентификатор товара в каталоге Mercury-ИИ. Обязательное поле. Допускается алиас id_tovar.
• qty — количество поступившего товара. Обязательное поле, значение должно быть больше нуля. Допускается алиас cnt.
• price — закупочная цена товара за единицу. Допускается алиас cena. Если цена не передана, используется последняя закупочная цена товара.
• nds — значение НДС. Если поле не передано, используется значение из карточки товара.
• retail_price — розничная цена товара. Необязательное поле. Допускается алиас cena_rash.
• serials — массив серийных номеров товара. Если для товара включён посерийный учёт, поле обязательно. Количество переданных серийных номеров должно совпадать со значением qty.

Идентификатор товара и количество

Поле product_id указывает, какой именно товар нужно добавить в накладную. Это ID товара из каталога, а не его название или штрихкод. Если вы ещё не знаете идентификатор товара, сначала получите каталог через метод catalog.json.

Поле qty определяет количество единиц товара в приходе. Значение должно быть положительным. Нулевое или отрицательное количество для строки не подходит.

Закупочная и розничная цены

В поле price передаётся закупочная цена за единицу товара. Если вы не укажете её, программа подставит последнюю закупочную цену, известную для этого товара.

Поле retail_price предназначено для передачи розничной цены. Оно необязательно: если ваша внешняя система не передаёт розничную цену, это поле можно не включать в строку.

Поле nds также можно не передавать, если нужно использовать значение НДС, уже указанное в карточке товара.

Серийные номера

Если в карточке товара включён посерийный учёт, для каждой приходной строки необходимо передать массив serials с серийными номерами поступивших единиц товара.

Количество серийных номеров должно точно соответствовать количеству товара в поле qty. Например, если в приходе указано qty: 3, массив serials должен содержать три серийных номера.

Если товар не требует посерийного учёта, передавать массив serials не требуется.

Черновик и проведение накладной

При создании прихода важно различать два состояния документа: черновик и проведённую накладную. От выбранного состояния зависит, будет ли поступление учтено в складских остатках.

Создание черновика

По умолчанию API создаёт непроведённую накладную. Для этого достаточно не передавать поле posted или передать значение false.

Черновик сохраняется в программе, но ещё не изменяет складские остатки. Это удобно, если вы сначала хотите передать документ в Mercury-ИИ, проверить его содержимое, а провести позднее через интерфейс программы.

Такой документ будет отображаться в журнале приходов как непроведённая накладная и открываться в обычной карточке прихода.

Создание проведённой накладной

Если вы хотите, чтобы документ был проведён сразу при создании, передайте:

"posted": true

В качестве альтернативы можно использовать поле valid_flag со значением 1.

В этом случае накладная создаётся уже проведённой, аналогично тому, как если бы пользователь создал документ в интерфейсе и нажал кнопку «Провести».

Важно: если вы передаёте posted: true, убедитесь, что данные документа готовы к проведению. Если требуется предварительная проверка или согласование поступления, безопаснее сначала создать черновик, а затем провести его из интерфейса программы.

Ограничения API

У метода создания прихода есть несколько особенностей, которые важно учитывать при интеграции с внешней системой.

• Привязка к сделке CRM. Поле id_deal через public POST не задаётся. Если приход необходимо связать со сделкой CRM, откройте созданную накладную в интерфейсе Mercury-ИИ и укажите сделку в поле «Сделка». Подробнее — «Привязка к сделке CRM».
• Производственные приходы. Метод GET не возвращает производственные приходы. Они не входят в выдачу журнала этого API-метода.

При проектировании интеграции учитывайте эти ограничения заранее. Например, если внешняя система должна создавать приходы и одновременно связывать их со сделками CRM, сам документ можно создать через API, а привязку к сделке выполнить уже в интерфейсе программы.

Как API связан с интерфейсом программы

Приходная накладная, созданная через API, становится обычным документом Mercury-ИИ. Её можно найти в журнале приходов соответствующего склада, открыть и просмотреть в стандартной карточке прихода.

Это означает, что API не создаёт отдельный тип документа со своей собственной логикой отображения. Он позволяет передать данные извне, а дальнейшая работа с накладной выполняется так же, как с документом, созданным вручную.

Например, внешняя учётная система может автоматически передать в Mercury-ИИ склад, поставщика и список поступивших товаров. После создания документа пользователь сможет открыть его в программе, проверить строки и при необходимости провести черновик.

Для работы с API необходимо включить соответствующий доступ и использовать персональный токен из раздела Настройка → API сервер. Полная документация по настройке и примеры запросов находятся в разделе «API сервер → Приходы».

Связанные методы API

Для создания приходной накладной обычно нужны идентификаторы склада, поставщика и товаров. Получить их можно с помощью других методов API:

• stores.json — получение списка складов фирмы. Используйте его, чтобы узнать значение store_id.
• contragents.json — получение списка контрагентов. Позволяет определить contragent_id нужного поставщика.
• catalog.json — получение товарного каталога. Нужен для определения product_id товаров.
• stocks.json — получение информации об остатках.
• supplier-orders.json — работа с заказами поставщикам. Это отдельный метод API, не являющийся частью маршрута создания приходов.

Если вы разрабатываете интеграцию с нуля, сначала получите необходимые справочники и сохраните соответствие идентификаторов между Mercury-ИИ и вашей системой. Затем используйте эти ID при формировании JSON для POST-запроса.

Дополнительные материалы:

• Приходы — раздел программы.
• API сервер — настройка доступа и общие сведения об API.