API для больших списков

Как получить ключ

Войдите через аккаунт Krafta — по почте или через Telegram — и создайте ключ в кабинете. Ключ бесплатный и работает сразу.

Запрос

Передавайте ключ в заголовке Authorization. Адрес API — https://tasnif.krafta.uz/api/v1. Ответ всегда в JSON.

Authorization: Bearer $TASNIF_KEY

Поиск

GET https://tasnif.krafta.uz/api/v1/search?q=…&limit=10

Принимает всё, что и строка поиска на сайте: слова на русском, узбекском или английском, штрихкод, код ИКПУ, код упаковки, код ТН ВЭД. limit — сколько результатов вернуть (от 1 до 30, по умолчанию 10).

Тот же запрос на curl, 1С, Python, JavaScript и PHP. Ключ программа берёт из переменной окружения TASNIF_KEY, а в 1С — из строки «Ключ».

curl "https://tasnif.krafta.uz/api/v1/search?q=капучино&limit=1" \
  -H "Authorization: Bearer $TASNIF_KEY"

Ответ

{
  "query": "капучино",
  "type": "words",
  "ordered_by": "ai",
  "results": [
    {
      "ikpu": "10202001010000002",
      "name": {
        "ru": "Безалкогольные напитки, кофе и кофесодержащие напитки, приготовленные в заведении общественного питания",
        "uz": "Alkogolsiz ichimliklar, qahva va qahva tarkibli ichimliklar, umumiy ovqatlanish shaxobchalarida tayyorlangan"
      },
      "kind": "catering",
      "active": true,
      "branded": false,
      "match": "text",
      "exact": false,
      "category": {
        "code": "10202001010",
        "name": { "ru": "Безалкогольные напитки", "uz": "Alkogolsiz ichimliklar" }
      },
      "invoice_blocked_since": null
    }
  ],
  "usage": { "ai_word_lookups_left_today": 999 }
}

Целый список

POST https://tasnif.krafta.uz/api/v1/batch

До 1 000 позиций за раз, ответы — в том же порядке. limit — сколько результатов на каждую позицию (от 1 до 10, по умолчанию 3). Штрихкоды и коды отвечаются за секунды, а список из 1 000 позиций со словами — около четырёх минут: поставьте HTTP-клиенту таймаут не меньше пяти минут.

curl "https://tasnif.krafta.uz/api/v1/batch" \
  -H "Authorization: Bearer $TASNIF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": ["4780029010025", "капучино", "2701 19"], "limit": 1}'

Ответ

{
  "results": [
    {
      "query": "4780029010025",
      "type": "barcode",
      "ordered_by": "search",
      "results": [
        {
          "ikpu": "04818001001038001",
          "name": { "ru": "Бумага туалетная: Viva Classik, сорт серый …", "uz": "Hojatxona qog’ozi: Viva Classik …" },
          "kind": "goods",
          "active": true,
          "branded": true,
          "match": "barcode",
          "exact": true,
          "category": { "code": "04818001001", "name": { "ru": "Бумага туалетная", "uz": "Hojatxona qog’ozi" } },
          "invoice_blocked_since": null
        }
      ]
    },
    { "query": "капучино", "type": "words", "ordered_by": "ai", "results": [ … ] },
    { "query": "2701 19", "type": "customs_code", "ordered_by": "search", "results": [ … ] }
  ],
  "usage": { "ai_word_lookups_left_today": 998 }
}

Всё о коде

GET https://tasnif.krafta.uz/api/v1/codes/{ikpu}

Названия на русском и узбекском, путь в каталоге, единицы измерения, штрихкод, льгота и коды упаковки для чека. Для отключённого кода — действующие коды той же категории в поле replacements.

curl "https://tasnif.krafta.uz/api/v1/codes/10202001010000002" \
  -H "Authorization: Bearer $TASNIF_KEY"

Что в ответе

type

Что это был за запрос: words — слова, barcode — штрихкод, code — код ИКПУ, package_code — код упаковки, customs_code — код ТН ВЭД, code_prefix — начало кода.

ordered_by

ai — порядок подобрал ИИ; search — обычный порядок поиска.

ikpu

Код ИКПУ, 17 цифр.

name.ru, name.uz

Название на русском и на узбекском (латиницей).

kind

goods — товар, service — услуга, catering — блюдо или напиток, приготовленные в заведении.

active

false — код отключён, в чеке его указывать нельзя.

branded

true — код конкретной марки, false — общий код категории.

exact

true — найден напрямую: по самому коду, штрихкоду или коду упаковки. false — лучшее совпадение, его стоит проверить.

match

Как найден: text — по словам; ikpu, barcode, package — по коду, штрихкоду, коду упаковки; tnved — по товарной позиции ТН ВЭД; same_maker — товар того же производителя (самого штрихкода в каталоге нет); same_category — действующий код той же категории.

category

Субпозиция каталога: код и название.

invoice_blocked_since

Дата (YYYY-MM-DD), с которой этот общий код нельзя указывать в электронном счёте-фактуре (у маркируемых товаров — и в чеке), иначе null. Такой код в ответе стоит сразу под подробным кодом той же категории.

usage.ai_word_lookups_left_today

Сколько запросов словами с порядком ИИ осталось на сегодня.

Лимиты

• Числа — штрихкоды, коды ИКПУ, коды упаковки и ТН ВЭД — без ограничений.
• Первые 1 000 запросов словами в день упорядочивает ИИ. Дальше ответы приходят в обычном порядке поиска — без ошибок, просто без ИИ. День считается по ташкентскому времени.
• Не больше 300 запросов в минуту; список до 1 000 позиций считается одним запросом.
• Лимиты — на аккаунт: все его ключи делят их. Сколько осталось, видно в кабинете.
• Нужно больше — напишите нам.

Ошибки

Ошибка приходит с кодом HTTP и таким телом:

{ "error": { "code": "rate_limited", "message": "Too many requests this minute. …" } }

400 bad_request

В запросе ошибка: нет q, строка длиннее 200 символов или в списке больше 1 000 позиций.

401 unauthorized

Ключа нет, он неверный или отозван.

404 not_found

Такого кода в каталоге нет.

429 rate_limited

Больше 300 запросов в минуту. Подождите минуту (заголовок Retry-After).

502 server_error

Сбой на нашей стороне. Повторите через минуту.