1. Главная
  2. Руководство Пользователя
  3. Руководство Пользователя

Запрос R7: Добавление в декларацию спецификации (с созданием товарных позиций, при необходимости)

Адрес: https://www.tws.by/tws/api/r7

Запрос позволяет добавить в декларацию список товаров (спецификацию), и при необходимости сразу создать из этой спецификации товарные позиции.

Для выполнения этого запроса необходимо наличие действующей подписки на услугу “Загрузка сведений о товарах через API”. Подробности в Пользовательском Соглашении.

Обратите внимание, что пользовательские данные могут содержать различные нестандартные символы, поэтому их обязательно необходимо кодировать в формат urlencoded после формирования строки в формате JSON для параметра Specification. Ссылки: PHP, 1С.

При загрузке выполняется контроль входных данных. Степень проверки входных данных задаётся параметром LazyDataChecks. В случае невозможности загрузки данных или создания из них товарных позиций заполняются поля ErrorMessages и WarningMessages выходных параметров.

Входные параметры

  • SessionKey – сессионный ключ, полученный из запроса R1. Обязательный параметр.
  • DeclarationID – внутренний ID декларации в Системе TWS. Может быть получен запросом R4 (список деклараций) либо R6 (создание новой декларации). Обязательный параметр.
  • CurrencyCode – трёхбуквенный код валюты, если необходимо изменить валюту декларации, в соответствии с Классификатором валют.
  • DeclarationDate – новая дата декларации, если необходимо её изменить. Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
  • Number – исходящий номер декларации, если необходимо его изменить.
  • LazyDataChecks – способ проверки данных спецификации, целое число. Возможные значения:
    • 0 – строгая проверка всех данных, необходимых для создания декларации и расчёта таможенных платежей.
    • 1 – проверка только тех данных, которые необходимы для расчёта таможенных платежей.
    • 2 – загрузка данных “как есть” с минимальными проверками (без гарантии создания готовых товарных позиций). Рекомендуется для статистических деклараций.
  • IgnoreWarnings – игнорирование предупреждений по данным спецификации (см. описание поля WarningMessages в ответе сервера). 0 – при наличии ошибок или предупреждений спецификация и товарные позиции не создаются. 1 – создание спецификации и товарных позиций блокируется только при наличии ошибок, предупреждения игнорируются.
  • CreateGoodPositions – признак создания товарных позиций на основании переданных данных спецификации. 0 - данные добавляются только в спецификацию, товарные позиции не создаются. 1 - данные добавляются в спецификацию и на их основании сразу создаются товарные позиции.
  • ApplyMaxAntidumping – автоматически применять максимальную ставку антидемпинговой пошлины (только при совпадении страны происхождения товаров и страны, указанной в антидемпинговой пошлине). 0 - ставка пошлины автоматически не применяется. 1 - автоматически применяется максимальная из доступных ставка антидемпинговой пошлины.
  • SellerPartner – краткое наименование Продавца/Контрактодержателя в соответствии с Карточками Контрагентов в Виртуальном офисе, если требуется его изменить в декларации.
  • SellerPartnerID – ID контрагента Продавца/Контрактодержателя в соответствии с Карточками Контрагентов в Виртуальном офисе, если требуется его изменить в декларации.
  • Specification – строка в формате JSON с массивом данных о товарах для добавления в спецификацию. Каждый элемент массива содержит следующие поля:
    • GoodPositionName – наименование товарной позиции (“название для лица”). Обязательный параметр при установке флага CreateGoodPositions.
    • Name – наименование товара (“название для обратки”). Обязательный параметр при установке флага CreateGoodPositions.
    • SpecialDescription – спецописание товара (в соответствии с Приложением №2 к Инструкции). Автоматически дописывается к наименованию товарной позиции.
    • Tnved – код ТНВЭД (десять цифр, можно с пробелами). Обязательный параметр.
    • TnvedAddition – код дополнительной таможенной информации (четыре цифры). Код “0000” означает “отсутствие дополнительной таможенной информации” и не сохраняется в спецификацию. В товарную позицию в любом случае подставляется код “0000”, если поле не заполнено.
    • Amount – количество в инвоисных единицах измерения. Обязательный параметр.
    • NetWeight – масса нетто в кг. Обязательный параметр.
    • NetWeight2 – масса нетто без первичной упаковки в кг. Заполняется только если отличается от значения массы нетто 1.
    • GrossWeight – масса брутто в кг. Обязательный параметр (кроме СД).
    • Cost – стоимость в валюте инвоиса. Обязательный параметр.
    • MeasureUnit – инвоисная единица измерения товара в соответствии с Классификатором единиц измерения. Может передаваться код, краткое наименование или полное наименование единицы измерения. Обязательный параметр.
    • Trademark – товарный знак.
    • Manufacturer – наименование производителя.
    • OriginCountry – страна происхождения товара в соответствии с Классификатором стран мира. Может передаваться как полное наименование страны, так и двухбуквенный код. Обязательный параметр.
    • Model – наименование модели.
    • VendorCode – артикул.
    • SerialNumber – серийный номер (или IMEI). Если серийных номеров добавлено несколько через запятую, в товарной позиции в сведениях о товаре они будут созданы отдельными записями с количеством только в первой записи. Если включена строгая проверка данных (параметр LazyDataChecks), то дополнительно выполняется контроль корректности IMEI-кодов и проверка на дубликаты, проверка на кратность количества серийных номеров количеству товара.
    • AdditionalMeasureAmount – Количество в дополнительных единицах измерения, если единица измерения отличается от инвоисной. При выборе режима LazyDataChecks=0 и наличии дополнительной единицы измерения в коде ТНВЭД этот параметр становится обязательным.
    • TnvedAmount – количество в единицах измерения для расчёта тарифа, если единица измерения отличается от инвоисной. При выборе режима LazyDataChecks=0 или LazyDataChecks=1 и отличии единицы измерения в специфической ставке кода ТНВЭД от инвоисной единицы измерения этот параметр становится обязательным.
    • ExciseAmount – количество в единицах измерения для расчёта акциза.
    • CargoPlacesAmount – количество грузовых мест. Обязательный параметр (кроме СД).
    • CargoPlaceType – код вида грузовых мест в соответствии с Классификатором видов груза, упаковки и упаковочных материалов.
    • InvoiceDate – дата инвоиса (документ добавляется в графу 44 товарной позиции с кодом “04021”). Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
    • InvoiceNumber – номер инвоиса (документ добавляется в графу 44 товарной позиции с кодом “04021”).
    • DateIssue – дата выпуска. Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
    • DimensionLength – габаритный размер: длина. Если заполнено это поле, то поле DimensionMeasure обязательно к заполнению.
    • DimensionWidth – габаритный размер: ширина. Если заполнено это поле, то поле DimensionMeasure обязательно к заполнению.
    • DimensionHeight – габаритный размер: высота. Если заполнено это поле, то поле DimensionMeasure обязательно к заполнению.
    • DimensionMeasure – габаритный размер: единица измерения в соответствии с Классификатором единиц измерения. Может передаваться код, краткое наименование или полное наименование единицы измерения. Поле обязательно к заполнению, если указан хотя бы один габаритный размер.
    • CustomsCost – оценка таможенной стоимости товара. Если это поле заполнено, метод определения стоимости для товара автоматически меняется на 6 при создании товарных позиций. Если не заполнено поле CustomsCostKind, оценка считается приведённой в валюте декларации.
    • CustomsCostKind – Тип оценки таможенной стоимости в поле CustomsCost. Допустимые значения: “USD/кг”, “USD/шт”, “бел.руб.”, “вал.дек.”, “$/кг”, “долл./кг”, “$/шт”, “долл./шт”, “валюта декларации”, “BYN”. Если значение поля не задано, по-умолчанию считается, что оценка приведена в валюте декларации.
    • ExciseID – применение режима расчёта акциза при создании товара. ID режима расчёта акциза можно получить запросом R12. Если режим расчёта акциза задан и в этом параметре, и в параметре TwsApiParams, то значение в TwsApiParams имеет приоритет. Значение “-1” означает “Акциз не начисляется”.
    • AntidumpingID – применение режима расчёта антидемпинговой пошлины при создании товара. ID режима расчёта антидемпинговой пошлины можно получить запросом R12. Если режим расчёта антидемпинговой пошлины задан и в этом параметре, и в параметре TwsApiParams, то значение в TwsApiParams имеет приоритет. Значение “-1” означает “Антидемпинговая пошлина не начисляется”.
    • IPRegistry – номер по таможенному реестру объектов интеллектуальной собственности. Если поле заполнено, выполняется поиск и проверка существования такого номера. При создании товарных позиций с указанным номером для них также автоматически проставляется признак “И”.
    • Documents – массив со списком произвольных документов, которые должны быть добавлены в графу 44 товарной позиции (графа 22 статистических деклараций). Если один и тот же документ необходимо добавить во все товарные позиции, его можно добавить в общие документы декларации запросом R11. Каждый элемент массива должен содержать следующие поля:
      • Type – Код документа в соответствии с Классификатором видов документов и сведений. Обязательное поле.
      • Date – дата документа. Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
      • Number – номер документа.
      • DateFrom – дата начала действия документа. Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
      • DateTo – дата окончания действия документа. Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
      • Sign – признак подачи документа в соответствии со Справочником признаков подачи документов.
      • RegDocNumber – номер документа, с которым был ранее предоставлен документ (для признака подачи “2”).
    • SdLiabilityDate – дата отгрузки/поступления. Только для статистических деклараций. Формат: YYYY-MM-DD или ДД.ММ.ГГГГ.
    • SdSrcCountry – двухбуквенный код страны отправления в соответствии с Классификатором стран мира. Только для статистических деклараций. Для экспортных статистических деклараций должно содержать значение “BY” либо быть незаполненным.
    • SdSrcCountryRegion – код региона страны отправления в соответствии с Классификатором административно-территориального деления стран мира. Значение поля игнорируется, если не заполнено поле SdSrcCountry. Код “000” соответствует записи справочника “000 - Иные”. Для заполнения графы значением “000 - Отсутствие административно-территориального деления” просто оставьте поле пустым.
    • SdDstCountry – двухбуквенный код страны назначения в соответствии с Классификатором стран мира. Только для статистических деклараций. Для импортных статистических деклараций должно содержать значение “BY” либо быть незаполненным.
    • SdDstCountryRegion – код региона страны назначения в соответствии с Классификатором административно-территориального деления стран мира. Значение поля игнорируется, если не заполнено поле SdDstCountry. Код “000” соответствует записи справочника “000 - Иные”. Для заполнения графы значением “000 - Отсутствие административно-территориального деления” просто оставьте поле пустым.
    • IdentificationCodes - Коды средств идентификации, разделённые переносом строки или запятой. По одному коду в строке (для одиночных кодов либо кодов агрегации), либо первый-последний коды для диапазонов.
    • IdentificationAggregationKind - Код уровня маркировки средствами идентификации: “0” - средство идентификации нанесено непосредственно на товар, “1” - средство идентификации нанесено на групповую упаковку, “2” - средство идентификации транспортной упаковки нанесено на транспортную упаковку, “3” - средство идентификации нанесено на набор (комплект) товаров. Если переданы коды в поле IdentificationCodes и не задан код уровня маркировки, автоматически подставляется значение “0”.
    • ApiNote – произвольная строка. Обычно используется для связи загружаемых в Систему TWS данных с данными в интегрируемой системе (например, идентификатор карточки товара, номер строки в инвоисе и т.п.). При получении данных из Системы TWS запросами R5, R8 строка будет записана в соответствующее поле ответа.
    • TwsApiParams – строка, полученная для данной записи запросами R5, R8 для применения настроек к товарной позиции даже после очистки декларации.

Параметры JSON-ответа

  • ErrorMessages – Массив с сообщениями об ошибках для каждой строки спецификации. Элементы массива содержат следующие поля:
    • ApiNote – значение поля ApiNote в исходных данных для строки спецификации, В которой возникла ошибка.
    • Message – сообщения об ошибках или пустая строка, если ошибок не было.
    • RowNumber – номер строки в массиве Specification во входном параметре. Поле может отсутствовать в ответе сервера, если ошибка обнаружилась уже после создания товарных позиций (т.к. в товарных позициях товары могут перемешаться).
  • WarningMessages – Массив предупреждений для каждой строки спецификации. Предупреждения - это ситуации, которые с большой долей вероятности являются ошибкой, но всё же не в 100% случаев. Элементы массива содержат следующие поля:
    • ApiNote – значение поля ApiNote в исходных данных для строки спецификации, В которой возникла ошибка.
    • Message – список предупреждений или пустая строка, если предупреждений не было.
    • RowNumber – номер строки в массиве Specification во входном параметре. Поле может отсутствовать в ответе сервера, если предупреждение обнаружилось уже после создания товарных позиций (т.к. в товарных позициях товары могут перемешаться).