API документация

Мы предоставляем простой REST API способ получать курсы валют по отношению к кыргызскому сому. API располагает несколькими эндпоинтами, которые предназначены для разных сценариев использования курсов валют.

Определения

Объект	Описание
API токен	Уникальных ключ, который используется для идентификации пользователя API через Bearer Token Authorization Header.
Код валюты	Трехсимвольный ISO код валюты.
Базовая валюта	Валюта, по отношению к которой возвращается курс. Пример: 1 доллар = 88 сомов, сом будет являться Базовой валютой.

HTTP коды ответов

API использует стандартные HTTP коды для индикации успешности или неуспешности запроса.

Код	Описание
200 OK	Успешный запрос. Данные возвращены в формате JSON.
400 Bad Request	Ошибка валидации. Проверьте параметры запроса.
401 Unauthorized	Отсутствует или неверный API токен. Проверьте заголовок Authorization.
403 Forbidden	Нет доступа к API или превышен лимит запросов в месяц. Обратитесь в поддержку.
500 Internal Server Error	Внутренняя ошибка сервера. Попробуйте позже или обратитесь в поддержку.

Авторизация и API токен

Вам необходимо зарегистрироваться и получить API Bearer Token. Затем вы должны отправлять его с каждым запросом к нашему API.

Базовый API URL:

https://data.fx.kg/api/v1/

Пример API Bearer Token:

L5HoneK2u1F61cYy6IX6SLv7BkaYKVB2iZzfVBa9

Вы можете получить больше информации о том, как использовать токен по этой ссылке.

Примеры ошибок авторизации:

401 Unauthorized (неверный токен):

{
    "message": "Unauthenticated."
}

403 Forbidden (превышен лимит запросов):

{
    "messages": "Превышено количество запросов в месяц. Обратитесь в поддержку."
}

403 Forbidden (нет доступа к API):

{
    "messages": "Нет доступа к API. Обратитесь в поддержку."
}

Real-time курсы

Курсы валют в режиме реального времени.

Средние курсы валют

GET https://data.fx.kg/api/v1/average

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

{
    "updated_at": null,
    "type": null,
    "buy_usd": "87.00",
    "sell_usd": "87.70",
    "buy_eur": "96.30",
    "sell_eur": "97.30",
    "buy_rub": "1.10",
    "sell_rub": "1.12",
    "buy_kzt": "0.14",
    "sell_kzt": "0.20"
}

Лучшие курсы валют

GET https://data.fx.kg/api/v1/best

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

{
    "updated_at": null,
    "type": null,
    "buy_usd": "87.00",
    "sell_usd": "87.70",
    "buy_eur": "96.30",
    "sell_eur": "97.30",
    "buy_rub": "1.10",
    "sell_rub": "1.12",
    "buy_kzt": "0.14",
    "sell_kzt": "0.20"
}

Текущие курсы коммерческих банков

GET https://data.fx.kg/api/v1/current

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

[
    {
        "id": 1,
        "title": "MBANK",
        "official_title": "ОАО \"MBANK\"",
        "slug": "mbank",
        "website_url": "https://www.mbank.kg",
        "rates": [
            {
                "organization_id": 1,
                "base_currency_id": 1,
                "created_at": "2023-06-15T02:35:05.000000Z",
                "updated_at": "2023-06-15T02:35:05.000000Z",
                "is_current": 1,
                "type": "cashless",
                "buy_usd": "87.00",
                "sell_usd": "87.64",
                "buy_eur": "94.50",
                "sell_eur": "95.50",
                "buy_rub": "1.020",
                "sell_rub": "1.070",
                "buy_kzt": "0.130",
                "sell_kzt": "0.200",
                "buy_uzs": null,
                "sell_uzs": null,
                "buy_cny": "11.00",
                "sell_cny": "14.00",
                "buy_gbp": null,
                "sell_gbp": null,
                "buy_try": null,
                "sell_try": null
            },
            {
                "organization_id": 1,
                "base_currency_id": 1,
                "created_at": "2023-06-15T02:40:04.000000Z",
                "updated_at": "2023-06-15T02:40:04.000000Z",
                "is_current": 1,
                "type": "regular",
                "buy_usd": "87.40",
                "sell_usd": "88.10",
                "buy_eur": "94.50",
                "sell_eur": "95.50",
                "buy_rub": "1.030",
                "sell_rub": "1.060",
                "buy_kzt": "0.130",
                "sell_kzt": "0.200",
                "buy_uzs": null,
                "sell_uzs": null,
                "buy_cny": null,
                "sell_cny": null,
                "buy_gbp": null,
                "sell_gbp": null,
                "buy_try": null,
                "sell_try": null
            }
        ]
    },
    {
        "id": 2,
        "title": "Оптима Банк",
        "official_title": "ОАО \"Оптима Банк\"",
        "slug": "optima-bank",
        "website_url": "https://www.optimabank.kg",
        "rates": [
            {
                "organization_id": 2,
                "base_currency_id": 1,
                "created_at": "2023-06-15T03:05:31.000000Z",
                "updated_at": "2023-06-15T03:05:31.000000Z",
                "is_current": 1,
                "type": "regular",
                "buy_usd": "87.50",
                "sell_usd": "88.00",
                "buy_eur": "94.40",
                "sell_eur": "95.40",
                "buy_rub": "1.030",
                "sell_rub": "1.055",
                "buy_kzt": "0.135",
                "sell_kzt": "0.205",
                "buy_uzs": null,
                "sell_uzs": null,
                "buy_cny": null,
                "sell_cny": null,
                "buy_gbp": null,
                "sell_gbp": null,
                "buy_try": null,
                "sell_try": null
            },
            {
                "organization_id": 2,
                "base_currency_id": 1,
                "created_at": "2023-06-15T03:05:31.000000Z",
                "updated_at": "2023-06-15T03:05:31.000000Z",
                "is_current": 1,
                "type": "cashless",
                "buy_usd": "87.30",
                "sell_usd": "87.64",
                "buy_eur": "94.40",
                "sell_eur": "95.40",
                "buy_rub": "1.010",
                "sell_rub": "1.080",
                "buy_kzt": "0.135",
                "sell_kzt": "0.205",
                "buy_uzs": null,
                "sell_uzs": null,
                "buy_cny": null,
                "sell_cny": null,
                "buy_gbp": null,
                "sell_gbp": null,
                "buy_try": null,
                "sell_try": null
            }
        ]
    },
    {...}
]

