# Получение данных {#ru_dbl_using_api}

статья о порядке работы с отдельными конечными точками Data API, с описаниями и примерами структур данных в запросах и ответах

**На уровень выше:**[Использование Data API](ru_dbl_api_protocol.md)

## Общая информация {#ru_dbl_using_api_overview}

В структуре Data API используются разные конечные точки для получения разной информации:

-   `[/balance/get](ru_dbl_using_api.md)`— для получения информации о балансах по проектам мерчанта \(в настоящее время поддерживается получение информации только о балансах типа OUT\);
-   `[/chargeback/list](ru_dbl_using_api.md)` — для получения информации об опротестованиях, соответствующих заданным условиям;
-   `[/chargeback/get](ru_dbl_using_api.md)` — для получения информации по конкретному опротестованию;
-   `[/fraud/list](ru_dbl_using_api.md)` — для получения информации об операциях, признанных мошенническими;
-   `[/financial-reporting/operations](ru_dbl_using_api.md)` — для получения информации о финансовых результатах по операциям за заданный период \(включая информацию о начисленных комиссиях\);
-   `[/operations/get](ru_dbl_using_api.md)` — для получения информации о выполнении операций за заданный период;
-   `[/operations/get-by-payment](ru_dbl_using_api.md)` — для получения информации об операциях конкретного платежа.

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

## Контроль балансов {#ru_dbl_using_api_balances}

