Видобуток API¶

Odoo надає послугу для автоматизації обробки документів типу рахунки-фактури, банківські виписки, витрати або резюме.

Сервіс сканує документи за допомогою механізму OCR, а потім використовує алгоритми на основі AI для вилучення полів, що цікавлять, таких як загальна сума, дата оплати або рядки рахунків для рахунків, початковий та кінцевий баланси, дата для банківських виписок, загальна сума, дата для витрат або ім’я, електронна пошта, номер телефону для резюме.

Ця послуга є платною. Кожна обробка документа коштуватиме вам один кредит з вашого облікового запису IAP для оцифрування документів. Більше інформації про облікові записи IAP можна знайти тут.

Ви можете використовувати цей сервіс безпосередньо в додатку для бухгалтерського обліку, витрат або рекрутингу або через API. API Extract, детально описаний у наступному розділі, дозволяє вам інтегрувати наш сервіс безпосередньо у ваші власні проекти.

Огляд¶

API вилучення використовує протокол JSON-RPC2; його кінцеві маршрути розташовані за адресою https://extract.api.odoo.com.

Версія¶

Версія API вилучення вказується в маршруті.

Найновіші версії:

рахунки-фактури: 123
банківські виписки: 100
витрати: 132
заявник: 102

Потік¶

Послідовність дій однакова для кожного типу документа.

Викличте /parse, щоб надіслати документи (один виклик для кожного документа). У разі успіху ви отримаєте document_token у відповіді.
Потім вам доведеться регулярно опитувати /get_result, щоб отримати статус парсингу документа.

Або ж ви можете надати webhook_url під час виклику /parse, і ви отримаєте сповіщення (через POST-запит), коли результат буде готовий.

Для всіх них слід використовувати метод HTTP POST. Реалізацію повного циклу для рахунків-фактур на Python можна знайти тут, а токен для інтеграційного тестування надається в розділі інтеграційного тестування.

Розбір¶

Запит на оцифрування документа. Маршрут поверне document_token, який можна використовувати для отримання результату вашого запиту.

Маршрути¶

/api/extract/invoice/2/parse

/api/extract/bank_statement/1/parse

/api/extract/expense/2/parse

/api/extract/applicant/2/parse

Запит¶

jsonrpc (обов’язково)

див. JSON-RPC2

method (обов’язково)

див. JSON-RPC2

id (обов’язково)

див. JSON-RPC2

params

account_token (обов’язково)

Токен облікового запису IAP, з якого будуть списані кредити. Кожен успішний виклик коштує один кредит.

version (обов’язково)

Версія визначатиме формат ваших запитів та формат відповіді сервера. Вам слід використовувати найновіша доступна версія.

documents (обов’язково)

Документ має бути наданий як рядок Base64 у кодуванні ASCII. Список має містити лише один документ. Це поле є списком лише з міркувань застарілих версій. Підтримувані формати: pdf, png та jpg.

dbuuid (необов’язково)

Унікальний ідентифікатор бази даних Odoo.

webhook_url (необов’язково)

Можна надати URL-адресу вебхука. Порожній POST-запит буде надіслано на адресу webhook_url/document_token, коли результат буде готовий.

user_infos (необов’язково)

Інформація про особу, яка надсилає документ до служби вилучення. Це може бути клієнт або постачальник (залежно від perspective). Ця інформація не є обов’язковою для роботи служби, але вона значно покращує якість результату.

user_company_vat (необов’язковий): Номер платника ПДВ користувача.
user_company_name (необов’язково): Назва компанії користувача.
user_company_country_code (необов’язковий): Код країни користувача. Формат: ISO3166 alpha-2.
user_lang (необов’язковий): Мова користувача. Формат: language_code + _ + locale (наприклад, fr_FR, en_US).
user_email (необов’язково): Електронна адреса користувача.
purchase_order_regex (необов’язково): Регулярний вираз для ідентифікації замовлення на купівлю. Якщо не вказано, за замовчуванням використовуватиметься формат замовлення на купівлю Odoo.
perspective (необов’язково): Може бути client або supplier. Це поле корисне лише для рахунків-фактур. client означає, що надана інформація користувача стосується клієнта рахунку. supplier означає, що вона пов’язана з постачальником. Якщо не вказано, буде використано значення клієнт.

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "account_token": string,
        "version": int,
        "documents": [string],
        "dbuuid": string,
        "webhook_url": string,
        "user_infos": {
            "user_company_vat": string,
            "user_company_name": string,
            "user_company_country_code": string,
            "user_lang": string,
            "user_email": string,
            "purchase_order_regex": string,
            "perspective": string,
        },
    },
    "id": string,
}

Примітка

