Често задавани въпроси

Системата приема един валиден файл за търговец на ден. След успешно приемане подаването за текущата дата се заключва, за да се гарантира, че данните за цените няма да се дублират и да няма противоречиви версии. Двойни данни няма как да бъдат визуализиране, а презаписването върху стари данни може да доведе до серия от проблеми.
Важно за тестова среда: в публичната тестова среда това ограничение е изключено, за да можете да тествате многократно.

Съгласно указанията, подаването е разрешено само за текущия календарен ден и до 12:00 ч. местно време. Извън този интервал бутонът се скрива/деактивира и API отхвърля заявки.
Важно за тестова среда: времевите ограничения са премахнати, за да симулирате подавания по всяко време.

В момента, в който файлът е успешно валидиран и приет (порталът показва потвърждение / API връща 200 OK), подаването за деня се счита финално за съответната търговска верига. Системата не позволява корекции за същия ден от страна на търговеца.

Данните за този ден няма да се публикуват. Подайте коректно на следващия ден и сигнализирайте КЗП за причината (при системен проблем).

Не. „\n“ е символ за нов ред в UNIX среди. Не го изписвайте като текст. Всеки запис трябва да е на нов ред в CSV файла; редакторът/скриптът ви трябва да записва реален нов ред (LF/CRLF), а не буквите „\“ и „n“.

Не. Редът на колоните е фиксиран. Разместване, преименуване или липсваща колона водят до отхвърляне. Уверете се, че заглавният ред (headers) съвпада буквално с указанията и примерните данни. Проверката е case sensitive – тоест дори изписването на главни и малки букви е от значение.

Не, ако всички полета са в двойни кавички. Пример:
"Населено място","Търговски обект","Наименование на продукта",...
Поле като "Яйца, размер L" е коректно, защото запетаята е вътре в кавички.

Точка (например 2.50). Не добавяйте валутни символи, интервали, „лв.“, „€“ и др. – подавате чисто число. Не подавайте стойности с повече от 2 (два) символа след десетичния разделител – това само ще увеличи обемът от данни, а няма да се отрази по никакъв начин върху информацията.

CSV трябва да е UTF-8 (без BOM по възможност). Използвайте стандартни двойни кавички за ограждане на стойности. Ако самата стойност съдържа двойни кавички, ги ескейпвайте (""). Не е необходимо да имате интервал между отделните стойности и след запетая между стойностите.

Пример за минимално коректен ред:
"10000","Хипермаркет Пример – бул. Европа 1","Кисело мляко 3.6%, BrandName, 500 г","PRD-12345","15","2.10","1.89"

Това е често срещан проблем при експорти/скриптове. Тъй като CSV е текстов, системата не може „по смисъл“ да разпознае, че колоните са разместени.

Препоръка: добавете автоматични проверки след генериране на CSV:

• валидирайте, че колоните съвпадат по име и позиция;
• проверете типове (цена → валидно десетично число; категория → валиден код и т.н.);
• пробно заредете файла в табличен редактор и визуално проверете първите/последните редове.

Уникалният ключ в системата е кодът на продукта, а не името му. Ако за един и същ артикул подавате различни кодове, в публичната част това ще се визуализира като дублирани продукти, което пречи на сравненията и ще обърка потребителите.

Препоръка: поддържайте стабилно единен продуктов код за даден артикул във всички обекти и във времето. Ако продуктът е различен (разфасовка, марка, серия) – отразете го и в наименованието, и с нов код. Еднаквите продукти в различни магазини на един и същи търговец задължително трябва да са с еднакви кодове.

Категоризацията не може да бъде валидирана машинно във всички случаи – разчитаме на коректно класифициране от търговеца. Неправилните категории водят до некоректни сравнения на портала.

Препоръка: внедрете вътрешно контролен списък за категоризация и използвайте актуалната номенклатура (изтегляйте я редовно от публичния endpoint за категории).

Технически е допустимо и не води до проблем в данните, но визуално в портала изглежда зле и затруднява четенето. Не преобразуваме служебно изписването от само главни букви на думи започващи с главна буква, защото има съкращения и марки, при които това ще доведе до грешки.

Препоръка: подавайте четими наименования, напр.

• ❌ КИСЕЛО МЛЯКО 3.6% BRANDNAME СИН ЕТИКЕТ 500 ГР
• ✅ Кисело мляко 3.6%, BrandName, син етикет – 500 г

ЕКАТТЕ трябва да е валиден 5-цифрен код. Името на обекта – разпознаваемо, до 500 символа. Твърде къси/нелогични имена или грешен ЕКАТТЕ водят до отхвърляне. ЕКАТТЕ кодовете имат водещи нули, които са задължителни!

