Документация / Партнёрский API
API Tax Free
Интеграция магазина с Tax Free: поиск туристов по паспорту или QR-коду и оформление заявок по фискальному чеку.
Для подключения получите у команды Tax Free адрес окружения и индивидуальный API-ключ.
/api/v1/nationalities | Справочник стран | |
/api/v1/partner/tourists/lookup | Поиск туриста | |
/api/v1/partner/applications | Создание заявки |
Авторизация по API-ключу
Передавайте ключ в заголовке X-API-Key каждого партнёрского запроса. Отдельная авторизация и получение JWT не требуются.
X-API-Key: <API_KEY>
Content-Type: application/json
Accept: application/json| Разрешение ключа | Доступ |
|---|---|
tourists:lookup | Поиск существующего туриста и получение его QR. |
applications:create | Оформление заявки от имени магазина. |
Для создания заявки ключ должен быть привязан к активному сотруднику активной организации с подписанным договором. Обычному сотруднику нужна выбранная торговая точка. Организация определяется по ключу.
401. Быстрый старт
- Получите у команды Tax Free адрес окружения и API-ключ с нужными разрешениями.
- Задайте на сервере переменные
BASE_URLиAPI_KEY.BASE_URL— адрес без/api/v1и завершающего слеша. - Выполните запрос из примера. Для поиска нужен зарегистрированный турист; для оформления — реальный чек вашей организации.
# 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"
}'Примеры иллюстрируют структуру запроса. Паспорт, реквизиты и чек условные; замените их своими данными.
Справочник стран
/api/v1/nationalitiesБез ключа Возвращает объект nationalities: английский ключ → переведённое название. Для русских названий передайте Content-Language: ru.
curl --fail-with-body "$BASE_URL/api/v1/nationalities" \
--header 'Content-Language: ru'200 Успешный ответ
{
"nationalities": {
"Germany": "Германия",
"China": "Китай"
}
} Ответ сокращён. В nationality и bank_country передавайте английский ключ, например Germany.
Поиск туриста
/api/v1/partner/tourists/lookupНаходит существующего верифицированного туриста с допустимым гражданством и возвращает его QR. Укажите ровно один критерий:
{
"passport_number": "AB1234567"
}{
"qr_code": "12345678901"
}Поиск точный, с учётом регистра; пробелы по краям удаляются. Длина паспорта — до 100 байт, QR при поиске — до 256 байт. Метод не создаёт профиль или отсутствующий QR.
200 Турист найден
{
"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
/api/v1/partner/applications Передайте три обязательных объекта: tourist, refund и receipt. API найдёт или создаст туриста, проверит чек и оформит заявку.
{
"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 Заявка создана
{
"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.
Возврат на карту
{
"card_number": "1234567890123456"
}card_number — строка из 16–20 цифр, без пробелов и разделителей. Банковские реквизиты вместе с картой передавать нельзя.
Банковский перевод
{
"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 либо полный набор реквизитов. Эти варианты нельзя смешивать.
{
"ofd_type": "kofd",
"datetime": "20261020T120000",
"fiscal_mark": "797081722205",
"reg_number": "010103274190",
"sum": "4327.00"
}| Поле | Формат |
|---|---|
ofd_type | Идентификатор ОФД из списка ниже. |
datetime | YYYYMMDDTHHMMSS — дата и время с чека без пересчёта часового пояса. |
fiscal_markreg_number | Строки цифр. Сохраняйте начальные нули ФП и РНМ. |
sum | Положительная десятичная строка: до 15 цифр до точки, до двух после. Без экспоненты. |
Поддерживаемые ОФД
kofd / jusanbeelineoofd / kazakhtelecomofd1 / transtelecomaofd / amianwofdkaspirekassa Kaspi — фискальный чек. Buhta поддерживается только по полной ссылке. Неизвестный ОФД возвращает 422.
Работа с QR-кодами
| Поля ответа | Назначение |
|---|---|
qr_codeqr_code_base64 | QR заявки в ответе создания. В ответе поиска — QR туриста. |
tourist_qr_codetourist_qr_code_base64 | QR туриста в ответе создания, для следующих покупок. |
Изображения — PNG 256 × 256, стандартный base64 без префикса data URI. Для отображения добавьте префикс:
image.src = 'data:image/png;base64,' + data.qr_code_base64; Ответы партнёрских методов содержат Cache-Control: no-store.
Коды ошибок
Проверяйте HTTP-статус и поле code. Поле error содержит текст причины; errors возвращается массивом.
{
"code": "receipt_already_used",
"error": "Receipt has already been used",
"errors": []
}| HTTP | Код / причина |
|---|---|
| 401 | invalid_api_keyКлюч отсутствует, неверен, отозван или просрочен. |
| 403 | permission_deniedУ ключа нет разрешения на операцию. |
| 403 | partner_access_deniedПроверьте привязку ключа, сотрудника, организацию, договор и торговую точку. |
| 403 | tourist_not_eligibleПри оформлении: турист не верифицирован, заблокирован или гражданство не допускается. |
| 403 | tourist_not_verifiedПри поиске: турист не верифицирован или заблокирован. |
| 403 | nationality_not_eligibleПри поиске: гражданство отсутствует, неизвестно или входит в ЕАЭС. |
| 404 | tourist_not_foundТурист не найден; при оформлении — неизвестный QR. |
| 409 | tourist_qr_missingПри поиске: у туриста ещё нет QR. |
| 409 | tourist_data_conflictДанные расходятся с профилем; профиль неполон или удалён. |
| 409 | receipt_already_usedЧек уже связан с действующей заявкой. |
| 409 | creation_conflictКонкурентный конфликт данных. Можно повторить запрос. |
| 422 | invalid_requestНекорректный JSON, поля или обязательные данные. |
| 422 | invalid_lookupПередайте ровно один допустимый критерий поиска. |
| 422 | invalid_receiptНевалидный чек, ошибка чтения или будущая дата. |
| 422 | receipt_details_mismatchРеквизиты не совпадают с данными ОФД. |
| 422 | receipt_organization_mismatchБИН чека не совпадает с организацией ключа. |
| 503 | ofd_unavailableОФД временно недоступен. Можно повторить запрос. |
| 500 | internal_errorВнутренняя ошибка обработки или сохранения. |
Повторные запросы
Создание туриста, QR, реквизитов, заявки, позиций и связей выполняется одной транзакцией. При ошибке сохранения частичные данные откатываются. Один чек не создаёт несколько действующих заявок, в том числе при одновременных запросах.
- После
503 ofd_unavailableили409 creation_conflictзапрос можно повторить. - Если соединение оборвалось без ответа, результат может быть неизвестен. Повторный запрос к уже сохранённому чеку вернёт
409 receipt_already_used, а не новый QR. - После административного удаления заявки чек можно оформить заново.