AtolOnlineNet 1.0.0

AtolOnlineNet

.NET SDK для облачной фискализации АТОЛ Онлайн (сервис possystem v4, ФФД 1.05): авторизация, регистрация чеков прихода/расхода/возврата, чеков коррекции и получение результата фискализации.

SDK работает с облачным API регистрации чеков (/possystem/v4/...). Версия v5 (ФФД 1.2) пока не реализована — см. Roadmap.

Установка

dotnet add package AtolOnlineNet

Целевые платформы: netstandard2.0, net8.0, net10.0 (работает на .NET Framework 4.6.1+, .NET Core 2.0+, .NET 8/10).

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

using AtolOnlineNet;
using AtolOnlineNet.V1_05;

var options = new AtolOnlineClientOptions
{
    Login = "your-login",
    Password = "your-password",
    GroupCode = "your-group-code",
    BaseAddress = AtolOnlineClientOptions.TestBaseAddress, // или ProductionBaseAddress
};

using var client = new AtolOnlineClient(options); // или new AtolOnlineClient(httpClient, options)

// Токен запрашивается автоматически и кешируется на 24 часа.
var registered = await client.SellAsync(new ReceiptRegistrationRequest
{
    ExternalId = Guid.NewGuid().ToString("N"),
    Timestamp = DateTime.Now,
    Receipt = new Receipt
    {
        Client = new Client { Email = "buyer@example.com" },
        Company = new Company
        {
            Email = "shop@example.com",
            Sno = TaxationSystem.Osn,
            Inn = "5544332219",
            PaymentAddress = "https://shop.example.com",
        },
        Items =
        [
            new Item
            {
                Name = "Носки хлопковые",
                Price = 199.00m,
                Quantity = 2m,
                Sum = 398.00m,
                PaymentMethod = PaymentMethod.FullPayment,
                PaymentObject = PaymentObject.Commodity,
                Vat = new Vat { Type = VatType.Vat20 },
            },
        ],
        Payments = [new Payment { Type = PaymentType.Cashless, Sum = 398.00m }],
        Total = 398.00m,
    },
});

Console.WriteLine($"UUID: {registered.Uuid}, статус: {registered.Status}");

// Получение результата по UUID (опрос до терминального статуса).
var report = await client.GetReportAsync(registered.Uuid!);
if (report.Status == DocumentStatus.Done)
{
    Console.WriteLine($"ФД №{report.Payload!.FiscalDocumentNumber}, ФПД {report.Payload.FiscalDocumentAttribute}");
    Console.WriteLine($"Чек ОФД: {report.Payload.OfdReceiptUrl}");
}

Среды

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

Сам AtolOnlineClient версионно-нейтрален: транспорт (токен / регистрация / результат) одинаков для всех версий ФФД. Типобезопасные методы SellAsync/BuyAsync/… — это методы-расширения из пространства имён AtolOnlineNet.V1_05 (ФФД 1.05), работающие с моделями чека этой версии. Для динамического выбора операции есть нейтральные RegisterAsync(ReceiptOperation, object) и RegisterCorrectionAsync(CorrectionOperation, object). Модели чека ФФД 1.2 будут добавлены в AtolOnlineNet.V1_2; версия выбирается через AtolOnlineClientOptions.ApiVersion.

К каждому запросу автоматически добавляется заголовок User-Agent вида AtolOnlineNet/<версия>, если на HttpClient не задан собственный.

Чек коррекции

var correction = await client.SellCorrectionAsync(new CorrectionRegistrationRequest
{
    ExternalId = Guid.NewGuid().ToString("N"),
    Timestamp = DateTime.Now,
    Correction = new Correction
    {
        Company = new Company { Email = "shop@example.com", Sno = TaxationSystem.Osn, Inn = "5544332219", PaymentAddress = "https://shop.example.com" },
        CorrectionInfo = new CorrectionInfo
        {
            Type = CorrectionType.Self,
            BaseDate = new DateTime(2026, 6, 1),
        },
        Payments = [new Payment { Type = PaymentType.Cashless, Sum = 100m }],
        Vats = [new Vat { Type = VatType.Vat20, Sum = 16.67m }],
    },
});

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

Бизнес-результат возвращается в объектах ответа — статус (Wait / Done / Fail) и Error не выбрасываются как исключения, их нужно проверять:

var report = await client.GetReportAsync(uuid);
switch (report.Status)
{
    case DocumentStatus.Done: /* реквизиты в report.Payload */ break;
    case DocumentStatus.Wait: /* ещё обрабатывается — повторить позже */ break;
    case DocumentStatus.Fail: Console.WriteLine($"Ошибка {report.Error?.Code}: {report.Error?.Text}"); break;
}

Исключения выбрасываются только в исключительных ситуациях:

Символьные имена кодов ошибок сервиса — в AtolServiceErrorCodes (например ExpiredToken = 11). Истёкший токен обрабатывается автоматически (повторная авторизация и один повтор запроса).

Внедрение зависимостей

Ядро не зависит от Microsoft.Extensions.*. Регистрация через IHttpClientFactory:

services.AddHttpClient("atol-online");
services.AddSingleton<IAtolOnlineClient>(sp =>
{
    var http = sp.GetRequiredService<IHttpClientFactory>().CreateClient("atol-online");
    return new AtolOnlineClient(http, new AtolOnlineClientOptions
    {
        Login = "...",
        Password = "...",
        GroupCode = "...",
        BaseAddress = AtolOnlineClientOptions.ProductionBaseAddress,
    });
});

Разработка

dotnet build AtolOnlineNet.slnx -c Release
dotnet test  tests/AtolOnlineNet.Tests/AtolOnlineNet.Tests.csproj -c Release   # модульные тесты
dotnet pack  src/AtolOnlineNet/AtolOnlineNet.csproj -c Release -o artifacts/packages

Интеграционные тесты (tests/AtolOnlineNet.Tests.Integration) выполняются против тестовой среды АТОЛ только при заданных учётных данных — скопируйте .env.example в .env. Без учётных данных они пропускаются.

Документация

• Протокол фискализации v4 (ФФД 1.05)
• Сервис информации о ККТ и ФН (отдельный API)
• Соглашения проекта · История изменений

Roadmap

• Поддержка possystem v5 (ФФД 1.2). Транспорт (токен/регистрация/результат) общий; добавляются только модели чека ФФД 1.2, версия выбирается через AtolOnlineClientOptions.ApiVersion.

Лицензия

MIT