Ако промо цената липсва, е 0 или е по-висока/равна на редовната, системата я игнорира (редът се приема без промоция). Уверете се, че промоцията е реално по-ниска.

Лимитът е до ~60 MB за файл. Няма лимит за брой редове, а единствено за размера на файла с данните. Приблизително това са около 1 000 000 реда (при стандартна дължина от 35 символа на имената на продуктите и обектите). При надвишаване системата връща грешка.

Ако не сте над лимита, а получавате „limit“ грешка, възможен е мрежов инцидент – уведомете ни, като приложите файла.

Зависи от дължината на текстовите полета. При типични дължини (100–150 байта на ред) очаквайте ориентировъчно ~70 до 100 хиляди реда за 10 MB.

Да, за защита от злоупотреби може да има минимални интервали между API заявки. При нормална употреба не би трябвало да ги достигнете. При тестове – ползвайте тестовата среда.

Не използвайте multipart/form-data, а подавайте CSV във тялото (body) на заявката. Добавете Authorization header с вашия токен.

Прегледайте API Swagger-ът, който е наличен в административния интерфейс.

Да. Системата е достъпна от цял свят през интернет. Ако срещнете ограничения, свържете се с нас (виж раздел „Поддръжка“).

Генерирането на Authorization token се извършва от всеки отделен потребител самостоятелно. Необходимо е да имате активен и одобрен акаунт в административния интерфейс на системата, след което от горния десен ъгъл на екрана избирате своя профил и през профила си генерирате нов Token (в долния десен край на екрана). Един потребител може да има повече от един Token. През същия екран можете да анулирате вече издадени Token-и.

Съобщението посочва редове и тип нарушение. Коригирайте източника (скрипт/експорт), генерирайте нов CSV и качете отново преди 12:00 ч. Ако крайният срок е изтекъл – корекции за днешния ден не се приемат.

Това означава, че има несъществени грешки само в конкретни редове (напр. невалиден код категория). Останалите са записани и публикувани. Частичното допълване на пропуснатите редове за същия ден не е възможно от страна на търговеца.

• Заглавия на колоните – идентични с указанията, в същия ред.
• Всички редове – в двойни кавички, разделени със запетаи, всеки запис на нов ред (реален LF/CRLF).
• ЕКАТТЕ – 5 цифри и валиден код; име на обект – разбираемо, да не е само с главни букви и ≤ 500 знака.
• Цени – числа с десетична точка, без валутни символи, до 2 символа след десетичния; промо цена (ако има) < редовна.
• Продуктов код – уникален и непроменящ се за артикула; няма дублиращи кодове за един и същ продукт.
• Категория – валиден код по номенклатура; актуализирани списъци.
• Файл ≤ 60 MB.
• Имена – четими, не UPPERCASE

• Скрипт, който сравнява headers и броя колони;
• Проверка за „липсващи“ кавички / незатворени полета;
• Валидация на типове (числа, дължини, празни задължителни полета);
• Извадка N първи / N последни реда за ръчен преглед;
• Проверка за дублиращи кодове на продукти за един и същ търговец.

• Акаунтът ви за тестовата среда (както и API token) са различни от тези на продукционната;
• Няма дневен „lock“ – можете да качвате многократно, тоест по повече от един файл на ден;
• Няма часово ограничение до 12:00 ч.;
• Данните не се публикуват публично;
• Подходяща е за разработка и автоматизирани тестове;
• Не използвайте реални цени, които не желаете да станат публично достояние при евентуален трансфер – ползвайте тестови данни;
• Не е възможна миграция на данни, които успешно сте качили на тестова среда към публичната;
• Ползвайте тестовата среда за разработка и dry-run преди продукционни промени!

Пишете на екипа на КЗП: [email protected]. Всички сигнали се разглеждат в писмен вид.

Моля, включете задължително:

• търговска верига (наименование на веригата, за която подавате данните – такова, каквото е програмата);
• потребител, с който подавате данните (user profile, не самият token);
• канал на подаване: Портал или API;
• дата и приблизителен час на опита;
• пълен текст на грешката (или HTTP статус);
• прикачете подадения CSV файл (точно този, който е върнат с грешка);
• при API: пример на заявката (без да издавате токена – поставете ***).

Не директно. Името, свързано с продуктови кодове, се използва за последователност в публичната част. При необходимост от корекция – пишете на [email protected].

Изгответе карта на съответствията между старите и новите кодове и поддържайте консистентност. Ако не е възможно – уведомете КЗП за период на преход, за да избегнем дублирания в публичната визуализация.

Не, няма как да стане автоматично. Системата приема стойностите като числа. Контролът е организационен – уверете се, че на датата на смяна всички източници са актуализирани.