TAX FREEДля разработчиков

Документация / Партнёрский API

API Tax Free

Интеграция магазина с Tax Free: поиск туристов по паспорту или QR-коду и оформление заявок по фискальному чеку.

Протокол
HTTPS · REST
Формат
JSON
Авторизация
X-API-Key

Для подключения получите у команды Tax Free адрес окружения и индивидуальный API-ключ.

GET/api/v1/nationalitiesСправочник стран
POST/api/v1/partner/tourists/lookupПоиск туриста
POST/api/v1/partner/applicationsСоздание заявки

Авторизация по API-ключу

Передавайте ключ в заголовке X-API-Key каждого партнёрского запроса. Отдельная авторизация и получение JWT не требуются.

HTTP · заголовки запроса
X-API-Key: <API_KEY>
Content-Type: application/json
Accept: application/json
Разрешение ключаДоступ
tourists:lookupПоиск существующего туриста и получение его QR.
applications:createОформление заявки от имени магазина.

Для создания заявки ключ должен быть привязан к активному сотруднику активной организации с подписанным договором. Обычному сотруднику нужна выбранная торговая точка. Организация определяется по ключу.

Ключ храните на сервере. Не включайте его в браузерный код, публичные репозитории или URL. Используйте HTTPS. Ключ действует только в выдавшем его окружении; отозванный или просроченный ключ возвращает 401.

Быстрый старт

  1. Получите у команды Tax Free адрес окружения и API-ключ с нужными разрешениями.
  2. Задайте на сервере переменные BASE_URL и API_KEY. BASE_URL — адрес без /api/v1 и завершающего слеша.
  3. Выполните запрос из примера. Для поиска нужен зарегистрированный турист; для оформления — реальный чек вашей организации.
cURL · запрос с вашего сервера
# BASE_URL — адрес окружения без /api/v1 и завершающего слеша
# API_KEY — индивидуальный ключ из переменной окружения
curl --fail-with-body --request POST \
  "$BASE_URL/api/v1/partner/tourists/lookup" \
  --header "X-API-Key: $API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "passport_number": "AB1234567"
}'

Примеры иллюстрируют структуру запроса. Паспорт, реквизиты и чек условные; замените их своими данными.

Справочник стран

GET/api/v1/nationalitiesБез ключа

Возвращает объект nationalities: английский ключ → переведённое название. Для русских названий передайте Content-Language: ru.

cURL
curl --fail-with-body "$BASE_URL/api/v1/nationalities" \
  --header 'Content-Language: ru'

200 Успешный ответ

JSON
{
  "nationalities": {
    "Germany": "Германия",
    "China": "Китай"
  }
}

Ответ сокращён. В nationality и bank_country передавайте английский ключ, например Germany.

Гражданство туриста — вне ЕАЭС. Kazakhstan, Russia, Belarus, Armenia и Kyrgyzstan присутствуют в общем справочнике, но не допускаются при оформлении Tax Free. На страну банка это ограничение не распространяется.

Поиск туриста

POST/api/v1/partner/tourists/lookup

Разрешение: tourists:lookup

Находит существующего верифицированного туриста с допустимым гражданством и возвращает его QR. Укажите ровно один критерий:

По паспорту
{
  "passport_number": "AB1234567"
}
По QR туриста
{
  "qr_code": "12345678901"
}

Поиск точный, с учётом регистра; пробелы по краям удаляются. Длина паспорта — до 100 байт, QR при поиске — до 256 байт. Метод не создаёт профиль или отсутствующий QR.

200 Турист найден

JSON
{
  "id": "00000000-0000-0000-0000-000000000001",
  "first_name": "John",
  "last_name": "Smith",
  "patronymic": null,
  "passport_number": "AB1234567",
  "nationality": "Germany",
  "qr_code": "12345678901",
  "qr_code_base64": "<PNG_BASE64>"
}

Если турист не найден, API вернёт 404 tourist_not_found. Нового туриста можно создать сразу при оформлении заявки.

