Видобуток API¶

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

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

Ця послуга є платною. Кожна обробка документа коштуватиме вам один кредит. Кредити можна придбати на сайті iap.odoo.com.

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

Огляд¶

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

Версія¶

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

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

рахунки: 122
витрати: 132
заявник: 102

Потік¶

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

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

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

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

Аналіз¶

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

Маршрути¶

/api/extract/invoice/2/parse

/api/extract/expense/2/parse

/api/extract/applicant/2/parse

Запит¶

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

див. JSON-RPC2

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

див. JSON-RPC2

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

див. JSON-RPC2

params

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

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

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

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

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

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

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.

Отримати результати¶

Маршрути¶

/api/extract/invoice/2/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 (обов’язково): Токен облікового запису, який було використано для надсилання документа.

{
    "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` є рядком

`feature_result` для функції `invoice_lines`¶

Він має більш специфічну структуру. Це, по суті, список словників, де кожен словник представляє рядок рахунку-фактури. Кожне значення має структуру feature_result.

"invoice_lines": [
    {
        "description": feature_result,
        "discount": feature_result,
        "product": feature_result,
        "quantity": feature_result,
        "subtotal": feature_result,
        "total": feature_result,
        "taxes": feature_result,
        "total": feature_result,
        "unit": feature_result,
        "unit_price": feature_result
    },
    ...
]

Витрати¶

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

Назва функції	Специфіка
`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 можна знайти тут.

Edit on GitLab

Видобуток API¶

Огляд¶

Версія¶

Потік¶

Аналіз¶

Маршрути¶

Запит¶

Відповідь¶

Отримати результати¶

Маршрути¶

Запит¶

Відповідь¶

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

feature_result¶

кандидат¶

Рахунки¶

feature_result для функції invoice_lines¶

Витрати¶

Заявник¶

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

`feature_result`¶

`feature_result` для функції `invoice_lines`¶