Видобуток API¶

Odoo надає послугу, яка дозволяє вам автоматизувати обробку ваших рахунків. Служба сканує ваш документ за допомогою механізму оптичного розпізнавання символів (OCR), а потім використовує алгоритми на основі штучного інтелекту, щоб витягти цікаві поля, такі як загальна сума, термін виконання або рядки рахунків. Більше функціональної інформації можна знайти на демо-сторінці.

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

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

Рахунки¶

API екстракту використовує протокол JSON-RPC 2. Різні маршрути розташовані за такою адресою: https://iap-extract.odoo.com.

Очікуваний успішний потік¶

Зателефонуйте /iap/invoice_extract/parse, щоб надіслати свої рахунки(один виклик для кожного рахунку). У разі успіху ви отримаєте document_id у відповіді.
Потім вам доведеться регулярно опитувати /iap/invoice_extract/get_results, щоб отримати статус аналізу документа.
Отримавши результат, ви можете підтвердити його, викликавши /iap/invoice_extract/validate і надіславши очікувані значення. Цей крок є необов’язковим, але значною мірою допомагає покращити систему.

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

Маршрути¶

`/iap/invoice_extract/parse`¶

Опис¶

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

Тіло запиту¶

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

Має бути точно “2.0”.

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

Має бути “call”.

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

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

params

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

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

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

Версія визначатиме формат ваших запитів і формат відповіді сервера. Деякі результати можуть бути недоступні в старіших версіях. Для поточної версії 1.2.0 надішліть ‘120’. Якщо не вказано, використовуватиметься остання версія.

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

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

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

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

user_company_vat (необов’язковий): Номер ПДВ клієнта.
user_company_name (необов’язково): Назва компанії клієнта.
user_company_country_code (необов’язковий): Код країни клієнта. Формат: ISO3166 alpha-2.
user_lang (необов’язковий): Мова клієнта. Формат: language_code + _ + locale (наприклад: fr_FR, en_US).
user_email (необов’язково): Ел. пошта клієнта.

{
    "jsonrpc": string,
    "method": string,
    "params": {
            "account_token": string (hex),
            "version": int,
            "documents": [string],
            "user_infos": {
                    "user_company_vat": string,
                    "user_company_name": string,
                    "user_company_country_code": string,
                    "user_lang": string,
                    "user_email": string,
            },
    },
    "id": string (hex),
}

Відповідь¶

jsonrpc

Рядок із зазначенням версії протоколу JSON-RPC. Це буде “2.0”.

id

Ідентифікатор, який ви встановили в тілі запиту.

result

status_code: The code indicating the status of the request. status_code is 0 in case of success. Other status_code are detailed in the table below.
status_msg: A string giving verbose details about the request status.
document_id: Відображати лише в разі успішного запиту.

Примітка

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

status_code	status_msg
0	Успіх
2	Виникла помилка
3	У вас недостатньо кредиту
6	Непідтримуваний формат файлу
9	На даний момент сервер знаходиться на технічному обслуговуванні. Будь-ласка спробуйте пізніше.

{
    "jsonrpc": string,
    "id": string,
    "result": {
        "status_code": int,
        "status_msg": string,
        "document_id": int,
    }
}

`/iap/invoice_extract/get_results`¶

Опис¶

Запитувати результати ідентифікаторів документів, отриманих за допомогою маршруту /parse. Може повертати результати або повідомлення «запит очікує на розгляд».

Тіло запиту¶

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

Same as for /parse.

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

Same as for /parse.

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

Same as for /parse.

params:

version (обов’язково): Same as for /parse.
documents_ids (обов’язково): Список document_id, для якого ви хочете отримати поточний статус аналізу.

{
    "jsonrpc": string,
    "method": string,
    "params": {
        "version": int,
        "documents_ids": [int]
    },
    "id": string (hex),
}

Відповідь¶

jsonrpc

Same as for /parse.

id

Same as for /parse.

result

Словник, де кожен ключ є ідентифікатором документа. Для кожного document_id:

status_code: The code indicating the status of the request. status_code is 0 in case of success. Other status_code are detailed in the table below.
status_msg: A string giving verbose details about the request status.
results: Відображати лише в разі успішного запиту.

Попередження

ключі результату є рядками, незважаючи на те, що document_ids, подані в тілі запиту, є цілими числами.

status_code	status_msg
0	Успіх
1	Не готовий
2	Виникла помилка
9	На даний момент сервер знаходиться на технічному обслуговуванні. Будь-ласка спробуйте пізніше.