Создание заявки Tax Free

POST/api/v1/partner/applications

Разрешение: applications:create

Передайте три обязательных объекта: tourist, refund и receipt. API найдёт или создаст туриста, проверит чек и оформит заявку.

JSON · новый турист, карта и ссылка на чек
{
  "tourist": {
    "first_name": "John",
    "last_name": "Smith",
    "passport_number": "AB1234567",
    "nationality": "Germany"
  },
  "refund": {
    "card_number": "1234567890123456"
  },
  "receipt": {
    "link": "https://cabinet.kofd.kz/consumer?i=797081722205&f=010103274190&s=4327.00&t=20241208T180727"
  }
}

Ссылка в примере не гарантирует доступный чек. Для оформления используйте реальный чек организации, к сотруднику которой привязан ключ.

Поля объекта tourist

Поле / типПравило
passport_numberstring · до 100 символовПаспорт. Передайте ровно одно из passport_number или qr_code.
qr_codestring · до 32 символовQR существующего туриста. Неизвестный QR не создаёт профиль.
first_namestring · до 255 символовИмя. Обязательно для нового туриста.
last_namestring · до 255 символовФамилия. Обязательно для нового туриста.
patronymicstring · до 255 символовОтчество. Необязательно.
nationalitystringДля нового туриста — английский ключ из справочника стран, вне ЕАЭС.
Повторная покупка. Достаточно passport_number либо qr_code. Если переданы ФИО и гражданство, они должны совпадать с профилем. Данные не перезаписываются; неизвестный QR возвращает 404.

Новый турист создаётся верифицированным: проверку паспорта выполняет доверенный магазин. Существующий неверифицированный или заблокированный профиль автоматически не повышается в статусе.

201 Заявка создана

JSON
{
  "application_id": "00000000-0000-0000-0000-000000000010",
  "tourist_id": "00000000-0000-0000-0000-000000000001",
  "tourist_created": true,
  "card_id": "00000000-0000-0000-0000-000000000020",
  "organization_id": "00000000-0000-0000-0000-000000000030",
  "status": "created",
  "created_at": "2026-10-29T08:00:00Z",
  "total_price": 20000,
  "total_nds_sum": 2758.62,
  "receipt_link": "https://cabinet.kofd.kz/consumer?...",
  "qr_code": "11111111111141118111111111111111",
  "qr_code_base64": "<PNG_BASE64>",
  "tourist_qr_code": "12345678901",
  "tourist_qr_code_base64": "<PNG_BASE64>"
}

tourist_created показывает, создан ли новый турист. total_price — сумма позиций, участвующих в возврате; она может отличаться от полной суммы чека. total_nds_sum — рассчитанный НДС. Суммы и идентификаторы в примере условные.

Способы возврата

Выберите ровно один способ для каждой заявки: банковская карта или перевод по IBAN.

Возврат на карту

JSON
{
  "card_number": "1234567890123456"
}

card_number — строка из 16–20 цифр, без пробелов и разделителей. Банковские реквизиты вместе с картой передавать нельзя.

Банковский перевод

JSON
{
  "iban": "DE89370400440532013000",
  "recipient_name": "John Smith",
  "swift_bic": "COBADEFFXXX",
  "bank_name": "Commerzbank",
  "bank_country": "Germany",
  "bank_address": "Frankfurt am Main, Germany",
  "recipient_address": "Berlin, Germany",
  "correspondent_bank": "Если есть"
}

Для IBAN все поля примера обязательны, кроме correspondent_bank. Проверяются формат и контрольное число IBAN; SWIFT/BIC должен содержать 8 или 11 символов. IBAN и BIC приводятся к верхнему регистру.

recipient_name, bank_name и correspondent_bank — до 255 символов; адреса — до 512. bank_country — английский ключ справочника стран.

Совпадающие реквизиты переиспользуются. При изменении банковских данных прежние заявки сохраняют свои реквизиты. Полные реквизиты в ответе не возвращаются.

Фискальный чек

