API сервісу EDIN-IDP
Опис методів АРІ та обʼєктів для роботи в сервісі EDIN-IDP
- Опис типової структури документа
- Опис обʼєктів для методів сервісу EDIN-IDP
- Опис методів для сервісу EDIN-IDP
Опис типової структури документа
[
{
"DocumentName": "Назва документу",
"Barcode": "штрихкод документу",
"DocumentType": "000-не визначено; 001-договір; 002-додаткова угода; 003-рахунок/рахунок-фактура; 004-акт/акт виконаних робіт/акт наданих послуг/акт надання послуг; 005-накладна/товарна накладна; 006-видаткова накладна; 007-наряд замовлення.",
"DocumentHeader": {
"Number": "номер додаткової угоди. поле опціональне",
"Date": "дата документу. формат YYYY-MM-DD. поле опціональне",
"Location": "місце складання",
"Route": "маршрут",
"DeliveryTerms": "умови поставки",
"DeliveryTime": "час доставки",
"CarNumber": "номер автомобіля",
"PayToDate": "сплатити до дати. формат YYYY-MM-DD. поле опціональне"
},
"Agreement": [
{
"AgreementNumber": "номер договору",
"AgreementDate": "дата документу. формат YYYY-MM-DD. поле опціональне",
"Subject": "предмет договору"
}
],
"Equipment": [
{
"Name": "найменування обладнання",
"Serial": "серійний номер"
}
],
"AdditionalInfo": [
{
"Name": "назва",
"Value": "значення"
}
],
"ReasonOfService": [
"причина виклику"
],
"CompletedWorks": [
"виконані роботи"
],
"Recommendations": [
"рекомендації"
],
"Notes": [
"помітки рукописним шрифтом"
],
"SpareParts": [
{
"Name": "Найменування використаних запасних частин та матеріалів",
"Quantity": "кількість",
"Price": "Вартість"
}
],
"Summary": "короткий зміст документу",
"DocumentParties": [
{
"Role": "роль контрагента: оператор, абонемент, продавець, покупець, ...",
"ILN": "GLN контрагента",
"TaxID": "ІПН контрагента",
"UtilizationRegisterNumber": "ЄДРПОУ контрагента",
"Name": "назва компанії контрагента",
"Signature":"boolean. true- є підпис; false-підпису немає",
"Stamp":"boolean. true- є штамп; false-штампу немає",
"Addresses": [
{
"Type": "тип адреси",
"StreetAndNumber": "вулиця/проспект/бульвар і номер будинку контрагента",
"CityName": "місто контрагента",
"District": "район та/або територіальна громада",
"Region": "область",
"PostalCode": "поштовий код контрагента"
}
],
"PhoneNumbers": [
{
"Type": "тип телефоного номера",
"Phone": "телефоний номер контрагента"
}
],
"BankAccounts": [
{
"IBAN": "IBAN контрагента",
"BankName": "назва банку"
}
],
"Email": "email",
"Signer": {
"Position": "посада підписанта",
"Name": "ПІП підписанта"
}
}
],
"DocumentLines": [
{
"LineNumber": "номер позиції в табличній частині",
"EAN": "Штрих-код продукту відповідно до стандарту EAN-8 та EAN-13",
"BuyerItemCode": "Артикул/код товару",
"CertNumber": "номер сертифікату",
"ExternalItemCode": "Код товару згідно з довідника УКТ ЗЕД. завжди складається з 10 символів",
"ItemDescription": "назва товару/послуги",
"InvoiceQuantity": "Замовлена кількість. десяткове число",
"UnitOfMeasure": "одиниці виміру",
"Location": "Локація де проводилась робота чи для якої продається товар",
"UnitGrossPrice": "Ціна однієї одиниці з ПДВ. десяткове число",
"UnitNetPrice": "Ціна однієї одиниці без ПДВ. десяткове число",
"TaxRate": "Ставка ПДВ (20/19/16/14/7/2/0)",
"TaxCategoryCode": "Код категорії податку:S - стандартний податок; можливі значення TaxRate: 20/19/16/14/7/2 (інакше помилка),E - звільнений від сплати податку; можливі значення TaxRate=0, Z - нульова ставка (0%); можливі значення TaxRate=0",
"GrossAmount": "Сума з ПДВ по позиції. десяткове число",
"TaxAmount": "Сума ПДВ по позиції. десяткове число",
"NetAmount": "Всього без ПДВ. десяткове число"
}
],
"DocumentSummary": {
"TotalLines": "Кількість рядків в документі",
"TotalNetAmount": "Загальна сума без ПДВ. десяткове число",
"TotalTaxAmount": "Сума ПДВ. десяткове число",
"TotalGrossAmount": "Загальна сума з ПДВ. десяткове число",
"TaxSummary": [
{
"TaxRate": "Ставка ПДВ (20/19/16/14/7/2/0)",
"TaxCategoryCode": "Код категорії податку:S - стандартний податок; можливі значення TaxRate: 20/19/16/14/7/2 (інакше помилка),E - звільнений від сплати податку; можливі значення TaxRate=0, Z - нульова ставка (0%); можливі значення TaxRate=0",
"TaxAmount": "Сума податку для конкретної категорії податку. десяткове число",
"TaxableAmount": "Оподаткована сума для конкретної категорії податку. десяткове число"
}
]
},
"AdditionalDocuments": [
{
"DocName": "Назва документу",
"Number": "номер документу. поле опціональне",
"Date": "дата документу. формат YYYY-MM-DD. поле опціональне"
}
]
}
]
Опис обʼєктів для методів сервісу EDIN-IDP
Обʼєкт IDPTasksQuery
export type IDPTasksQuery = {
uuid?: string; // uuid завдання
date?: DateTimeRange; // обʼєкт DateTimeRange
fileName?: string; // назва файла
limit?: Limitation; // обʼєкт Limitation
status?: IDPTaskStatus[]; // масив обʼєктів IDPTaskStatus
source?: IDPTaskSource[]; // масив обʼєктів IDPTaskSource
}Обʼєкт IDPTask
export type IDPTask = {
id: number; // ід задачі
userId: number; // ід користувача
uuid: string; // uuid задачі
status: IDPTaskStatus; // обʼєкт IDPTaskStatus
date: number; // дата завантаження файла у форматі UnixTimeStamp
doneDate: number; // дата завершення розпізнавання
info: IDPTaskInfo; // обʼєкт IDPTaskInfo
docType: IDPDocType; // обʼєкт IDPDocType
}Обʼєкт IDPTaskStatus
export type IDPTaskStatus = "ERROR" | "CREATED" | "PROCESSING" | "DONE" | "VERIFIED" | "PROCESSED";Обʼєкт IDPTaskSource
export type IDPTaskSource = "API" | "WEB";Обʼєкт DateTimeRange
export type DateTimeRange = {
startTimestamp?: number; // дата початку періоду у форматі UnixTimeStamp
finishTimestamp?: number; // дата завершення періоду у форматі UnixTimeStamp
excludeZero?: boolean; // виключити пусті дати
}Обʼєкт Limitation
export type Limitation = {
offset?: number; // початкова позиція
count?: number; // к-сть файлів у відображенні (не більше 100)
}Обʼєкт IDPTaskInfo
export type IDPTaskInfo = {
source: IDPTaskSource; // обʼєкт IDPTaskSource
mimeType: string; // тип файла
fileName: string; // назва файла
}Обʼєкт IDPDocType
export type IDPDocType = {
docTypeId: number; // ід типу документа
docTypeAlias: string; // псевдонім типу документа
docType: string; // назва типу документа
}Опис методів для сервісу EDIN-IDP
Дана інструкція описує послідовність викликів методів API, призначених для розпізнавання та перетворення PDF-файлів у структуровані документи.
Для роботи з методами сервісу EDIN-IDP у вас має бути IDP_API_KEY, який потрібно вказувати в Header в параметрі x-api-key
Надсилання документа на розпізнання
Під час одного запиту можна надіслати лише один файл.
REQUEST
| URL | https://idp.edin.ua/api/docs/upload |
| Method | POST |
| Header | x-api-key={IDP_API_KEY} |
| Body | Content-Type: multipart/form-data. |
| Params | |
| from_user | Опціонально. Логін користувача свого акаунту, від імені якого буде здійснено відправку на конвертацію |
Приклад запиту:
curl -v -H "x-api-key: {IDP_API_KEY}" -F upload='@{path to file}' https://idp.edin.ua/api/docs/uploadRESPONSE
-
У відповідь надходить унікальний ідентифікатор (UUID) завдання на конвертацію.
Отримання списку файлів
REQUEST
| URL | https://idp.edin.ua/api/docs/search |
| Method | POST |
| Header | x-api-key={IDP_API_KEY} |
| Body |
Content-Type: application/json
|
| Params |
|
| from_user | Опціонально. Логін користувача свого акаунту, від імені якого буде здійснено фільтрацію документів. |
Приклад запиту:
curl -v -X POST -H "x-api-key: MY_TEST_API_KEY" -H "Content-Type: application/json" --data '{"status": ["DONE", "VERIFIED"]}' https://idp.edin.ua/api/docs/searchRESPONSE
- Масив об'єктів
IDPTask[].
Приклад відповіді:
[
{
"id": 293,
"userId": 2000988,
"uuid": "90c5f7ae-5747-4f56-bf07-068bfe8160cf",
"status": "DONE",
"date": 1753077616,
"doneDate": 1753077643,
"info": {
"source": "API",
"mimeType": "image/jpeg",
"fileName": "300625_111323_1493.jpg"
}
}
]Отримання результату конвертації файлу
REQUEST
| URL | https://idp.edin.ua/api/docs/response |
| Method | GET |
| Header | x-api-key={IDP_API_KEY} |
| Params | |
| uuid | uuid завдання |
Приклад запиту:
curl -v -H "x-api-key: {IDP_API_KEY}" 'https://idp.edin.ua/api/docs/response?uuid=90c5f7ae-5747-4f56-bf07-068bfe8160cf'RESPONSE
- У відповідь надходить json-масив структурованих документів. Структура документів може бути або типовою (універсальною), або згідно з індивідуальними налаштуваннями
Отримання вмісту файлу, відправленого на конвертацію
REQUEST
| URL | https://idp.edin.ua/api/docs/request |
| Method | GET |
| Header | x-api-key={IDP_API_KEY} |
| Params | |
| uuid | uuid завдання |
Приклад запиту:
curl -v -H "x-api-key: {IDP_API_KEY}" 'https://idp.edin.ua/api/docs/request?uuid=90c5f7ae-5747-4f56-bf07-068bfe8160cf'RESPONSE
- У відповідь надходить оригінальний файл, який було відправлено на розпізнавання та перетворення.
Зміна статусу завдання
REQUEST
| URL | https://idp.edin.ua/api/docs/status |
| Method | POST |
| Header | x-api-key={IDP_API_KEY} |
| Params | |
| uuid | uuid завдання |
| status | одне зі значень [CREATED, VERIFIED, PROCESSED] |
CREATED - цей статус можна вказати у випадку якщо документ має поточний статус ERROR. Після зміни статусу на CREATED, документ буде повторно конвертований.
VERIFIED - цей статус можна вказати у випадку якщо документ має поточний статус DONE.
PROCESSED - цей статус можна вказати у випадку якщо документ має поточний статус DONE або VERIFIED
Приклад запиту:
curl -v -H "x-api-key: {IDP_API_KEY}" 'https://idp.edin.ua/api/docs/status?uuid=90c5f7ae-5747-4f56-bf07-068bfe8160cf&status=PROCESSED'RESPONSE
У відповіді повертається повідомлення та статус:
| STATUS | Message | Коментар |
| 200 | Запит успішно опрацьовано | Статус задачі змінено успішно |
| 400 | Unsupported 'status' param value | Неправильний статус завдання. Вкажіть коректний статус |
| 400 | Only task with status DONE can be changed to VERIFIED. Current task status is: PROCESSED | Неправильна послідовність зміни статусу |
| 500 | Internal Server Error. Chanel ID: 123456 | Непередбачена внутрішня помилка. Необхідно звернутись до тех. підтримки для зʼясування причини помилки. |