{
    "jsonrpc": string,
    "id": string,
    "result": {
        "document_id_1": {
            "status_code": int,
            "status_msg": str,
            "results": [{"feature_1_name": feature_1_result,
                         "feature_2_name": feature_2_result,
                         …
                        }]
            },
        "document_id_2": {
            "status_code": int,
            "status_msg": str,
            "results": [{"feature_1_name": feature_1_result,
                         "feature_2_name": feature_2_result,
                         …
                        }]
            },
            ...
    }
}

`feature_result`¶

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

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

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

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

`candidate`¶

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

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

{
    "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.
`VAT_Number`	content є рядком
`country`	content є рядком
`currency`	content є рядком
`date`	content є рядком Формат : YYYY-MM-DD HH:MM:SS
`due_date`	Те саме, що для `date`
`global_taxes`	content є плаваючою точкою candidate має додаткове поле `amount_type`. Його значення завжди дорівнює відсоткам. selected_values – це список кандидатів.
`global_taxes_amount`	content є плаваючою точкою
`invoice_id`	content є рядком
`subtotal`	content є плаваючою точкою
`total`	content є плаваючою точкою
`supplier`	content є рядком

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

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

[
    {
        "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
    },
    ...
]

`/iap/invoice_extract/validate`¶

Опис¶

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

Тіло запиту¶

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

Same as for /parse.

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

Same as for /parse.

params

documents_id (обов’язково): Ідентифікатор документа, для якого ви хочете перевірити результат.
values: Містить перевірку для кожної функції. Для рахунків поле merged_line вказує на те, об’єднано рядки чи ні.

Примітка

Вам не потрібно перевіряти всі функції, щоб перевірка пройшла успішно. Однак /validate не можна викликати кілька разів для одного рахунку. Тому вам слід перевірити всі функції, які ви хочете підтвердити одночасно.

{
    "jsonrpc": string,
    "method": string,
    "params": {
        "document_id": int,
        "values": {
            "merged_lines": bool
            "feature_name_1": validation_1,
            "feature_name_2": validation_2,
            ...
        }
    },
    "id": string (hex),
}

`validation`¶

Перевірка для даної функції – це словник, що містить текстове представлення очікуваного значення для даної функції. Цей формат застосовується до всіх функцій, за винятком global_taxes і invoice_lines, які мають більш складний формат перевірки.

{ "content": string|float }

перевірка для `global_taxes`¶

content - це список словників. Кожен словник представляє податок:

amount: Сума, з якої нараховується податок.
tax_amount: Сума податку.
tax_amount_type: Указує, чи є tax_amount відсоток чи фіксоване значення. Тип необхідно вказати за допомогою літерального рядка «фіксований» або «відсоток».
tax_price_include: Вказує, чи містить сума податок чи ні.

{"content": [
    {
        "amount": float,
        "tax_amount": float,
        "tax_amount_type": "fixed"|"percent",
        "tax_price_include": bool
    },
    ...
]}

перевірка для `invoice_lines`¶

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

{"lines": [
    {
        "description": string,
        "quantity": float,
        "unit_price": float,
        "product": string,
        "taxes_amount": float,
        "taxes": [
                    {
                        "amount": float,
                        "type": "fixed"|"percent",
                        "price_include": bool
                    },
                    ...
                ],
        "subtotal": float,
        "total": float
    },
    ...
]}

Відповідь¶

jsonrpc

Same as for /parse.

id

Same as for /parse.

result

status_code: The code indicating the status of the request. status_code is 0 in case of success. Other status_code are detailed in the table below.
status_msg: A string giving verbose details about the request status.

status_code	status_msg
0	Успіх
12	Неправильний формат перевірки

{
    "jsonrpc": string,
    "id": string,
    "result": {
        "status_code": int,
        "status_msg": string,
    }
}

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

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

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

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

Реалізацію повного потоку на Python можна знайти тут.

Edit on GitHub

Видобуток API¶

Рахунки¶

Очікуваний успішний потік¶

Маршрути¶

/iap/invoice_extract/parse¶

Опис¶

Тіло запиту¶

Відповідь¶

/iap/invoice_extract/get_results¶

Опис¶

Тіло запиту¶

Відповідь¶

feature_result¶

candidate¶

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

/iap/invoice_extract/validate¶

Опис¶

Тіло запиту¶

validation¶

перевірка для global_taxes¶

перевірка для invoice_lines¶

Відповідь¶

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

`/iap/invoice_extract/parse`¶

`/iap/invoice_extract/get_results`¶

`feature_result`¶

`candidate`¶

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

`/iap/invoice_extract/validate`¶

`validation`¶

перевірка для `global_taxes`¶

перевірка для `invoice_lines`¶