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

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

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

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

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

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

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

При успешном прохождении входных проверок данных перед сохранением новой спецификации все старые спецификации удаляются. Если переда параметр CreateGoodPositions, то перед созданием товарных позиций все уже созданные товарные позиции в декларации также очищаются.

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

  • 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” означает “Антидемпинговая пошлина не начисляется”.
    • SpecialTariffID – применение ставки специальной таможенной пошлины. 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”).
      • DocGoodNumber – порядковый номер товара в представленном документе. Целое число от 1 до 999.
    • 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 во входном параметре. Поле может отсутствовать в ответе сервера, если предупреждение обнаружилось уже после создания товарных позиций (т.к. в товарных позициях товары могут перемешаться).

Применение TwsApiParams

TODO