Текущие курсы Национального Банка

GET https://data.fx.kg/api/v1/central

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

{
    "created_at": "2023-06-26T10:00:34.000000Z",
    "updated_at": "2023-06-26T10:00:34.000000Z",
    "is_current": 1,
    "usd": "87.3231",
    "eur": "95.1036",
    "kzt": "0.1940",
    "rub": "1.0323",
    "gbp": "110.8733",
    "dkk": "12.7144",
    "inr": "1.0641",
    "cad": "66.1026",
    "cny": "12.1595",
    "krw": "0.0666",
    "nok": "8.0359",
    "xdr": "117.0534",
    "sek": "8.0974",
    "chf": "96.9444",
    "jpy": "6.1007",
    "amd": "2.2608",
    "byr": "0.3402",
    "mdl": "4.8381",
    "tjs": "7.9993",
    "uzs": "0.0076",
    "uah": "2.3873",
    "kwd": "283.8142",
    "huf": "2.5562",
    "czk": "3.9963",
    "nzd": "53.5139",
    "pkr": "0.3047",
    "aud": "58.3895",
    "try": "3.4586",
    "azn": "51.3520",
    "sgd": "64.5340",
    "afn": "1.0170",
    "bgn": "48.4238",
    "brl": "18.2885",
    "gel": "33.2439",
    "aed": "23.7673",
    "irr": "0.0208",
    "myr": "18.6675",
    "mnt": "0.0253",
    "twd": "2.8099",
    "tmt": "24.9424",
    "pln": "21.3464",
    "sar": "23.2718",
    "byn": "29.2948"
}

ПЛАТНАЯ ПОДПИСКА

Исторические данные PRO

Мы располагаем архивом изменения курсов валют с 2013 года. Вы можете получить курсы за любой конкретный день, добавив параметр date к запросу.

Требования:

Активная платная подписка
Лимит: 100 исторических запросов в месяц
Формат даты: Y-m-d (например, 2025-01-15)
Дата не может быть в будущем

Таймзона: все даты в ответах API возвращаются в формате UTC.

Параметр запроса

Параметр	Тип	Описание
date	string	Дата в формате `Y-m-d`. Необязательный. При отсутствии возвращаются текущие данные.

Поддерживаемые эндпоинты

Параметр date поддерживается на следующих эндпоинтах:

GET https://data.fx.kg/api/v1/average?date=2025-01-15

GET https://data.fx.kg/api/v1/best?date=2025-01-15

GET https://data.fx.kg/api/v1/current?date=2025-01-15

GET https://data.fx.kg/api/v1/central?date=2025-01-15

HTTP коды: 200 (успех), 400 (неверный формат даты), 401 (не авторизован), 403 (нет подписки/превышен лимит)

Детальная история курсов

Возвращает все записи курсов валют за указанный день, отсортированные от старых к новым. Можно отфильтровать по организации и валюте.

GET https://data.fx.kg/api/v1/rates/history?date=2025-01-15

Параметры запроса:

Параметр	Обязательный	Описание
date	да	Дата в формате `Y-m-d` (например, `2025-01-15`)
organization_id	нет	ID организации для фильтрации
currency	нет	Код валюты: `usd`, `eur`, `rub`, `kzt`, `uzs`, `cny`, `gbp`, `try`. При указании возвращаются только курсы выбранной валюты.
type	нет	Тип курса: `regular` (наличный) или `cashless` (безналичный). По умолчанию: `regular`.

