Інтеграція з 1С/BAS

Практичні функції 1С 8 для створення операції, відправки одного або багатьох документів, отримання результату, webhook і розбору JSON.

API документація Кабінет

1С/BAS • зовнішня обробка

Обробка JDOC.epf

Готовий приклад для 1С/BAS: вибір PDF/PNG, відправка документа в JDOC, отримання результату розпізнавання та демонстрація логіки створення документа в обліковій системі.

Завантажити JDOC.epf Опис сервісу

Що показує обробка

підключення до JDOC за API-ключем;
завантаження PDF/PNG з 1С/BAS;
отримання структурованого JSON;
приклад подальшого створення документа у базі.

Це приклад для старту інтеграції. Ваш IT-відділ або 1С-фахівець може адаптувати його під конкретну конфігурацію.

1С 8 • звичайні форми

Обробка JDOC_4U.epf

Зовнішня обробка JDOC для конфігурацій на звичайних формах: «Управління торгівлею 10», «Управління торговим підприємством» та «Управління виробничим підприємством».

Завантажити JDOC_4U.epf Опис сервісу

Підтримувані конфігурації

1С:Управління торгівлею 10;
1С:Управління торговим підприємством;
1С:Управління виробничим підприємством.

Використовуйте цю версію для конфігурацій на звичайних формах. Для конфігурацій на керованих формах використовуйте основну обробку JDOC.epf.

Партнери 1С/BAS

Якщо вам потрібна допомога з підключенням JDOC до конкретної бази BAS / 1С, адаптацією обробок або автоматизацією створення документів, перегляньте розділ Партнери 1С/BAS.

1. Налаштування підключення

Параметр	Значення
Хост	`jdoc.net.ua`
HTTPS	Так, порт 443.
Авторизація	`Authorization: Bearer <API_KEY>`
Створення операції	`POST /api/v1/operations`
Файли	`multipart/form-data`, поле `files[]`.
Пакет	До 20 файлів за один запит.

Перем JDOC_API_HOST;
Перем JDOC_API_KEY;

Процедура JDOC_Ініціалізувати(APIКлюч) Экспорт
    JDOC_API_HOST = "jdoc.net.ua";
    JDOC_API_KEY = APIКлюч;
КонецПроцедуры

Функция JDOC_Соединение() Экспорт
    Возврат Новый HTTPСоединение(JDOC_API_HOST, 443,,,,, Новый ЗащищенноеСоединениеOpenSSL);
КонецФункции

Функция JDOC_НовыйIdempotencyKey(Префикс = "jdoc") Экспорт
    Возврат Префикс + "-" + Строка(Новый УникальныйИдентификатор);
КонецФункции

2. Допоміжні функції JSON і HTTP

Функция JDOC_ПрочитатьJSON(ОтветHTTP) Экспорт
    Тело = ОтветHTTP.ПолучитьТелоКакСтроку();
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.УстановитьСтроку(Тело);
    Возврат ПрочитатьJSON(ЧтениеJSON);
КонецФункции

Процедура JDOC_ПроверитьHTTP(ОтветHTTP) Экспорт
    Код = ОтветHTTP.КодСостояния;
    Если Код < 200 Или Код >= 300 Тогда
        ВызватьИсключение "JDOC HTTP " + Строка(Код) + ": " + ОтветHTTP.ПолучитьТелоКакСтроку();
    КонецЕсли;
КонецПроцедуры

3. Multipart/form-data для файлів

JDOC приймає файли у полі files[]. Для багатьох документів додайте кілька частин з однаковим name files[].

Функция JDOC_СобратьMultipart(МассивПутейКФайлам, Boundary, WebhookURL = "", MetadataJSON = "", ClientOperationID = "", ИспользоватьHeavyAI = Ложь) Экспорт
    CRLF = Символы.ВК + Символы.ПС;
    Поток = Новый ПотокВПамяти;
    Запись = Новый ЗаписьДанных(Поток);

    Для Каждого ПутьКФайлу Из МассивПутейКФайлам Цикл
        Файл = Новый Файл(ПутьКФайлу);
        ИмяФайла = Файл.Имя;
        Mime = ?(НРег(Файл.Расширение) = ".pdf", "application/pdf", "application/octet-stream");

        Заголовок = "--" + Boundary + CRLF
            + "Content-Disposition: form-data; name=\"files[]\"; filename=\"" + ИмяФайла + "\"" + CRLF
            + "Content-Type: " + Mime + CRLF + CRLF;

        Запись.ЗаписатьСтроку(Заголовок, КодировкаТекста.UTF8);
        Запись.Записать(Новый ДвоичныеДанные(ПутьКФайлу));
        Запись.ЗаписатьСтроку(CRLF, КодировкаТекста.UTF8);
    КонецЦикла;

    Если WebhookURL <> "" Тогда
        Запись.ЗаписатьСтроку("--" + Boundary + CRLF
            + "Content-Disposition: form-data; name=\"webhook_url\"" + CRLF + CRLF
            + WebhookURL + CRLF, КодировкаТекста.UTF8);
    КонецЕсли;

    Если MetadataJSON <> "" Тогда
        Запись.ЗаписатьСтроку("--" + Boundary + CRLF
            + "Content-Disposition: form-data; name=\"metadata\"" + CRLF + CRLF
            + MetadataJSON + CRLF, КодировкаТекста.UTF8);
    КонецЕсли;

    Если ClientOperationID <> "" Тогда
        Запись.ЗаписатьСтроку("--" + Boundary + CRLF
            + "Content-Disposition: form-data; name=\"client_operation_id\"" + CRLF + CRLF
            + ClientOperationID + CRLF, КодировкаТекста.UTF8);
    КонецЕсли;

    Если ИспользоватьHeavyAI Тогда
        Запись.ЗаписатьСтроку("--" + Boundary + CRLF
            + "Content-Disposition: form-data; name=\"use_heavy_ai\"" + CRLF + CRLF
            + "true" + CRLF, КодировкаТекста.UTF8);
    КонецЕсли;

    Запись.ЗаписатьСтроку("--" + Boundary + "--" + CRLF, КодировкаТекста.UTF8);
    Запись.Закрыть();
    Возврат Поток.ЗакрытьИПолучитьДвоичныеДанные();
