Skip to content

SDK для работы с API Контур.Экстерна

License

Notifications You must be signed in to change notification settings

skbkontur/extern-csharp-sdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SDK для интеграции с АПИ Контур Экстерн

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

Шаг 1. Создание и настройка объекта IExtern

Для выполнения запросов необходимы реквизиты доступа, получить их можно обратившись по контактам, указанным в соответствующем разделе документации

Тестовая площадка

    string apiKey = "..."; // Апи-ключ, назначенный вашему приложению, для использования на ТЕСТОВОЙ площадке
    string someUserLogin = "..."; // Логин пользователя (на ТЕСТОВОЙ площадке), от имени которого выполняется аутентификация
    string someUserPassword = "..."; // Пароль пользователя (на ТЕСТОВОЙ площадке), от имени которого выполняется аутентификация
    string clientId = "..."; // Уникальное сервисное имя вашего приложения (на ТЕСТОВОЙ площадке)

    IExtern externApi = new ExternBuilder()
          .WithExternApiUrl(
              new Uri("https://extern-api.testkontur.ru/"), // урл ТЕСТОВОЙ площадки апи Экстерна
              log)
          .WithOpenIdAuthenticator(
                builder => builder
                .WithHttpConfiguration(new ExternalUrlHttpClientConfiguration("https://identity.testkontur.ru")) // урл ТЕСТОВОЙ площадки сервиса аутентификации
                .WithClientIdentification(clientId, apiKey)
                .WithAuthenticationByPassword(someUserLogin, someUserPassword)
                .Build())                
           .Create();

Продуктовая площадка

    // Значения параметров для продуктовой площадки не будут совпадать с аналогичными значениями для тестовой площадки
    string apiKey = "..."; // Апи-ключ, назначенный вашему приложению, для использования на ПРОДУКТОВОЙ площадке
    string someUserLogin = "..."; // Логин пользователя (на ПРОДУКТОВОЙ площадке), от имени которого выполняется аутентификация
    string someUserPassword = "..."; // Пароль пользователя (на ПРОДУКТОВОЙ площадке), от имени которого выполняется аутентификация
    string clientId = "..."; // Уникальное сервисное имя вашего приложения (на ПРОДУКТОВОЙ площадке)

    IExtern externApi = new ExternBuilder()
            .WithExternApiUrl(
                new Uri("https://extern-api.kontur.ru/"), // урл ПРОДУКТОВОЙ площадки апи Экстерна
                log)
            .WithPasswordAuthentication( // Дополнительно указывать урл ПРОДУКТОВОЙ площадки сервиса аутентификации не нужно, его значение используется по умолчанию.
                                         // Для более гибкой настройки процесса аутентификации вместо вызова .WithPasswordAuthentication(...) можно воспользоваться
                                         // .WithOpenIdAuthenticator(...), аналогично примеру для тестовой площадки. В этом случае в .WithHttpConfiguration(...) нужно
                                         // будет передать урл ПРОДУКТОВОЙ площадки сервиса аутентификации - "https://identity.kontur.ru"
                new Credentials(someUserLogin, someUserPassword),
                clientId,
                apiKey)
            .Create();

Шаг 2. Выполнение запросов

После создания и настройки объекта IExtern можно использовать его для выполнения запросов к АПИ. Например, загрузить все учетные записи, доступные аутентифицированному пользователю:

    IReadOnlyList<Account> accounts = await externApi.Accounts.List().SliceBy(100).LoadAllAsync();

Аутентификация для выполнения запросов

⚠️ Дополнительно аутентифицироваться до выполнения запросов не нужно ⚠️

При запросе сдк автоматически выполнит попытку аутентифицироваться.

Также сдк автоматически выполнит реаутентификакцию при истечении времени жизни токена.

Другие методы аутентификации

Доступна аутентификация по сертификату, для этого вместо .WithPasswordAuthentication(...) нужно вызвать .WithCertificateAuthentication(...).

Более подробно про процесс аутентификации можно прочитать в документации к АПИ

Примеры выполнения запросов

Загрузка контента документа в Сервис Контентов

    Stream contentStream =  new MemoryStream(new byte[] {1, 2, 3});
    Guid contentId = await externApi.Accounts.WithId(accountId).Contents.UploadAsync(contentStream);

Создание черновика и документа с подписью в черновике

    Draft draft = await externApi
        .Accounts.WithId(accountId)
        .Drafts.CreateDraftAsync(draftMetadata);

    byte[] signature = new byte[] {1, 2, 3};
    IDraftDocument document = DraftDocumentBuilder
        .WithNewId()
        .WithUploadedContent(contentId, "application/xml", signature)
        .ToDocument();

    await externApi
        .Accounts.WithId(accountId)
        .Drafts.WithId(draft.Id)
        .SetDocumentAsync(document);

Проверка черновика

    ILongOperationAwaiter<DraftCheckingStatus> checkAwaiter = await externApi
        .Accounts.WithId(accountId)
        .Drafts.WithId(draft.Id)
        .Check()
        .StartAsync();
    
    DraftCheckingStatus draftCheckingStatus = await checkAwaiter.WaitForCompletion();

Отправка черновика

    ILongOperationAwaiter<IDocflowWithDocuments, DraftSendingFailure> sendAwaiter = await externApi
        .Accounts.WithId(accountId)
        .Drafts.WithId(draft.Id)
        .TrySend()
        .StartAsync();
    
    LongOperationResult<IDocflowWithDocuments, DraftSendingFailure> draftSendResult = await sendAwaiter.WaitForSuccessOrFailure();
    IDocflowWithDocuments docflow = draftSendResult.GetSuccessResult();

Получение ДО по идентификатору

    IDocflowWithDocuments docflow = await externApi
        .Accounts.WithId(accountId)
        .Docflows.WithId(docflowId)
        .GetAsync();