Фильтрация

🧩 Что такое фильтры

Во многих GET-запросах Monocrypt API используется гибкая система фильтрации данных. Она построена на JSON-структуре, которая описывает условия поиска (and, or, операторы eq, iLike, gte, и т.д.). На фронтенде (или SDK) фильтр передаётся в виде JSON, но под капотом превращается в query string, которую вы можете использовать вручную, например, в curl или Postman.

---

🔎 Пример фильтра JSON

{
  "and": [
    {
      "or": [
        { "currency": { "eq": "USDT" } },
        { "currency": { "eq": "USDC" } }
      ]
    },
    {
      "or": [
        { "status": { "eq": "completed" } },
        { "status": { "eq": "processing" } }
      ]
    }
  ]
}

Этот фильтр означает:

Выбрать все транзакции, где валюта USDT или USDC, и статус completed или processing.

---

🧠 Основные логические операторы

Оператор	Описание	Пример
and	Все условия должны выполняться	and: [ {...}, {...} ]
or	Должно выполниться хотя бы одно из условий	or: [ {...}, {...} ]

---

⚙️ Поддерживаемые типы сравнений

Оператор	Описание	Пример
isNot	Проверяет, что поле не null, true или false	"isNot": null
eq	Равно значению	"currency": { "eq": "USDT" }
neq	Не равно значению	"status": { "neq": "failed" }
gt	Больше значения	"amount": { "gt": "100" }
gte	Больше или равно	"amount": { "gte": "100" }
lt	Меньше	"amount": { "lt": "1000" }
lte	Меньше или равно	"amount": { "lte": "1000" }
in	Находится в списке значений	"currency": { "in": ["USDT", "USDC"] }
notIn	Не входит в список	"status": { "notIn": ["failed", "pending"] }
like	Похоже на значение (чувствительно к регистру)	"name": { "like": "%John%" }
iLike	Похоже на значение (без учёта регистра)	"email": { "iLike": "[e-mail]%" }
between	Находится между нижним и верхним диапазоном	"amount": { "between": { "lower": 100, "upper": 500 } }

---

🧩 Пример того, как JSON превращается в Query String

{
  "and": [
    {
      "or": [
        { "currency": { "eq": "USDT" } },
        { "currency": { "eq": "USDC" } }
      ]
    },
    {
      "or": [
        { "status": { "eq": "completed" } }
      ]
    }
  ]
}

Преобразуется в строку:

filter[and][0][or][0][currency][eq]=USDT&
filter[and][0][or][1][currency][eq]=USDC&
filter[and][1][or][0][status][eq]=completed

---

💻 Пример с curl

curl -X GET "xxx.xxx/v1/transactions?filter[and][0][or][0][currency][eq]=USDT&filter[and][0][or][1][currency][eq]=USDC&filter[and][1][or][0][status][eq]=completed" \
  -H "x-api-key: your-api-key"

---

⚡ Пример с axios

На фронтенде (или в Node.js) фильтры проще передавать как объект — axios сам преобразует их в query string.

import axios from "axios";

const filter = {
  and: [
    {
      or: [
        { currency: { eq: "USDT" } },
        { currency: { eq: "USDC" } }
      ]
    },
    {
      or: [
        { status: { eq: "completed" } },
        { status: { eq: "processing" } }
      ]
    }
  ]
};

const response = await axios.get("https://xxx.xxx/v1/transactions", {
  headers: {
    "x-api-key": "your-api-key"
  },
  params: {
    filter,
    paging: { limit: 20, offset: 0 },
    sorting: [{ field: "createdAt", direction: "DESC" }]
  }
});

console.log(response.data);

---

⚠️ Важно

• Используйте URL-кодирование (%20, %25 и т.д.) при передаче фильтров вручную.

• Для сложных запросов рекомендуется использовать axios, чтобы не собирать строку руками.

• Все запросы GET с фильтрацией поддерживают также:

  • paging[limit] и paging[offset] — для пагинации

  • sorting[0][field] и sorting[0][direction] — для сортировки результатов

---