Tenderland API

Начало работы

Ключ хранится только на сервере в переменной TENDERLAND_API_KEY. Не добавляйте его в HTML, клиентский JavaScript, URL интерфейса, логи или репозиторий.

API принимает ключ и в параметре apiKey, но для Kortex используем HTTP-заголовок: так секрет не попадает в историю браузера и журналы прокси.

Проверка подключения

curl "https://tenderland.ru/Api/v1/User/GetStatistic" \
  -H "Tenderland-Api-Key: $TENDERLAND_API_KEY"

Серверный запрос на Node.js

const response = await fetch(
  `${process.env.TENDERLAND_API_BASE_URL}/User/GetStatistic`,
  {
    headers: {
      "Tenderland-Api-Key": process.env.TENDERLAND_API_KEY
    }
  }
);

if (!response.ok) {
  throw new Error(`Tenderland API: ${response.status}`);
}

const statistic = await response.json();

Модули и способы интеграции

Выгрузка из автопоиска

1. Получите автопоиски. Вызовите Dictionary/GetAutosearchList и выберите Id.
2. Получите формы отчётов. Вызовите Dictionary/GetExportViewList и выберите Id отчёта.
3. Создайте задачу. Передайте autosearchId и exportViewId в Export/Create.
4. Читайте последовательно. Передавайте полученный exportId в Export/Get, увеличивая offset на batchSize.

# 1. Создать задачу
curl "https://tenderland.ru/Api/v1/Export/Create?autosearchId=123&exportViewId=456&batchSize=100&format=json" \
  -H "Tenderland-Api-Key: $TENDERLAND_API_KEY"

# 2. Прочитать страницы: 0, 100, 200...
curl "https://tenderland.ru/Api/v1/Export/Get?exportId=789&offset=0" \
  -H "Tenderland-Api-Key: $TENDERLAND_API_KEY"

Инкрементальная синхронизация

Чтобы получать только новые или изменённые записи, храните контрольную точку в Kortex и при следующем запуске передавайте один из параметров:

Параметры searchAfterCreateDate, searchAfterUpdateDate и searchAfterId взаимоисключающие. Для защиты от записей с одинаковым временем храните идентификаторы обработанных сущностей и делайте загрузку идемпотентной.

Поиск

По номеру или идентификатору

Search/Get принимает через запятую реестровые номера или идентификаторы Tenderland. Для организаций при подключённом модуле «API Ревизор» можно передавать ОГРН, ИНН или название.

curl "https://tenderland.ru/Api/v1/Search/Get?keys=TL12345&entityType=tender&strictMatch=true&hideSensitiveApiData=true" \
  -H "Tenderland-Api-Key: $TENDERLAND_API_KEY"

Динамический поиск

POST Search/Find относится к отдельному модулю «API Поиск». Надёжнее всего создать автопоиск в интерфейсе Tenderland, получить его JSON через Search/GetAutosearch, а затем менять нужные фильтры на сервере Kortex.

curl -X POST "https://tenderland.ru/Api/v1/Search/Find" \
  -H "Tenderland-Api-Key: $TENDERLAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["tender_regNumber", "tender_name", "tender_endDate"],
    "filters": {"and": []},
    "interval": [0, 1],
    "pageSize": 30,
    "skip": 0
  }'

Для последующей полной выгрузки результатов укажите pageSize: 0, возьмите идентификатор поисковой сессии и передайте его как sessionId в Export/Create.

Webhook

1. В панели Tenderland откройте «Панель управления API» → «Интеграция».
2. Выберите автопоиск, отчёт, JSON или XML, интервал 15/30/60 минут и размер страницы.
3. Укажите HTTPS-адрес обработчика Kortex и при необходимости включите обновления и GZIP.
4. Сохраняйте данные идемпотентно и возвращайте HTTP 200 только после успешной обработки всей страницы.

Один цикл содержит не более пяти страниц. Если обработка длится дольше 30 секунд или ответ отличается от 200, цикл останавливается и следующая попытка начинается с той же страницы.

Каталог методов

Файлы и связанные данные

Тип сущности задаётся параметром entityTypeId: 1 — тендер, 2 — контракт, 3 — позиция плана. Идентификатор сущности имеет формат TL\d+.

Сначала вызывайте File/GetEntityFileList. Файл со storageId > 0 можно скачать через File/Get. Если storageId отсутствует, используйте sourceLink. ZIP из File/GetAll может быть неполным, потому что Tenderland хранит на своих серверах не все документы.

Отчёты могут объединять тендеры, лоты, контракты и позиции планов. В многолотовых и совместных закупках строки повторяются для сохранения связей, поэтому ключ дедупликации должен учитывать тип сущности и лот.

Лимиты

Суточные счётчики сбрасываются в 00:00 МСК, месячные — первого числа в 00:00 МСК. Единица данных — тендерный лот, контракт, позиция плана или один файл.

Ошибки и повторные запросы

Для 429 и 500 используйте ограниченное число повторов с увеличивающейся задержкой. Ошибки 400 и 403 автоматически не повторяйте: сначала исправьте запрос, доступ или лимит.

Замечания к редакции v1

• В таблице Export/Get для offset указано значение больше нуля, но официальный пример начинает с offset=0. Первую страницу запрашиваем с нуля.
• В строке запроса Export/Create встречается опечатка oderBy; описание параметра и остальные примеры используют orderBy.
• Для результата Search/Find документация использует оба имени: sessionId в таблице и id в примере. До проверки реальным ответом обработчик должен принимать оба варианта.
• Методы поиска сейчас работают только с JSON, а Organizations/GetEgrul всегда возвращает XML.