Запрос 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 во входном параметре. Поле может отсутствовать в ответе сервера, если предупреждение обнаружилось уже после создания товарных позиций (т.к. в товарных позициях товары могут перемешаться).