КонецФункции

4. Створити операцію: один документ

Функция JDOC_СоздатьОперациюОдинФайл(ПутьКФайлу, APIКлюч, IdempotencyKey = "", WebhookURL = "", ИспользоватьHeavyAI = Ложь) Экспорт
    Если IdempotencyKey = "" Тогда IdempotencyKey = JDOC_НовыйIdempotencyKey("upload-one"); КонецЕсли;

    Boundary = "----JDOC1C" + СтрЗаменить(Строка(Новый УникальныйИдентификатор), "-", "");
    Файлы = Новый Массив;
    Файлы.Добавить(ПутьКФайлу);
    Тело = JDOC_СобратьMultipart(Файлы, Boundary, WebhookURL, "", "", ИспользоватьHeavyAI);

    Запрос = Новый HTTPЗапрос("/api/v1/operations");
    Запрос.Заголовки.Вставить("Authorization", "Bearer " + APIКлюч);
    Запрос.Заголовки.Вставить("Idempotency-Key", IdempotencyKey);
    Запрос.Заголовки.Вставить("Content-Type", "multipart/form-data; boundary=" + Boundary);
    Запрос.УстановитьТелоИзДвоичныхДанных(Тело);

    Ответ = JDOC_Соединение().ОтправитьДляОбработки(Запрос);
    JDOC_ПроверитьHTTP(Ответ);
    Возврат JDOC_ПрочитатьJSON(Ответ);
КонецФункции

5. Створити операцію: кілька документів

Можна передати до 20 файлів за один запит. Параметр ИспользоватьHeavyAI застосовується до всіх файлів цієї операції. Щоб увімкнути посилене розпізнавання лише для одного документа, надішліть його окремою операцією.

Функция JDOC_СоздатьОперациюНесколькоФайлов(МассивПутейКФайлам, APIКлюч, IdempotencyKey = "", WebhookURL = "", ИспользоватьHeavyAI = Ложь) Экспорт
    Если МассивПутейКФайлам.Количество() > 20 Тогда
        ВызватьИсключение "JDOC принимает до 20 файлов за один запрос.";
    КонецЕсли;

    Если IdempotencyKey = "" Тогда IdempotencyKey = JDOC_НовыйIdempotencyKey("upload-batch"); КонецЕсли;

    Boundary = "----JDOC1C" + СтрЗаменить(Строка(Новый УникальныйИдентификатор), "-", "");
    Тело = JDOC_СобратьMultipart(МассивПутейКФайлам, Boundary, WebhookURL, "", "", ИспользоватьHeavyAI);

    Запрос = Новый HTTPЗапрос("/api/v1/operations");
    Запрос.Заголовки.Вставить("Authorization", "Bearer " + APIКлюч);
    Запрос.Заголовки.Вставить("Idempotency-Key", IdempotencyKey);
    Запрос.Заголовки.Вставить("Content-Type", "multipart/form-data; boundary=" + Boundary);
    Запрос.УстановитьТелоИзДвоичныхДанных(Тело);

    Ответ = JDOC_Соединение().ОтправитьДляОбработки(Запрос);
    JDOC_ПроверитьHTTP(Ответ);
    Возврат JDOC_ПрочитатьJSON(Ответ);
КонецФункции

6. Отримати операцію, результати і webhook-статус

Функция JDOC_ПолучитьОперацию(OperationID, APIКлюч) Экспорт
    Запрос = Новый HTTPЗапрос("/api/v1/operations/" + OperationID);
    Запрос.Заголовки.Вставить("Authorization", "Bearer " + APIКлюч);
    Ответ = JDOC_Соединение().Получить(Запрос);
    JDOC_ПроверитьHTTP(Ответ);
    Возврат JDOC_ПрочитатьJSON(Ответ);