Передайте полную ссылку ОФД в receipt.link либо полный набор реквизитов. Эти варианты нельзя смешивать.

JSON · чек по реквизитам
{
  "ofd_type": "kofd",
  "datetime": "20261020T120000",
  "fiscal_mark": "797081722205",
  "reg_number": "010103274190",
  "sum": "4327.00"
}
ПолеФормат
ofd_typeИдентификатор ОФД из списка ниже.
datetime YYYYMMDDTHHMMSS — дата и время с чека без пересчёта часового пояса.
fiscal_mark
reg_number
Строки цифр. Сохраняйте начальные нули ФП и РНМ.
sum Положительная десятичная строка: до 15 цифр до точки, до двух после. Без экспоненты.

Поддерживаемые ОФД

kofd / jusanbeelineoofd / kazakhtelecomofd1 / transtelecomaofd / amianwofdkaspirekassa

Kaspi — фискальный чек. Buhta поддерживается только по полной ссылке. Неизвестный ОФД возвращает 422.

Данные ОФД сверяются с реквизитами запроса, а БИН чека — с организацией ключа. Чек с будущей датой отклоняется.

Работа с QR-кодами

Поля ответаНазначение
qr_code
qr_code_base64
QR заявки в ответе создания. В ответе поиска — QR туриста.
tourist_qr_code
tourist_qr_code_base64
QR туриста в ответе создания, для следующих покупок.

Изображения — PNG 256 × 256, стандартный base64 без префикса data URI. Для отображения добавьте префикс:

JavaScript · отображение QR из ответа
image.src = 'data:image/png;base64,' + data.qr_code_base64;

Ответы партнёрских методов содержат Cache-Control: no-store.

Коды ошибок

Проверяйте HTTP-статус и поле code. Поле error содержит текст причины; errors возвращается массивом.

JSON · пример ошибки 409
{
  "code": "receipt_already_used",
  "error": "Receipt has already been used",
  "errors": []
}
HTTPКод / причина
401invalid_api_key

Ключ отсутствует, неверен, отозван или просрочен.

403permission_denied

У ключа нет разрешения на операцию.

403partner_access_denied

Проверьте привязку ключа, сотрудника, организацию, договор и торговую точку.

403tourist_not_eligible

При оформлении: турист не верифицирован, заблокирован или гражданство не допускается.

403tourist_not_verified

При поиске: турист не верифицирован или заблокирован.

403nationality_not_eligible

При поиске: гражданство отсутствует, неизвестно или входит в ЕАЭС.

404tourist_not_found

Турист не найден; при оформлении — неизвестный QR.

409tourist_qr_missing

При поиске: у туриста ещё нет QR.

409tourist_data_conflict

Данные расходятся с профилем; профиль неполон или удалён.

409receipt_already_used

Чек уже связан с действующей заявкой.

409creation_conflict

Конкурентный конфликт данных. Можно повторить запрос.

422invalid_request

Некорректный JSON, поля или обязательные данные.

422invalid_lookup

Передайте ровно один допустимый критерий поиска.

422invalid_receipt

Невалидный чек, ошибка чтения или будущая дата.

422receipt_details_mismatch

Реквизиты не совпадают с данными ОФД.

422receipt_organization_mismatch

БИН чека не совпадает с организацией ключа.

503ofd_unavailable

ОФД временно недоступен. Можно повторить запрос.

500internal_error

Внутренняя ошибка обработки или сохранения.

Повторные запросы

Создание туриста, QR, реквизитов, заявки, позиций и связей выполняется одной транзакцией. При ошибке сохранения частичные данные откатываются. Один чек не создаёт несколько действующих заявок, в том числе при одновременных запросах.

  • После 503 ofd_unavailable или 409 creation_conflict запрос можно повторить.
  • Если соединение оборвалось без ответа, результат может быть неизвестен. Повторный запрос к уже сохранённому чеку вернёт 409 receipt_already_used, а не новый QR.
  • После административного удаления заявки чек можно оформить заново.