API

Всі запити виконуються методом HTTP POST. Параметри запиту надсилаються у тілі запиту у форматі JSON.

Базовий URL

https://blacklist.risktools.pro/

Авторизація

При підключенні до сервісу ви отримуєте унікальний ключ доступу до API. Цей ключ передається у параметрі AuthKey у заголовку запиту.

Заголовки запиту

Content-Type: application/json
AuthKey: your-auth-key

Пошук у чорному списку

Метод API

/blacklist/search

Приклади

Пошук за ІПН

POST /blacklist/search

{
    "ipn": "1234567890",
}

Пошук за номером телефону

POST /blacklist/search

{
    "phone": "380501112233",
}

Пошук за ІПН з фільтром категорій

POST /blacklist/search

{
    "ipn": "1234567890",
    "categories": ["military", "claim"],
}

З повним списком категорій можете ознайомитись тут.

Приклад запиту за допомогою curl

curl \
--header "AuthKey: your-auth-key" \
--header "Content-Type: application/json" \
  --request POST \
  --data '{
  "ipn": "1234567890",
  "phone": "380680000000",
  "categories": [
    "military"
  ]
}'  https://blacklist.risktools.pro/blacklist/search

Якщо в параметрах пошуку задані одночасно і ІПН та номер телефону, пошук виконуйтеся за логікою АБО, тобто будуть знайдені записи, у яких збігається ІПН або номер телефону.

Структура відповіді

Приклад

{
  "status": "ok",
  "result": {
    "records": [
      {
        "ipn": "1234567890",
        "phone": null,
        "category": "military",
        "added_at": "2023-06-25T21:30:24+03:00",
        "partner_id": "87613"
      },
      {
        "ipn": "1234567890",
        "phone": "380509999999",
        "category": "military",
        "added_at": "2023-03-16T11:19:57+02:00",
        "partner_id": "01933"
      }
    ],
    "found": 2,
    "partners": [
      "01933",
      "87613"
    ],
    "categories": {
      "military": 2
    }
  },
  "exec_time_ms": 40.763,
  "request_id": "72603a66-53da-4e96-911a-1ce7cffa4b31"
}

Поля

records (list) - список знайдених записів. Кожен запис містить поле partner_id, яке містить унікальний ID партнера (донора)
found (integer) - кількість знайдених записів
partners (list) - унікальний список партнерів, які передали знайдені записи
categories (dictionary) - статистика результатів пошуку за категоріями. Ключ – назва категорії. Значення – кількість знайдених записів цієї категорії.

Додавання до чорного списку

Метод API

/blacklist/update

Приклади

POST /blacklist/update

{
  "records": [
    {
      "ipn": "1234567890",
      "category": "inadequate",
      "added_at": "2023-01-02T14:59:04+02:00"
    },
    {
      "phone": "380931112233",
      "category": "circle",
      "added_at": "2023-01-03T11:21:34+02:00"
    },
    {
      "ipn": "9876123450",
      "phone": "380671112233",
      "category": "military",
      "added_at": "2023-01-03T11:47:18+02:00"
    }
  ]
}

Приклад запиту за допомогою curl

curl \
--header "AuthKey: your-auth-key" \
--header "Content-Type: application/json" \
  --request POST \
  --data '{
  "records": [
    {
      "ipn": "1234567890",
      "category": "inadequate",
      "comment": "неадекватна поведінка, у ч/с",
      "added_at": "2023-01-02T14:59:04+02:00"
    },
    {
      "phone": "380931112233",
      "category": "circle",
      "added_at": "2023-01-03T11:21:34+02:00"
    },
    {
      "ipn": "9876123450",
      "phone": "380671112233",
      "category": "military",
      "added_at": "2023-01-03T11:47:18+02:00"
    }
  ]
}'  https://blacklist.risktools.pro/blacklist/update

Параметри запиту

records (list) - список записів чорного списку. Кожен елемент списку – це об'єкт key-value (dictionary), що містить такі поля:

ipn (string) - ІПН
phone (string) - номер телефону
category (string) - одна з категорій цього списку
added_at (datetime) - час додавання до чорного списку в CRM партнера
comment (string) - коментар, який був зроблений при додаванні до чорного списку

Обов'язкові поля: ipn або phone, category, added_at

Структура відповіді

Відповідь містить поле errors, де міститься список помилок валідації при додаванні переданих записів.

Приклад відповіді з помилками

{
  "status": "ok",
  "result": {
    "errors": [
      {
        "item": {
          "ipn": "01234567890"
        },
        "errors": {
          "category": [
            "Missing data for required field."
          ],
          "added_at": [
            "Missing data for required field."
          ]
        }
      },
      {
        "item": {
          "ipn": "9876543210",
          "category": "unsupported"
        },
        "errors": {
          "category": [
            "Must be one of: military, claim, fraud, circle, dead, gaming, incapable, writeoff, inadequate, addict, lost_docs, self, other."
          ],
          "added_at": [
            "Missing data for required field."
          ]
        }
      },
      {
        "item": {
          "category": "military",
          "added_at": "2023-08-01 12:00:00"
        },
        "errors": {
          "_schema": [
            "At least ipn or phone must contain valid values"
          ]
        }
      }
    ]
  },
  "exec_time_ms": 510.064,
  "request_id": "9f7d1485-0b18-4f10-9cf5-5afd033504d9"
}

Кожен елемент списку помилок містить два поля: * item - переданий запис * errors - помилки, які виникли при обробці запису