Описание интеграционного взаимодействия

Схема взаимодействия

Image of integration

Таблица запросов и ответов, приведенных в общей схеме

#	Сообщение	Тип	Формат	endpoint	Описание
1	Запрос на получение токена аутентификации	Синхронный	json	/access-tokens	Перед отправкой задачи на распознавание, необходимо получить токен. После получения, его необходимо передавать в header для всех последующих запросов. Время жизни токена — 7 суток
1.1	Ответ с токеном	Синхронный	json
1.2	Ответ с ошибкой аутентификации	Синхронный	json
2	Запрос на создание задания обработки данных	Синхронный	json	/tasks	После получения токена можно отправлять запрос на создание задачи распознавания. Файлы можно загрузить в теле запроса в качестве files или строки, содержащей ссылку на файл
2.1	Ответ с id созданного задания	Синхронный	json		После создания задачи на распознавание, Базис передает идентификатор задачи, который необходим для дальнейшего получения результатов задачи, методом описаным в п. 4.
2.2	Ответ с ошибкой	Синхронный	json, html
3	Ответ с результатом обработки файла	Асинхронный / webhook	json		Если в запросе был указан адрес вебхука, то по завершении задачи распознавания, Базис автоматически вышлет ответ с результатами распознавания на указанный адрес. Если вебхук не был указан, то получить результат распознавания можно с помощью long polling, методом GET
4	Запрос на получение результата обработки	Асинхронный	json	/tasks/{{taskId}}	GET-запрос для получения результатов распознавания по id задачи, полученным в ответе 2.1
4.1	Ответ с ошибкой на получение результата обработки	Cинхронный	json

url: https://api.doc.basis.center/

Поддерживаемые форматы: pdf, png, jpg, jpeg, pjpeg, gif, tiff или zip

Ограничения: - В одном запросе не более 100мб (по договору SLA 10мб)
- Не более 40 страниц в запросе


url:	https://api.doc.basis.center/
Поддерживаемые форматы:	pdf, png, jpg, jpeg, pjpeg, gif, tiff или zip
Ограничения:	- В одном запросе не более 100мб (по договору SLA 10мб) - Не более 40 страниц в запросе

1. Запрос на получение авторизационного токена

POST {url}/access-tokens

Параметр	Количество	Тип данных	Размещение	Описание
${url}	1	url	request line	URL стенда, на который осуществляется запрос
Content-Type	1	string	header	application/json
email	1	string	body/raw	Адрес электронной почты, предоставленный для аутентификации
password	1	string	body/raw	Пароль, предоставленный для аутентификации

1.1. Ответ с токеном

HTTP-code: 201

Параметр	Количество	Тип данных	Размещение	Описание
token	1	string	body	Токен аутентификации, с которым необходимо выполнять все следующие запросы. Срок жизни токена 24 часа с момента получения

1.2. Ответ с ошибкой авторизации

HTTP-code: 401

Параметр	Количество	Тип данных	Размещение	Описание
timestamp	1	string	body	Время события на сервере
status	1	int	body	Код ошибки
error	1	string	body	Причина ошибки
message	1	string	body	Текст сообщения об ошибке
path	1	string	body	Путь запроса

2. Запрос на создание задания обработки данных

Параметр	Количество	Тип данных	Размещение	Описание
${url}	1	string	request line	URL стенда, на который осуществляется запрос
authorization	1	string	header	Содержит токен аутентификации
files	1..*	file/string	body/form‑data	Объекты с файлами для распознавания. Не более 40 страниц в одном запросе
preset	1	string	body/form‑data	Выбор шаблона бизнес-процесса распознавания докуменов. Значение параметра `preset` уникально для каждого заказчика.
webhookUrl	0..1	string	body/form‑data	Адрес вебхука для ответа

2.1. Ответ с id созданного задания

HTTP-code: 201

Параметр	Количество	Тип данных	Размещение	Описание
id	1	string	body	Внешний ID задания
creatorId	1	string	body	ID автора задания
status	1	string	body	Pending - распознавание в процессе

2.2. Ответ с ошибкой

Ошибки валидации файла

Код ошибки	Причина	Решение
403	Ошибка в уровне доступа (невалидная роль)	Обратитесь к менеджеру Базис. Докуменов
413	Файл превышает размер в 100мб	Удалите из запроса часть распознаваемых файлов
422	- Запрос не содержит файлов - Запрос содержит не поддерживаемый файл	Убедитесь, что запрос содержит поддерживаемый файл или работающую ссылку на файл Поддерживаемые форматы: pdf, png, jpg, jpeg, pjpeg, gif, tiff или zip

Ошибки запроса

Код ошибки	Причина	Решение
401	Ошибка пары логин/пароль	Проверьте правильность указанных в запросе логина и пароля. Если проблему не удается решить самостоятельно, то обратитесь к менеджеру Базис.Документов
500	Ошибка в названии пресета	Убедитесь в правильности используемого в запросе пресета

3. Ответ с результатом обработки файла

Структура ответа может меняться в зависимости от выбранного пресета. Ниже приведен один из возможных вариантов.

HTTP-code: 200

Параметр	Количество	Тип данных	Размещение	Описание
id	1	string	body	Идентификатор задачи
creatorId	1	string	body	ID инициатора задания
DocumentType	1	string	body	Тип распознанного документа
status	1	string	body	`Completed` - распознавание завершено `Pending` - распознавание в процессе `Rejected` - ошибка распознавания
solution	1	object	body	Коллекция с результатом обработки. Коллекция содержит распознанные поля, пример атрибутов паспорта: `"gender": "МУЖ.", "issuer": "ОТДЕЛОМ ВНУТРЕННИХ ДЕЛ ОКТЯБРЬСКОГО ОКРУГА ГОРОДА АРХАНГЕЛЬСКА", "number": "1104 000000", "lastName": "ПЕТРОВ", "firstName": "ЕВГЕНИЙ", "issueDate": "17.12.2004", "birthPlace": "ГОР. АРХАНГЕЛЬСК", "birthDate": "01.01.1980", "issuerCode": "292-000", "middleName": "АЛЕКСАНДРОВИЧ"`
preset	1	string	body	Используемый для обработки пресет
webhookUrl	0..1	string	body	Адрес вебхуков для ответа, возможно значение null
sessionId	0..1	string	body	ID сессии, возможно значение null

4. Запрос на получение результата обработки

Параметр	Количество	Тип данных	Размещение	Описание
${url}	1	string	request line	URL стенда, на который осуществляется запрос
${id}	1	string	request line	Внешний ID задания
Authorization	1	string	header	Токен аутентификации

4.1 Ответ с ошибкой на get-запрос

Технические ошибки

Код ошибки	Причина	Решение
404	Не найден id задачи	1. Убедитесь в корректности введенного id 2. Обратитесь к администратору Базис.Документы
403	Ошибка в уровне доступа (невалидная роль)	Обратитесь к администратору Базис.Документов

Ошибки уровня бизнес логики

Код ошибки	Причина	Решение
200	"message": "Превышено допустимое количество страниц в одном файле"	Загрузите менее 40 страниц в одном запросе