Параметр user_infos необов’язковий, але він значно покращує якість результату, особливо для рахунків-фактур. Чим більше інформації ви можете надати, тим краще.

Відповідь¶

jsonrpc

див. JSON-RPC2

id

див. JSON-RPC2

result

status: Код, що вказує на статус запиту. Див. таблицю нижче.
status_msg: Рядок, що містить докладні відомості про стан запиту.
document_token: Відображати лише в разі успішного запиту.

status	status_msg
`success`	Успіх
`error_unsupported_version`	Непідтримувана версія
`error_internal`	Виникла помилка
`error_no_credit`	У вас недостатньо кредиту
`error_unsupported_format`	Непідтримуваний формат файлу
`error_maintenance`	Сервер зараз на технічному обслуговуванні, спробуйте пізніше.

{
    "jsonrpc": "2.0",
    "id": string,
    "result": {
        "status": string,
        "status_msg": string,
        "document_token": string,
    }
}

Примітка

API насправді не використовує схему помилок JSON-RPC. Натомість API має власну схему помилок, яка входить до успішного результату JSON-RPC.

Get results¶

Маршрути¶

/api/extract/invoice/2/get_result

/api/extract/bank_statement/1/get_result

/api/extract/expense/2/get_result

/api/extract/applicant/2/get_result

Запит¶

jsonrpc (обов’язково)

див. JSON-RPC2

method (обов’язково)

див. JSON-RPC2

id (обов’язково)

див. JSON-RPC2

params

version (обов’язково): Версія має збігатися з версією, переданою в запит /parse.
document_token (обов’язковий): document_token, для якого потрібно отримати поточний стан парсингу.
account_token (обов’язково): Токен облікового запису IAP, який було використано для надсилання документа.

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "version": int,
        "document_token": int,
        "account_token": string,
    },
    "id": string,
}

Відповідь¶

Під час отримання результатів розбору виявлене поле значно варіюється залежно від типу документа. Кожна відповідь – це список словників, по одному для кожного документа. Ключі словника – це назва поля, а значення – це значення поля.

jsonrpc

див. JSON-RPC2

id

див. JSON-RPC2

result

status

Код, що вказує на статус запиту. Див. таблицю нижче.

status_msg

Рядок, що містить докладні відомості про стан запиту.

results

Відображати лише в разі успішного запиту.

full_text_annotation: Містить необроблений повний результат OCR для документа.

status	status_msg
`success`	Успіх
`error_unsupported_version`	Непідтримувана версія
`error_internal`	Виникла помилка
`error_maintenance`	Сервер зараз на технічному обслуговуванні, спробуйте пізніше.
`error_document_not_found`	Документ не знайдено
`error_unsupported_size`	Документ відхилено, оскільки він занадто малий
`error_no_page_count`	Не вдалося отримати кількість сторінок PDF-файлу
`error_pdf_conversion_to_images`	Не вдалося конвертувати PDF-файл у зображення
`error_password_protected`	PDF-файл захищено паролем
`error_too_many_pages`	Документ містить забагато сторінок

{
    "jsonrpc": "2.0",
    "id": string,
    "result": {
        "status": string,
        "status_msg": string,
        "results": [
            {
                "full_text_annotation": string,
                "feature_1_name": feature_1_result,
                "feature_2_name": feature_2_result,
                ...
            },
            ...
        ]
    }
}

Загальні поля¶

`feature_result`¶

Кожне поле, яке нас цікавить, таке як загальна сума або термін виконання, також називається ознаками. Вичерпний перелік усіх вилучених ознак, пов’язаних із певним типом документа, можна знайти в розділах нижче.

Для кожної функції ми повертаємо список кандидатів і виділяємо кандидата, який, за прогнозами нашої моделі, найкраще підходить для функції.

selected_value (необов’язково): Найкращий кандидат на цю функцію.
selected_values (необов’язково): Найкращі кандидати на цю функцію.
candidates (необов’язково): Список усіх кандидатів на цю функцію, відсортованих за зменшенням показника достовірності.

"feature_name": {
    "selected_value": candidate_12,
    "candidates": [candidate_12, candidate_3, candidate_4, ...]
}

кандидат¶

Для кожного кандидата ми вказуємо його представництво та позицію в документі. Кандидати відсортовані в порядку зменшення придатності.

content: Представлення кандидата.
coords: [center_x, center_y, width, height, rotation_angle]. Розташування та розміри відносяться до розміру сторінки, а отже, між 0 і 1. Кут – це поворот за годинниковою стрілкою, виміряний у градусах.
page: Сторінка оригіналу документа, на якому знаходиться кандидат (починається з 0).

