Перейти к основному контенту

Общие сведения

В запросах и ответах формат JSON. В заголовках HTTP запроса Content-Type: application/json.

Формат данных.

Дата. Все передаваемые и принимаемые даты имеют формат yyyyMMddhhmmss или yyyyMMdd.

Период. Период задается двумя датами, как правило, from и to. Если даты не содержат времени, то периодом считать время с начала суток даты from и до окончания суток даты to. Например, при запросе отчета за период с 20170101 по 20170101, результатом будет все за сутки 01.01.2017. При запросе за период с 20170101 по 20170102, в результат будет входить период времени за двое суток: 01.01.2017 и 02.01.2017.

Запятая или точка? В качестве разделителя, в нецелых числах, использовать только точку. 

Запросы на ресурсы

Общая часть функционала апи разбита на ресурсы (resource) и действия (actions).
Общий формат url для запроса: https://{host}/{resource}/{action}

Общий формат запроса
{
    "Body":{
        "PageSize": 10,
        "CurrentPage": 20,
        "Sort": "idTerminal, date asc, amount desc",
        "Params":{
            "param1":"value1",
            "param2":"value2"
        }
    }
}

Теги:

  • PageSize - размер страницы QueryData. Не обязательное. По умолчанию 1000;
  • CurrentPage - текущая страница данных QueryData. Не обязательное. По умолчанию 0;
  • Sort - сортировка по полям (только для запросов где в ответе QueryData). Перечисляются через запятую поля для сортировки. После каждого поля можно указать asc или desc.
Общий формат ответа

Пример 1.

{
    "Code":0,
    "Message":"Success!",
    "ResultData": {
        "field1":"value1",
        "field2":"value2"
    }
}

Пример 2.

{
    "Code": 0,
    "Message": "OK",
    "QueryData": [
        {
            "Rows": []
        }
    ],
    "Metadata": {
        "PageCount": 1,
        "PageSize": 47,
        "PageIndex": 0,
        "RowCount": 47
    }
}

Секция Metadata есть только в случае, если в ответе табличные данные QueryData.

Теги:

  • PageCount - кол-во страниц данных;
  • PageSize - размер выданной страницы. Если это полная страница, то будет равен значению PageSize в запросе. Если это остаточные данные, то будет меньше PageSize;
  • PageIndex - текущая страница. Нумерация с 0;
  • RowCount - общее кол-во строк данных на всех страницах.

Совместимость

Изменений в запросах и ответах мы разделяем на обратно совместимые с клиентскими приложениями обратно несовместимые.

Обратно несовместимые. Стараемся минимизировать. Если все таки требуется внести обратно несоместимые изменения, уведомляем клиентов, обозначаем сроки, даем рекомендации. В любом случае, внезапного прекращения функциональности не допускаем.

  • удаление запроса
  • удаление тегов из запроса
  • удаление тегов в ответах
  • изменения адреса (эндпоинта) запроса
  • изменение в бизнес-процессах повлекшие изменение логики работы запросов
  • изменение регистра тегов в ответах (amount не равно Amount)

Обратно совместимые. Отражаются в документации. Уведомления не рассылаются.

  • Длиннный или короткий формат даты (20230415000000 или 20230415)
  • Добавление новых запросов
  • Добавление в запрос новых не обязательных тегов 
  • Добавление в ответ новых тегов, не влияющих на ход того-или иного бизнес-процесса (например, добавилось новое поле в отчете)
  • изменение порядка следования тегов в запросах и ответах находящихся на одном уровне (сортировка тегов)
  • изменение регистра тегов в запросах (amount равно Amount, так как парсинг запросов регистронезависимый)

URL

Sandbox Production
https://api.portal.tech24.kz/ https://api.portal.kassa24.kz/

Наверх