КонецФункции

Функция JDOC_ПолучитьРезультатыОперации(OperationID, APIКлюч) Экспорт
    Запрос = Новый HTTPЗапрос("/api/v1/operations/" + OperationID + "/results");
    Запрос.Заголовки.Вставить("Authorization", "Bearer " + APIКлюч);
    Ответ = JDOC_Соединение().Получить(Запрос);
    JDOC_ПроверитьHTTP(Ответ);
    Возврат JDOC_ПрочитатьJSON(Ответ);
КонецФункции

Функция JDOC_ПолучитьРезультатДокумента(DocumentID, APIКлюч) Экспорт
    Запрос = Новый HTTPЗапрос("/api/v1/documents/" + DocumentID + "/result");
    Запрос.Заголовки.Вставить("Authorization", "Bearer " + APIКлюч);
    Ответ = JDOC_Соединение().Получить(Запрос);
    JDOC_ПроверитьHTTP(Ответ);
    Возврат JDOC_ПрочитатьJSON(Ответ);
КонецФункции

Функция JDOC_ПолучитьWebhookСтатус(OperationID, APIКлюч) Экспорт
    Запрос = Новый HTTPЗапрос("/api/v1/operations/" + OperationID + "/webhook");
    Запрос.Заголовки.Вставить("Authorization", "Bearer " + APIКлюч);
    Ответ = JDOC_Соединение().Получить(Запрос);
    JDOC_ПроверитьHTTP(Ответ);
    Возврат JDOC_ПрочитатьJSON(Ответ);
КонецФункции

7. Дочекатися готового результату

Функция JDOC_ДочекатисяРезультату(OperationID, APIКлюч, ТаймаутСекунд = 180, ПаузаСекунд = 5) Экспорт
    Начало = ТекущаяДата();

    Пока Истина Цикл
        Операция = JDOC_ПолучитьОперацию(OperationID, APIКлюч);

        Если Операция.status = "PROCESSED" Или Операция.status = "PROCESSED_WITH_WARNINGS" Тогда
            Возврат Операция;
        КонецЕсли;

        Если Операция.status = "FAILED" Или Операция.status = "CANCELLED"
            Или Операция.status = "COMPLETED_WITH_ERRORS" Тогда
            Возврат Операция;
        КонецЕсли;

        Если ТекущаяДата() - Начало > ТаймаутСекунд Тогда
            ВызватьИсключение "JDOC: истек таймаут ожидания.";
        КонецЕсли;

        Пауза(ПаузаСекунд);
    КонецЦикла;
КонецФункции

8. Webhook: що отримує 1С/BAS

Якщо ви налаштували webhook у кабінеті, JDOC надсилає POST-запит у вашу систему після завершення обробки. Повний результат краще забирати через GET-запит за operation_id або document_id.

Основні headers

Header	Опис
`X-DocParser-Event`	Тип події.
`X-DocParser-Operation-Id`	ID операції.
`X-DocParser-Document-Id`	ID документа, якщо подія документна.
`X-DocParser-Event-Id`	ID події для дедуплікації.
`X-DocParser-Timestamp`	Timestamp підпису.
`X-DocParser-Signature`	Підпис `sha256=...`.

Приклад payload

{
  "event_type": "operation.completed",
  "event_id": "evt_xxx",
  "operation_id": "op_xxx",
  "status": "PROCESSED",
  "summary": {
    "files_total": 1,
    "processed": 1,
    "processed_with_warnings": 0,
    "rejected": 0,
    "failed": 0,
    "cancelled": 0
  },
  "documents": [
    {
      "document_id": "doc_xxx",
      "filename": "document.pdf",
      "status": "PROCESSED",
      "billing": {
        "billable": true,
        "documents_charged": 1
      }
    }
  ]
}

Перевірка підпису

Підпис рахується як HMAC-SHA256 від рядка timestamp + "." + raw_body секретом webhook.

Функция JDOC_WebhookПідписДійсний(ТелоJSON, Timestamp, Signature, Secret) Экспорт
    // Псевдокод: реалізація HMAC залежить від вашої конфігурації 1С/BAS
    СтрокаДляПодписи = Timestamp + "." + ТелоJSON;
    ОжидаемаяПодпись = "sha256=" + HMAC_SHA256_HEX(Secret, СтрокаДляПодписи);
    Возврат ОжидаемаяПодпись = Signature;
КонецФункции

9. Що читати з JSON

Дані	Поле
Номер документа	`documents[0].result.document.number`
Дата	`documents[0].result.document.date`
Контрагенти	`documents[0].result.parties`
Рядки	`documents[0].result.line_items`
Суми	`documents[0].result.totals`
ПДВ	`documents[0].result.taxes`
Попередження	`documents[0].warnings`

10. Підтримка інтеграції

Якщо потрібна допомога з API або 1С/BAS, напишіть на support@jdoc.net.ua.