"candidate": [
    {
        "content": string|float,
        "coords": [float, float, float, float, float],
        "page": int
    },
    ...
]

Рахунки¶

Рахунки-фактури є складними та можуть містити багато різних полів. У наступній таблиці наведено вичерпний перелік усіх полів, які ми можемо витягти з рахунку-фактури.

Назва функції	Специфіка
`SWIFT_code`	`content` - це словник, закодований як рядок. Він містить інформацію про виявлений код SWIFT (або BIC). Ключі: `bic` виявлений BIC (рядок). `name` (необов’язково) назва банку (рядок). `country_code` ISO3166 alpha-2 код країни банку (рядок). `city` (необов’язково) місто банку (рядок). `verified_bic` True, якщо BIC знайдено в нашій БД (bool). Назва та місто присутні, лише якщо verified_bic має значення true.
`iban`	`content` – це рядок
`aba`	`content` – це рядок
`VAT_Number`	`content` – це рядок Залежно від значення perspective у user_infos, це буде номер платника ПДВ постачальника або клієнта. Якщо perspective є клієнтом, це буде номер платника ПДВ постачальника. Якщо це постачальник, це номер платника ПДВ клієнта.
`qr-bill`	`content` – це рядок
`payment_ref`	`content` – це рядок
`purchase_order`	`content` – це рядок Використовує `selected_values` замість `selected_value`
`country`	`content` – це рядок
`currency`	`content` – це рядок
`date`	`content` – це рядок Формат : YYYY-MM-DD
`due_date`	Те саме, що для `date`
`total_tax_amount`	`content` - це число з плаваючою комою
`invoice_id`	`content` – це рядок
`subtotal`	`content` - це число з плаваючою комою
`total`	`content` - це число з плаваючою комою
`supplier`	`content` – це рядок
`client`	`content` – це рядок
`email`	`content` – це рядок
`website`	`content` – це рядок

`invoice_lines` - це функція¶

Повертається у вигляді списку словників, де кожен словник представляє рядок рахунку-фактури.

"invoice_lines": [
    {
        "description": string,
        "quantity": float,
        "subtotal": float,
        "total": float,
        "taxes": list[float],
        "total": float,
        "unit_price": float
    },
    ...
]

Виписки з банківського рахунку¶

У наступній таблиці наведено список усіх полів, які витягуються з банківських виписок.

Назва функції	Специфіка
`balance_start`	`content` - це число з плаваючою комою
`balance_end`	`content` - це число з плаваючою комою
`date`	`content` – це рядок

`bank_statement_lines` - це функція¶

Повертається у вигляді списку словників, де кожен словник представляє рядок банківської виписки.

"bank_statement_lines": [
    {
        "amount": float,
        "description": string,
        "date": string,
    },
    ...
]

Витрати¶

Витрати менш складні, ніж рахунки-фактури. У наступній таблиці наведено вичерпний перелік усіх полів, які ми можемо витягти зі звіту про витрати.

Назва функції	Специфіка
`description`	`content` – це рядок
`country`	`content` – це рядок
`date`	`content` – це рядок
`total`	`content` - це число з плаваючою комою
`currency`	`content` – це рядок

Заявник¶

Цей третій тип документа призначений для обробки резюме. У наступній таблиці наведено вичерпний перелік усіх полів, які ми можемо витягти з резюме.

Назва функції	Специфіка
`name`	`content` – це рядок
`email`	`content` – це рядок
`phone`	`content` – це рядок
`mobile`	`content` – це рядок

Інтеграційне тестування¶

Ви можете протестувати свою інтеграцію, використовуючи integration_token як account_token у запиті /parse.

Використання цього токена переводить вас у тестовий режим і дозволяє імітувати весь процес без фактичного розбору документа та без стягнення плати в одному кредиті за кожен успішний розбір документа.

Єдині технічні відмінності в тестовому режимі полягають у тому, що документ, який ви надсилаєте, не аналізується системою, і відповідь, яку ви отримуєте від /get_result, є жорстко закодованою.

Реалізацію повного циклу для рахунків-фактур на Python можна знайти тут.

Редагувати на GitHub

Видобуток API¶

Огляд¶

Версія¶

Потік¶

Розбір¶

Маршрути¶

Запит¶

Відповідь¶

Get results¶

Маршрути¶

Запит¶

Відповідь¶

Загальні поля¶

feature_result¶

кандидат¶

Рахунки¶

invoice_lines - це функція¶

Виписки з банківського рахунку¶

bank_statement_lines - це функція¶

Витрати¶

Заявник¶

Інтеграційне тестування¶

`feature_result`¶

`invoice_lines` - це функція¶

`bank_statement_lines` - це функція¶