Примеры с фильтрами:

GET https://data.fx.kg/api/v1/rates/history?date=2025-01-15&organization_id=1

GET https://data.fx.kg/api/v1/rates/history?date=2025-01-15&currency=usd

GET https://data.fx.kg/api/v1/rates/history?date=2025-01-15&organization_id=1&currency=eur

GET https://data.fx.kg/api/v1/rates/history?date=2025-01-15&type=cashless

Response (200 OK):

[
    {
        "organization_id": 1,
        "organization": "MBANK",
        "type": "regular",
        "created_at": "2025-01-15T03:35:05.000000Z",
        "buy_usd": "87.40",
        "sell_usd": "88.10",
        "buy_eur": "94.50",
        "sell_eur": "95.50",
        "buy_rub": "1.030",
        "sell_rub": "1.060",
        "buy_kzt": "0.130",
        "sell_kzt": "0.200",
        "buy_uzs": null,
        "sell_uzs": null,
        "buy_cny": null,
        "sell_cny": null,
        "buy_gbp": null,
        "sell_gbp": null,
        "buy_try": null,
        "sell_try": null
    },
    {
        "organization_id": 2,
        "organization": "Оптима Банк",
        "type": "regular",
        "created_at": "2025-01-15T05:05:31.000000Z",
        "buy_usd": "87.50",
        "sell_usd": "88.00",
        ...
    },
    {...}
]

Response с фильтром currency=usd (200 OK):

[
    {
        "organization_id": 1,
        "organization": "MBANK",
        "type": "regular",
        "created_at": "2025-01-15T03:35:05.000000Z",
        "buy_usd": "87.40",
        "sell_usd": "88.10"
    },
    {...}
]

Примеры ошибок

403 Forbidden (нет платной подписки):

{
    "messages": "Доступ к историческим данным доступен только для платных подписок."
}

403 Forbidden (превышен лимит исторических запросов):

{
    "messages": "Превышен лимит исторических запросов (100 в месяц)."
}

400 Bad Request (неверный формат даты):

{
    "message": "Неверный формат даты. Используйте формат Y-m-d (например, 2025-01-15)."
}

Общие данные

Дополнительные эндпоинты, которые могут быть полезны.

Список банков с курсами валют

Возвращает список коммерческих банков с их текущими курсами валют.

GET https://data.fx.kg/api/v1/organizations

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

[
    {
        "id": 1,
        "title": "MBANK",
        "official_title": "ОАО \"MBANK\"",
        "slug": "mbank",
        "website_url": "https://www.mbank.kg",
        "rates": [
            {
                "organization_id": 1,
                "base_currency_id": 1,
                "created_at": "2023-06-15T02:35:05.000000Z",
                "updated_at": "2023-06-15T02:35:05.000000Z",
                "is_current": 1,
                "type": "regular",
                "buy_usd": "87.40",
                "sell_usd": "88.10",
                "buy_eur": "94.50",
                "sell_eur": "95.50",
                "buy_rub": "1.030",
                "sell_rub": "1.060",
                "buy_kzt": "0.130",
                "sell_kzt": "0.200"
            }
        ]
    },
    {...}
]

Response объекты:

Поле	Описание
id	Внутренний ID организации. Используется в других эндпоинтах для фильтрации.
title	Краткое название банка.
official_title	Официальное юридическое название банка.
slug	Уникальный строковый идентификатор банка.
website_url	Официальный сайт банка.
rates	Массив текущих курсов валют банка. Может содержать несколько записей (наличный и безналичный курсы).

Список доступных валют

GET https://data.fx.kg/api/v1/currencies

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

[
    {
        "id": 1,
        "code": "KGS",
        "title": "Кыргызский сом"
    },
    {
        "id": 2,
        "code": "USD",
        "title": "Доллар США"
    },
    {
        "id": 3,
        "code": "EUR",
        "title": "Евро"
    },
    {
        "id": 4,
        "code": "RUB",
        "title": "Российский рубль"
    },
    {
        "id": 5,
        "code": "KZT",
        "title": "Казахский тенге"
    },
    {...}
]

Response объекты:

Объект	Описание
id	Внутренний ID валюты.
code	Трехсимвольный ISO код валюты.
title	Название валюты на русском языке.

Список свободно конвертируемых валют

GET https://data.fx.kg/api/v1/currencies/convertible

HTTP коды: 200 (успех), 401 (не авторизован), 403 (нет доступа/лимит)

Response (200 OK):

[
    {
        "id": 2,
        "code": "USD",
        "title": "Доллар США"
    },
    {
        "id": 3,
        "code": "EUR",
        "title": "Евро"
    },
    {
        "id": 4,
        "code": "RUB",
        "title": "Российский рубль"
    },
    {
        "id": 5,
        "code": "KZT",
        "title": "Казахский тенге"
    }
]

Response объекты:

Объект	Описание
id	Внутренний ID валюты.
code	Трехсимвольный ISO код валюты.
title	Название валюты на русском языке.