Для получения информации о балансах по проектам мерчанта следует отправлять запросы к конечной точке [/balance/get](https://api-data.ecommpay.com/balance/post-balance-get).

В этих запросах должны указываться параметры `token` \(токен учётной записи Dashboard\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). В ответах на такие запросы содержатся сведения о текущем состоянии балансов типа OUT.

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

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

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

## Общий контроль опротестований {#ru_dbl_using_api_chargeback_list}

Для получения информации об опротестованиях \(chargebacks\), которые относятся к проектам мерчанта и соответствуют заданным условиям, следует отправлять запросы к конечной точке [/chargeback/list](https://api-data.ecommpay.com/chargeback/post-chargeback-list).

В работе с этими запросами необходимо учитывать следующее:

1.  В каждом запросе должны указываться параметры `token` \(токен учётной записи Dashboard с ролью `Risks` или `Merchant admin` и правами доступа ко всем целевым проектам\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\).
2.  Для фильтрации данных об опротестованиях могут использоваться любые из параметров в объекте `filter`.

    В этом объекте каждый из периодов задаётся как объект с двумя параметрами строкового типа `from` \(начало\) и `to` \(окончание\). Остальные параметры могут содержать как одно, так и несколько значений, заданных в виде массива или строки с разделением через запятую с пробелом. Исключением является параметр `provider_id`, который может быть задан только в виде массива. Параметры фильтрации можно указывать в произвольном порядке. Если они не указываются вовсе, в ответе от платёжной платформы отправляются данные обо всех опротестованиях по проектам, к которым есть доступ у используемой учётной записи.

    В объекте `filter` могут указываться следующие объекты и параметры:

    -   `report_date` — период, в котором информация об опротестовании впервые поступила в платформу \(формат каждой границы периода — `ГГГГ-ММ-ДД`\);
    -   `respond_by` — период, к которому относится последний день срока предоставления ответа по опротестованию \(формат каждой границы периода — `ГГГГ-ММ-ДД чч:мм:сс` с возможностью не указывать время\);
    -   `chb_completed_at` — период, в котором опротестованию присвоен итоговый статус \(формат каждой границы периода — `ГГГГ-ММ-ДД чч:мм:сс` с возможностью не указывать время\);
    -   `project_id` — идентификатор проекта;
    -   `chargeback_id` — идентификатор опротестования, полученный от Ecommpay;
    -   `chargeback_stage` — этап работы с опротестованием \(`Chargeback`, `Representment`, `Pre-Arbitration attempt`, `Pre-Arbitration response` и `Arbitration`; [подробнее об этапах](ru_faq_chargebacks.md#section_plz_g54_p5b)\);
    -   `arn` — acquirer reference number \(идентификатор операции, присвоенный эквайером\);
    -   `card` — номер платёжной карты, использованной при проведении платежа;
    -   `card_type` — код платёжной системы \(`visa` для Visa и `mc` для Mastercard\);
    -   `reason_code` — числовой код причины опротестования, полученный от платёжной системы;
    -   `operation_id` — идентификатор оспариваемой операции;
    -   `status` — статус опротестования.
3.  Для ограничения количества записей с информацией об опротестованиях, возвращаемых в одном ответе, можно использовать объект `pagination` с двумя параметрами: `limit` — максимальное количество возвращаемых записей \(не меньше `1`\) и `offset` — величина сдвига для отбора записей \(с отсчётом с `0`\). Например, если необходимо получить информацию о 5 опротестованиях, пропустив первые 20, то в запросе можно указать `"limit": 5` и `"offset": 20`. При отсутствии этих параметров используются значения по умолчанию: `limit` — `20`, `offset` — `0`.

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

```language-json
// Тело запроса
{
    "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
    "filter": {
        "report_date": {
            "from": "2024-01-01",
            "to": "2024-02-01"
        },
        "status": [
            "WON",
            "PARTIALLY WON"
        ]
    },
    "signature": "DNqOZOCxNlXu3bENrDPuEE8fSJLWDNM/...UqhiEUoC5VcNFw=="
}

// Тело ответа
{
  "operations": [
    {
      "chargeback_id": "11201",
      "charged_amount": "5000",
      "channel_amount": "5000",
      "case_id": "142",
      "project_id": "1234",
      "operation_id": "12330123485431",
      "report_date": "2024-01-31",
      "respond_by": "2024-02-04 23:59:59",
      "rev_date": null,
      "tr_date_time": "2024-01-13 17:00:56",
      "chb_completed_at": "2024-02-21 00:00:00",
      "chb_amount": "50.00",
      "chb_settlement_amount": "50.00",
      "rev_indicator": null,
      "chb_ccy": "USD",
      "chb_settlement_ccy": "USD",
      "charged_currency": "USD",
      "channel_currency": "USD",
      "eci_sli": "7",
      "reason_code": "10.4",
      "card_type": "VISA",
      "merchant_id": "10000123",
      "card": "431422******0056",
      "arn": "74312342013012340041234",
      "status": "WON",
      "chb_amount_in_usd": "50.0000",
      "merchant_name": "Cosmoshop_on_Mars",
      "order_id": "1234123412345",
      "operation_type": "sale",
      "auth_code": "061230",
      "card_holder": "JANE DOE",
      "issuer_country": "UK",
      "chargeback_stage": "Arbitration",
      "pre_arbitration_report_date": "2024-02-06",
      "pre_arbitration_amount": "50.00",
      "pre_arbitration_ccy": "USD",
      "arbitration_report_date": "2024-03-06",
      "arbitration_amount": "50.00",
      "arbitration_ccy": "USD",
      "representment_amount": "50.00",
      "representment_ccy": "USD"
    },
    ...
  ],
  "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
}
```

## Контроль отдельных опротестований {#ru_dbl_using_api_chargeback_get}

Для получения информации об отдельных опротестованиях \(chargebacks\) следует использовать запросы к конечной точке [/chargeback/get](https://api-data.ecommpay.com/chargeback/post-chargeback-get).

В работе с этими запросами необходимо учитывать следующее:

1.  В каждом запросе должны указываться параметры `token` \(токен учётной записи Dashboard с ролью `Risks` или `Merchant admin` и правами доступа ко всем целевым проектам\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\).
2.  Дополнительно должен указываться по крайней мере один из следующих идентификаторов в объекте `filter`:

    -   `chargeback_id` — идентификатор опротестования, полученный от Ecommpay;
    -   `arn` — идентификатор операции, присвоенный эквайером \(acquirer reference number\);
    -   `operation_id` — идентификатор операции в платёжной платформе.
    Если в запросе не указан ни один из этих идентификаторов или указаны противоречащие друг другу, то в ответ выдаётся ошибка.


В ответе на корректный запрос содержатся данные о конкретном опротестовании.

```language-json
// Тело запроса
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "filter": {
        "operation_id": 87980010093051
    },
  "signature": "VoOJxpMge0uBN22gZxf3BhE+5wlCaU...y+KM1lQ=="
}

// Тело ответа
{
  "chargeback": {
    "chargeback_id": "11201",
    "charged_amount": "5000",
    "channel_amount": "5000",
    "case_id": "142",
    "project_id": "1234",
    "operation_id": "12330123485431",
    "report_date": "2024-01-31",
    "respond_by": "2024-02-04 23:59:59",
    "rev_date": null,
    "tr_date_time": "2024-01-13 17:00:56",
    "chb_completed_at": "2024-02-21 00:00:00",
    "chb_amount": "50.00",
    "chb_settlement_amount": "50.00",
    "rev_indicator": null,
    "chb_ccy": "USD",
    "chb_settlement_ccy": "USD",
    "charged_currency": "USD",
    "channel_currency": "USD",
    "eci_sli": "7",
    "reason_code": "10.4",
    "card_type": "VISA",
    "merchant_id": "10000123",
    "card": "431422******0056",
    "arn": "74312342013012340041234",
    "status": "WON",
    "chb_amount_in_usd": "50.00",
    "merchant_name": "Cosmoshop_on_Mars",
    "order_id": "1234123412345",
    "operation_type": "sale",
    "auth_code": "061230",
    "card_holder": "JANE DOE",
    "issuer_country": "UK",
    "chargeback_stage": "Arbitration",
    "pre_arbitration_report_date": "2024-02-06",
    "pre_arbitration_amount": "50.00",
    "pre_arbitration_ccy": "USD",
    "arbitration_report_date": "2024-03-06",
    "arbitration_amount": "50.00",
    "arbitration_ccy": "USD",
    "representment_amount": "50.00",
    "representment_ccy": "USD"
  },
  "signature": "lSiQYO06cTBi5Hos2/sWjWOZocZhDr...gtmmKfB2g=="
}
```

## Контроль мошеннических операций {#ru_dbl_using_api_fraud}

Для получения информации об операциях, признанных мошенническими на стороне платёжных систем, следует отправлять запросы к конечной точке [/fraud/list](https://api-data.ecommpay.com/fraud/post-fraud-list).

Стоит учитывать, что с помощью таких запросов нельзя получать данные об операциях, признанными подозрительными на стороне Ecommpay, а в работе с этими запросами необходимо учитывать следующее:

1.  В каждом запросе должны указываться параметры `token` \(токен учётной записи Dashboard с ролью `Risks` или `Merchant admin` и правами доступа ко всем целевым проектам\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\).
2.  Для фильтрации данных об операциях могут использоваться любые из параметров в объекте `filter`:

    -   `received_on` — период, в который в платёжной платформе зарегистрирована информация о признании операции мошеннической на стороне платёжной системы;
    -   `purchase_date` — период, в котором операции присвоен итоговый статус;
    -   `fraud_report_date` — период, в котором эмитент был уведомлён о признании операции мошеннической;
    -   `issuer_country` — код страны эмитента, выпустившего карту \(массив из одного или нескольких кодов в формате ISO 3166-1 alpha-2\);
    -   `has_chargebacks` — указатель наличия по крайней мере одного зарегистрированного в платёжной платформе опротестования по операции, признанной мошеннической;
    -   `customer_id` — идентификатор пользователя в рамках проекта;
    -   `card_type` — код платёжной системы \(`mc` для Mastercard и `visa` для Visa\).
    В этом объекте любой период должен задаваться через массив строк с границами временного интервала, например `"purchase_date": [ "2025-12-31 00:00:00", "2026-01-07 23:59:59" ]`.

3.  Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, можно использовать объект `pagination` с двумя параметрами: `limit` — максимальное количество возвращаемых записей \(не меньше `1`\) и `offset` — величина сдвига для отбора записей \(с отсчётом с `0`\). Например, если необходимо получить информацию о 5 операциях, пропустив первые 20, то в запросе можно указать `"limit": 5` и `"offset": 20`. При отсутствии этих параметров используются значения по умолчанию: `limit` — `20`, `offset` — `0`.

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

```language-json
// Тело запроса
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "signature": "dfsder34fuk7sJ...grdfht5gJg==",
  "filter": {
    "received_on": [
      "2026-01-01 00:00:00",
      "2026-02-01 23:59:59"
    ],
    "issuer_country": [
      "GB"
    ]
  },
  "pagination": {
    "limit": 5,
    "offset": 20
  }
}

// Тело ответа
{
  "operations": [
    {
      "payment_id": "cosmopayment78",
      "operation_id": 6435212169999,
      "tr_amount": "580.00",
      "tr_ccy": "USD",
      "account_number": "431422******0056",
      "payment_method_type": "visa",
      "row_updated_at": "2026-01-01 05:30:30",
      "customer_id": "earthling1232400",
      "project_name": "cosmoshop.earth",
      "project_id": "123",
      "arn": "40216364365007272011473",
      "fraud_type": "6",
      "fraud_report_date": "2026-02-10",
      "issuer_country": "GB",
      "received_on": "2026-02-11",
      "purchase_date": "2026-02-01",
      "channel_amount_in_usd": "580.00",
      "issuer_bank_name": "Intergalactic Bank",
      "bin": "123456",
      "country_by_ip": "GB",
      "customer_email": "earthling@earth.earth",
      "report_and_purchase_date_difference": 9
    }
  ],
  "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
}
```

## Общий контроль финансовых результатов операций {#ru_dbl_using_api_financial-statements}

Для получения информации о финансовых результатах по операциям за заданный период \(включая информацию о начисленных комиссиях\) следует отправлять запросы к конечной точке [/financial-reporting/operations](https://api-data.ecommpay.com/operations/post-financial-reporting-operations). Эта информация может дополнять информацию о выполнении операций \([подробнее](ru_dbl_using_api.md)\) и использоваться для итогового анализа и сверок.

В работе с запросами на получение информации о финансовых результатах по операциям необходимо учитывать следующее:

1.  В каждом запросе должны использоваться следующие объекты и параметры:
    -   `token` — токен учётной записи Dashboard;
    -   `signature` — подпись запроса, составленная после указания целевых параметров \([подробнее](ru_platform_signature.md)\);
    -   `operation_completed_at` — объект с информацией о границах временно́го интервала, в который было закончено выполнение целевых операций \(с учётом последних действий и обновлений информации по ним\):

        -   `from` — дата и время начала интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`;
        -   `to` — дата и время окончания интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`;
        **Прим.:** Можно запрашивать информацию только об операциях, завершённых за последние 30 дней.

    -   `tz` — указатель часового пояса, задаваемый через время смещения в формате UTC \(например, +10:30\) или через название пояса в соответствии с базой данных IANA Time Zone Database \(например, Asia/Singapore\).
2.  Для фильтрации операций по проектам и \(или\) провайдерам используются массивы `project_id` и `provider_id`, а также учитывается наличие прав доступа к проектам через токен, указанный в запросе. По умолчанию, если в запросе не указаны эти массивы, в ответе от платёжной платформы отправляются данные об операциях по всем проектам \(к которым есть права доступа через используемый токен\) и всем провайдерам, задействованным при выполнении этих операций. Если необходимо получить данные по конкретным проектам и провайдерам, в массивах `project_id` и `provider_id` следует указать их идентификаторы \(через запятую с пробелом, если необходимо указать более одного идентификатора; например, `4, 12`\).
3.  Для получения информации о конкретных операциях используется массив `operation_id`. По умолчанию, если в запросе не указан этот массив, в ответе от платёжной платформы отправляются данные обо всех операциях, соответствующих заданным условиям. Если необходимо получить данные по конкретным операциям \(одной или нескольким\), в массиве `operation_id` следует указать идентификаторы этих операций \(через запятую с пробелом, если необходимо указать более одного идентификатора; например, `6435212162442, 6435212162443`\).
4.  Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, используется параметр `limit`. Этот параметр может принимать значения в диапазоне `0`–`1000` и по умолчанию равен `1000`, при этом количество записей, возвращаемых в ответе, может быть меньше заданного значения.

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

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


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

```language-json
// Тело запроса на получение данных о 1000 операциях (с отсчётом от 0) 
{
  "project_id": [11],
  "operation_completed_at": {
    "from": "2024-09-01 00:00:00",
    "to": "2024-09-30 23:59:59"
  },
  "tz": "Indian/Mauritius",
  "limit": 1000,
  "offset": 0,
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "YsrkgdBr5peXJgJ...glVmsd0f=="
}

// Тело ответа на запрос
 
{
  "data": [
    {
      "operation_completed_at": "2024-09-29T22:08:19+0000",
      "transaction_id": "81194009089601",
      "operation_id": "81194009122865",
      "provider_payment_id": "0040000028207224",
      "payment_id": "1994-1312",
      "arn": "70114165164100000032105",
      "rrn": "451912040334",
      "auth_appr_code": "611887",
      "operation_type": "sale",
      "operation_status": "success",
      "tran_region": "domestic",
      "tariff_region": "EU",
      "proc_region": "Visa Europe",
      "security_level": "SEC",
      "operation_amount": 2098.00,
      "operation_currency": "GBP",
      "billing_conversion_rate": 0.00,
      "billing_amount": 2098.00,
      "billing_currency": "GBP",
      "total_interchange_fee": -4.20,
      "total_scheme_fee": -0.64,
      "auth_msc_fee": 0.000000,
      "clearing_msc_fee": -3.785649,
      "total_msc_fee": -3.78,
      "hold_amount": 0.00,
      "project_id": 11,
      "project_url": "https://www.company.com",
      "merchant_name": "COMPANY NAME",
      "mid": "70000000",
      "terminal_id": "70000000",
      "mcc_code": "4722",
      "legal_country": "GB",
      "payment_method_name": "visa",
      "product_type": "Consumer",
      "account_funding_source": "debit",
      "account_number": "475144******1111",
      "card_product": "Visa classic",
      "issuer_country": "GB",
      "customer_id": "1436462",
      "card_holder": "CARD HOLDER"
    },
    // сведения об остальных операциях...
  ],  
  "signature": "sncpEB75H...3jTS=="
}
```

## Общий контроль выполнения операций {#ru_dbl_using_api_operations}

Для получения информации о выполнении операций за заданный период следует отправлять запросы к конечной точке [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get). Эту информацию можно использовать в ознакомительных целях и для развёрнутого анализа выполнения операций, в то время как для итогового анализа и сверок можно использовать информацию о финансовых результатах по операциям \(с учётом начисленных комиссий; [подробнее](ru_dbl_using_api.md)\).

В работе с запросами на получение информации о выполнении операций необходимо учитывать следующее:

1.  В каждом запросе должны использоваться следующие объекты и параметры:
    -   `token` — токен учётной записи Dashboard;
    -   `signature` — подпись запроса, составленная после указания целевых параметров \([подробнее](ru_platform_signature.md)\);
    -   `interval` — объект с информацией о границах временно́го интервала, к которому относятся целевые операции \(с учётом последних действий и обновлений информации по ним\):

        -   `from` — дата и время начала интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`;
        -   `to` — дата и время окончания интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`.
        **Прим.:** Если от имени одной учётной записи Dashboard в течение 10 секунд в платформу поступает более одного запроса на информацию за период, превышающий 180 дней, то эти запросы обрабатываются поэтапно, с тайм-аутом в 10 секунд.

2.  Для фильтрации операций по проектам используется массив `project_id`, а также учитывается наличие прав доступа к проектам через токен, указанный в запросе. По умолчанию, если в запросе не указан этот массив, в ответе от платёжной платформы отправляются данные об операциях по всем проектам, к которым есть права доступа через используемый токен. Если необходимо получить данные по конкретным проектам, в массиве `project_id` следует указать идентификаторы этих проектов \(через запятую с пробелом, если необходимо указать более одного идентификатора; например, `4, 12`\).
3.  Для указания часового пояса используется параметр `tz`. По умолчанию, если в запросе не указан этот параметр, используется часовой пояс учётной записи Dashboard, ассоциированной с токеном из параметра `token`. Выбор часового пояса с помощью этого параметра влияет на то, какие операции попадают в заданный интервал времени в объекте `interval`, и на значения параметров в ответе, связанных с датой и временем, например `operation_created_at` и `operation_completed_at`. Часовой пояс в параметре `tz` указывается через время смещения в формате UTC \(например, `+10:30`\) или через название в соответствии с базой данных часовых поясов IANA Time Zone Database \(например, `Asia/Singapore`\).
4.  Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, используется параметр `limit`. Этот параметр может принимать значения в диапазоне `0`–`1000` и по умолчанию равен `1000`, при этом количество записей, возвращаемых в ответе, может быть меньше заданного значения.

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

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

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

    Названия целевых параметров указываются в массиве через запятую с пробелом, при этом их можно указывать в произвольном порядке, но в ответах используется фиксированный порядок, заданный в спецификации. Полный перечень параметров, которые могут выдаваться в ответах на запросы этого типа, также представлен в спецификации — в виде параметров объекта `operations` в описании формата ответа на запрос к конечной точке [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get). В этом описании параметры приводятся в фиксированном порядке, который не может изменяться, при этом параметры, используемые по умолчанию, отмечены как обязательные.

6.  Для получения данных об операциях по конкретным типам и \(или\) статусам используются параметры `operation_type` и `operation_status`.По умолчанию, если в запросе не указаны эти параметры, в ответе отправляются данные об операциях всех допустимых типов и статусов. Если указывать эти параметры, то в качестве их значений следует использовать названия конкретных типов и статусов операций, через запятую с пробелом при указании более чем одного названия. Актуальный перечень типов и статусов операций представлен [в модели проведения платежей](ru_platform_payment_model.md).

    Каждый из параметров `operation_type` и `operation_status` может задаваться как строка \(если необходимо указать одно значение\) и как массив строк \(если необходимо указать одно или множество значений\).

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


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

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

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

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

// Тело ответа на первый запрос
{
    "operations": [
        // сведения об операции
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "192.0.2.255",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2024-04-04T08:28:47+00:00",            
            "provider_date": "2024-04-04 10:34:24",
            "shipment_date": "",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "arn": "12304191169003210000234",
            "rrn": "001045563840",
            "payment_provider_code": "0",
            "payment_provider_message": "Success"
        },

        // сведения о следующей операции
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "198.51.100.0",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2024-04-04T08:28:47+00:00",
            "provider_date": "2024-04-04 10:34:24",
            "shipment_date": "",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "arn": "30407191169003210010678",
            "rrn": "128905563823",
            "payment_provider_code": "0",
            "payment_provider_message": "Success"
        },
        // сведения об остальных операциях
        ...
    ],
    "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw=="
}
```

Если состав параметров, используемый в ответах по умолчанию, не подходит для решения целевых задач, можно определять необходимый состав параметров через массив `fields`. Если при этом необходимо также применять фильтрацию операций, можно задавать критерии фильтрации через различные параметры, например `operation_type`, `operation_status` и `customer_email`.

```language-json
// Тело запроса на получение данных:
{
    "project_id":[
        0,
        11
    ],
    "interval": {
        "from":"2024-04-04 00:00:00",
        "to":"2024-04-19 23:59:59"
    },
    "operation_type": [
        "sale",
        "refund"
    ],
    "operation_status": [
        "success",
        "decline"
    ],
    "customer_email": "astronaut@earth.station",
    "token":"qOnHY86dfhpxdghEBb7HSLbe",
    "fields": [
        "operation_id",
        "operation_type",    
        "operation_status",
        "sum_initial.amount",
        "sum_initial.currency",
        "customer_email"
    ],
    "signature":"vtv5TN6aWQV...5QBjpe8Dsv=="
}

// Тело ответа:

{
    "operations": [
    // сведения об операции
    {
        "operation_id": "12347892",
        "operation_type": "sale",
        "operation_status": "success",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "customer_email": "astronaut@earth.station"
    },
    // сведения об остальных операциях ...
    ],
    "signature": "sdkf45rt73jncpEB75HTS=="
}

```

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

Для получения информации обо всех операциях по конкретному платежу следует использовать запрос к конечной точке [/operations/get-by-payment](https://api-data.ecommpay.com/operations/post-operations-get-by-payment).

В этом запросе должны указываться параметры `payment_id` \(идентификатор целевого платежа\), `token` \(токен учётной записи Dashboard\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). В ответе на такой запрос содержатся сведения об операциях целевого платежа.

```language-json
// Тело запроса
{
  "payment_id":"PID_25467851461-2147",
  "token":"VmJQhaXILAnZWTKmqwSd3j",
  "signature":"JM+YWmTL7uGn26IgZWT...yaq030+eNXVtJjjtgrkglpeXJg=="
}

// Тело ответа
{
  "operations": [
    {
      "arn": "",
      "operation_completed_at": "2024-11-22T13:13:04+00:00",
      "operation_type": "refund",
      "operation_id": "2747253065470",
      "amount": 221,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:13:04+00:00",
      "rrn": "803817399309",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "2024-11-22T13:09:03+00:00",
      "operation_type": "capture",
      "operation_id": "2747253065469",
      "amount": 1621,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:09:03+00:00",
      "rrn": "000000248370",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "2024-11-22T13:06:40+00:00",
      "operation_type": "auth",
      "operation_id": "2747253065468",
      "amount": 200,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:06:38+00:00",
      "rrn": "000047769105",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    }
  ],
  "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7b...y1WihDJ4ljz/Hv7NkQFujSnvw=="
}
```