ExolveNet 0.2.1

<div align="center"> <img src="https://raw.githubusercontent.com/ai-iskuzhin/ExolveNet/main/assets/ExolveNet.png" width="140" alt="Логотип ExolveNet" />

<h1>ExolveNet</h1>

<p> <a href="https://www.nuget.org/packages/ExolveNet"><img src="https://img.shields.io/nuget/v/ExolveNet?logo=nuget&style=flat-square" alt="Версия NuGet" /></a> <a href="https://dotnet.microsoft.com/"><img src="https://img.shields.io/badge/targets-netstandard2.0%20%7C%20net8.0%20%7C%20net10.0-512BD4?logo=dotnet&style=flat-square" alt="Таргеты" /></a> <a href="https://github.com/ai-iskuzhin/ExolveNet/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ai-iskuzhin/ExolveNet?style=flat-square" alt="Лицензия" /></a> <a href="https://github.com/ai-iskuzhin/ExolveNet/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ai-iskuzhin/ExolveNet/ci.yml?branch=main&style=flat-square" alt="CI" /></a> </p> </div>

Неофициальный .NET SDK для платформы МТС Exolve.

Не аффилирован с МТС Exolve и АО «МТТ».

Установка

dotnet add package ExolveNet

Таргеты: netstandard2.0, net8.0, net10.0.

Поддерживаемые методы

Пакетные отчёты — до 50 000 номеров за раз

Полное описание полей — в docs/api-hlr.md.

Быстрый старт

using ExolveNet;

var client = new ExolveHlrClient(
    httpClient,                                  // можно из IHttpClientFactory
    new ExolveClientOptions { ApiKey = "<API-ключ приложения>" });

var score = await client.GetActivityScoreAsync("+7 913 999-99-99");

Console.WriteLine(score.Score);     // 0.85 — от 0 (нет активности) до 1
Console.WriteLine(score.OwnerId);   // оператор
Console.WriteLine(score.Number);    // 79139999999

Номер принимается в любом привычном виде — +7…, 8…, с пробелами и дефисами — и приводится к 7XXXXXXXXXX до отправки. Это не косметика: запрос в неверном формате Exolve отклоняет, но тарифицирует, поэтому единственный бесплатный отказ — локальный.

Какой оператор обслуживает номер

var info = await client.GetBaseNumberInfoAsync("+79139999999");

Console.WriteLine(info.OwnerId);   // Tele2
Console.WriteLine(info.Mnc);       // 20
Console.WriteLine(info.IsPorted);  // true — номер переносили

if (info.Operator == MobileOperator.Mts)
{
    // только сюда имеет смысл слать методы, которые работают по номерам МТС
}

По префиксу оператора определить нельзя: номер мог быть перенесён (MNP), и тогда «мтс-овский» префикс принадлежит другому оператору. GetBaseNumberInfo — единственный надёжный ответ.

Operator считается по коду сети (MNC), а если его нет — по названию из owner_id. Таблица намеренно короткая: четыре федеральных оператора, всё остальное — Other, потому что назвать оператора наугад хуже, чем честно сказать «не из этих четырёх».

Методы «только для МТС»

try
{
    var sim = await client.GetSimStatusAsync(number);
    Console.WriteLine(sim.IsRegistered);
}
catch (ExolveApiException ex) when (ex.IsNonMtsNumber)
{
    // 400 enter another number — номер не МТС. Ожидаемый исход, а не сбой.
}

Пакетная проверка

var handle = await client.GenerateActivityScoreReportAsync(new[]
{
    "+79139999999",
    "89139999998",
});

// Считается асинхронно — Pending/Processing это нормальный ответ, а не ошибка.
var report = await client.GetReportAsync(handle.FileUuid!);
if (report.IsComplete)
{
    Console.WriteLine(report.NumberTotal);
    Console.WriteLine(report.DecodeResults());
}

Список номеров уходит не массивом JSON, а файлом в base64 — SDK нормализует каждый номер и кодирует список сам. Предел — 50 000 номеров; и пустой список, и превышение предела, и один нерабочий номер отвергаются локально, до платного запроса.

report.RetainedUntil — это срок хранения (30 дней), хотя на проводе поле называется created_at. После него статус становится Expired, а данные пропадают.

Тарификация — важное

Платный запрос — любой запрос, независимо от ответа. Если по номеру нет данных (обычно не было активности около двух лет), API возвращает ошибку, и деньги всё равно списываются. «Неуспешного» HLR-запроса с точки зрения счёта не существует — перепродавать его «за успех» нельзя.

Обработка ошибок

У ExolveApiException есть признаки для частых случаев, чтобы не сравнивать строки в своём коде: IsNonMtsNumber, IsHlrDisabled, IsUnsignedCustomer (тестовый период — можно проверять только свой подтверждённый номер; легко спутать с ограничением по оператору).

Персональные данные

Номер телефона — персональные данные, а текст исключения почти наверняка попадёт в лог. Поэтому:

• в ExolveProtocolException.BodyPreview номер замаскирован;
• сырое тело ответа в Metadata.RawBody не сохраняется, пока не включишь CaptureRawResponseBody.

Лицензия

MIT.