Получение данных

Общая информация

В структуре Data API используются разные конечные точки для получения разных видов данных:

  • /balance/get — для получения данных о балансах по проектам мерчанта (в настоящее время поддерживается получение информации только о балансах типа OUT);
  • /operations/get — для получения данных об операциях за заданный период;
  • /operations/get-by-payment — для получения данных об операциях конкретного платежа.

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

Контроль балансов

Для получения данных о балансах по проектам мерчанта следует отправлять запросы к конечной точке /balance/get. В этих запросах должны указываться параметры token (токен учётной записи) и signature (подпись). В ответах на такие запросы содержатся сведения о текущем состоянии балансов типа OUT.

Сведения о каждом балансе включают в себя наименование баланса и доступную сумму в валюте этого баланса, причём валюта указывается в качестве названия параметра, а сумма — в качестве значения параметра ("<валюта>": "<сумма>").

Рис.: Пример данных из запроса на получение данных о балансах и ответа на этот запрос

// Тело запроса
{
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"dQcIbv94Z0nPTYX9glSCi...jqInXqYrY9bzkfcBGQ=="
}

// Тело ответа
{
    "balance": [
        {
            "name": "Project_Cosmo1_balance_RUB",
            "RUB": "1010750"
        },
        {
            "name": "Project_Cosmo1_balance_USD",
            "SGD": "310099"
        },
        {
            "name": "Project_Cosmo1_balance_EUR",
            "EUR": "113128"
        }
    ],
    "signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w=="
}

Общий контроль операций

Для получения данных об операциях за заданный период по проектам мерчанта следует отправлять запросы к конечной точке /operations/get. При это необходимо учитывать следующее:

  1. В каждом запросе должны использоваться следующие объекты и параметры:
    • interval — объект с информацией о границах временно́го интервала, к которому относятся последние действия (и соответствующие обновления информации) по целевым операциям:
      • from — дата и время начала интервала, в формате ГГГГ-ММ-ДД чч:мм:сс;
      • to — дата и время окончания интервала, в формате ГГГГ-ММ-ДД чч:мм:сс;
    • token — токен учётной записи;
    • signature — подпись запроса, составленная после указания целевых параметров.
  2. Для фильтрации операций по их отношению к проектам используется параметр project_id, а также учитывается наличие прав доступа к проектам через токен, указанный в запросе. По умолчанию, если в запросе не указан этот параметр, в ответе от платёжной платформы отправляются данные об операциях по всем проектам, к которым есть права доступа через используемый токен. При необходимости получить данные по конкретным проектам (одному или нескольким), в параметре project_id следует указать идентификаторы этих проектов (через запятую с пробелом, если необходимо указать несколько идентификаторов; например, 4, 12).
  3. Для использования часового пояса, отличного от заданного по умолчанию UTC +00:00, используется параметр tz. Выбор часового пояса с помощью этого параметра влияет на то, какие операции попадают в заданный интервал времени в объекте interval, и на значения параметров в ответе, связанных с датой и временем — например, operation_created_at и operation_completed_at. Часовой пояс в параметре tz указывается через время смещения в формате UTC (например, +10:30) или через название в соответствии с базой данных часовых поясов IANA Time Zone Database (например, Asia/Singapore).
  4. Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, используется параметр limit. Этот параметр может принимать значения в диапазоне 01000 и по умолчанию равен 1000, при этом количество записей, возвращаемых в ответе, может быть меньше заданного значения.

    При необходимости получить информацию более чем о тысяче операций, следует отправлять несколько запросов и в каждом из них использовать параметр offset. Этот параметр определяет величину сдвига для отбора операций. Когда в запросе указываются оба параметра — и limit, и offset, то сначала операции пропускаются в количестве, заданном значением offset, а затем записи с информацией о следующих операциях возвращаются в ответе в количестве, не превышающем значения limit.

    Например, если необходимо получить информацию о 1125 операциях, то в первом запросе можно указать "limit": "1000" и "offset": "0", а во втором — "limit": "125" и "offset": "1000".

  5. Для фильтрации данных об операциях по различным атрибутам используется параметр fields. По умолчанию, если в запросе не указан этот параметр, в ответе от платёжной платформы отправляется типовой набор данных для каждой операции. Если же необходимо получить данные по конкретным атрибутам (одному или нескольким), в параметре fields следует указать названия этих атрибутов.

    Атрибуты указываются через запятую с пробелом (если необходимо указать несколько названий), при этом их можно указывать в произвольном порядке, но в ответах используется фиксированный порядок данных. Полный перечень атрибутов представлен в спецификации Data API — в виде параметров объекта operations в описании формата ответа на запрос к конечной точке /operations/get. В этом описании атрибуты указаны в порядке, который используется по умолчанию, и отмечены как обязательные.

  6. При необходимости фильтрации данных по типу операции следует указать название одной из доступных операций в параметре operation_type: sale, auth, capture, cancel, recurring, reversal, refund или payout.

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

Рис.: Пример данных из запросов на получение данных об операциях и ответа на один из таких запросов

// Тело запроса на получение данных о 1000 операциях (с отсчётом от 0) 
{
  "project_id":[
    0,
    1
  ],
  "interval": {
    "from":"2020-08-01 00:00:00",
    "to":"2020-08-28 23:59:59"
  },
  "limit":"1000",
  "offset": "0",
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"yPu0wYr2BoV5...MzQtRkvdC0y=="
}

// Тело запроса на получение данных о следующих 125 операциях (с отсчётом от 1000)
{
  "project_id":[
    0,
    12
  ],
  "interval": {
    "from":"2020-08-01 00:00:00",
    "to":"2020-08-28 23:59:59"
  },
  "limit":"125",
  "offset": "1000"
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"sd0fr5YsdBVmJ...grkglpeXJg=="
}

// Тело ответа на первый запрос
{
    "operations": [
        // сведения об операции
        { 
            "operation_completed_at": "2020-08-01T08:28:48+00:00",
            "customer_ip": "87.245.207.226",
            "operation_type": "sale",
            "operation_status": "success",
            "operation_id": "6435212162442",
            "operation_created_at": "2018-08-01T08:28:47+00:00",
            "payment_id": "EP06c1-b285",
            "account_number": "424242******4242",
            "payment_description": "",
            "payment_method_type": "visa",
            "payment_method_name": "visa",
            "provider_name": "Decta New Mock Edition",
            "provider_date": "2020-08-01 10:34:24",
            "project_id": "11",
            "shipment_date": "",
            "mid": "3940459",
            "sum_initial": {
                "amount": 1000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RUB"
            }
        },

        // сведения о следующей операции
        { 
            "operation_completed_at": "2020-08-01T08:28:48+00:00",
            "customer_ip": "87.245.207.226",
            "operation_type": "sale",
            "operation_status": "success",
            "operation_id": "6435212162442",
            "operation_created_at": "2018-08-01T08:28:47+00:00",
            "payment_id": "EP06c1-b285",
            "account_number": "424242******4242",
            "payment_description": "",
            "payment_method_type": "visa",
            "payment_method_name": "visa",
            "provider_name": "Decta New Mock Edition",
            "provider_date": "2018-02-07 10:34:24",
            "project_id": "11",
            "shipment_date": "",
            "mid": "3940459",
            "sum_initial": {
                "amount": 1000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RUB"
            }
        },
        // сведения об остальных операциях
        ...
    ],
    "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw=="
}

Контроль операций по отдельным платежам

Для получения данных обо всех операциях конкретного платежа следует использовать запрос к конечной точке /operations/get-by-payment. В этом запросе должны указываться параметры payment_id (идентификатор целевого платежа), token (токен учётной записи) и signature (подпись). В ответе на такой запрос содержатся сведения об операциях целевого платежа.

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

// Тело запроса
{
  "payment_id":"PID_25467851461-2147",
  "token":"VmJQhaXILAnZWTKmqwSd3j",
  "signature":"JM+YWmTL7uGn26IgZWTKmqwSd3jJM+YWmTL7uGn26IglUOMzQtRkvdC0yaq030+eNXVtJjjtgrkglpeXJg=="
}

// Тело ответа
{
  "operations": [
    {
      "arn": "",
      "operation_completed_at": "2019-11-22T13:13:04+00:00",
      "operation_type": "refund",
      "operation_id": "2747253065470",
      "amount": 221,
      "currency": "RUB",
      "operation_created_at": "2019-11-22T13:13:04+00:00",
      "rrn": "803817399309"
    },
    {
      "arn": "",
      "operation_completed_at": "2019-11-22T13:09:03+00:00",
      "operation_type": "capture",
      "operation_id": "2747253065469",
      "amount": 1621,
      "currency": "RUB",
      "operation_created_at": "2019-11-22T13:09:03+00:00",
      "rrn": "000000248370"
    },
    {
      "arn": "",
      "operation_completed_at": "2019-11-22T13:06:40+00:00",
      "operation_type": "auth",
      "operation_id": "2747253065468",
      "amount": 2000,
      "currency": "RUB",
      "operation_created_at": "2019-11-22T13:06:38+00:00",
      "rrn": "000047769105"
    }
  ],
  "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7bABSdjLPkQXkMjQ7tqoB8TCJR1Oh2xyiA8y1WihDJ4ljz/Hv7NkQFujSnvw=="
}