API kinyerés¶

Odoo provides a service to automate the processing of documents of type invoices, bank statements, expenses or resumes.

The service scans documents using an OCR engine and then uses AI-based algorithms to extract fields of interest such as the total, due date, or invoice lines for invoices, the initial and final balances, the date for bank statements, the total, date for expenses, or the name, email, phone number for resumes.

This service is a paid service. Each document processing will cost you one credit from your document digitization IAP account. More information about IAP accounts can be found here.

Ezt a szolgáltatást közvetlenül használhatja a Számvitel, Költség vagy Toborzás alkalmazásban, vagy az API-n keresztül. Az API kinyerés, amely a következő szakaszban részletezett, lehetővé teszi, hogy szolgáltatásunkat közvetlenül integrálja saját projektjeibe.

Áttekintés¶

Az API kinyerés a JSON-RPC2 protokollt használja; végponti útvonalai a https://extract.api.odoo.com címen találhatók.

Verzió¶

Az API kinyerés verziója az útvonalban van meghatározva.

A legújabb verziók:

invoices: 123
bank statements: 100
költségek: 132
pályázó: 102

Folyamat¶

A folyamat minden dokumentumtípus esetében azonos.

Hívja a /parse-t a dokumentumok benyújtásához (egy hívás minden dokumentumhoz). Siker esetén egy document_token-t kap a válaszban.
Ezután rendszeresen kell lekérdeznie a /get_result-et, hogy megkapja a dokumentum feldolgozási állapotát.

Alternatív megoldásként megadhat egy webhook_url-t a /parse hívásakor, és értesítést kap (egy POST kérésen keresztül), amikor az eredmény elkészült.

Az összes esetben a HTTP POST módszert kell használni. A számlák teljes folyamatának python megvalósítása itt található, és egy token az integrációs teszteléshez a integrációs tesztelési szakaszban van megadva.

Feldolgozás¶

Request the digitization of a document. The route will return a document_token that you can use to fetch the result of your request.

Útvonalak¶

/api/extract/invoice/2/parse

/api/extract/bank_statement/1/parse

/api/extract/expense/2/parse

/api/extract/applicant/2/parse

Kérelem¶

jsonrpc (kötelező)

lásd JSON-RPC2

method (kötelező)

lásd JSON-RPC2

id (kötelező)

lásd JSON-RPC2

params

account_token (kötelező)

The token of the IAP account from which credits will be charged. Each successful call costs one credit.

version (kötelező)

A verzió meghatározza a kérések formátumát és a szerver válaszának formátumát. Az elérhető legújabb verziót kell használnia.

documents (kötelező)

The document must be provided as a Base64 string in the ASCII encoding. The list should contain only one document. This field is a list only for legacy reasons. The supported formats are pdf, png and jpg.

dbuuid (opcionális)

Az Odoo adatbázis egyedi azonosítója.

webhook_url (opcionális)

Megadható egy webhook URL. Egy üres POST kérés kerül elküldésre a webhook_url/document_token címre, amikor az eredmény elkészül.

user_infos (opcionális)

Információ a dokumentumot az extract szolgáltatásnak küldő személyről. Lehet az ügyfél vagy a szállító (a perspective függvényében). Ez az információ nem szükséges a szolgáltatás működéséhez, de jelentősen javítja az eredmény minőségét.

user_company_vat (opcionális): A felhasználó áfa száma.
user_company_name (opcionális): A felhasználó cégének neve.
user_company_country_code (opcionális): A felhasználó országkódja. Formátum: ISO3166 alpha-2.
user_lang (opcionális): A felhasználó nyelve. Formátum: language_code + _ + locale (pl. fr_FR, en_US).
user_email (opcionális): A felhasználó e-mail címe.
purchase_order_regex (opcionális): Regex a beszerzési rendelés azonosításához. Ha nincs megadva, az Odoo PO formátum lesz az alapértelmezett.
perspective (opcionális): Lehet client vagy supplier. Ez a mező csak számlák esetén hasznos. A client azt jelenti, hogy a megadott felhasználói információk a számla ügyfelére vonatkoznak. A supplier azt jelenti, hogy a szállítóra vonatkozik. Ha nincs megadva, az ügyfél lesz használva.

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

Megjegyzés

A user_infos paraméter opcionális, de jelentősen javítja az eredmény minőségét, különösen a számlák esetében. Minél több információt tud megadni, annál jobb.

Válasz¶

jsonrpc

lásd JSON-RPC2

id

lásd JSON-RPC2

result

status: A kérés állapotát jelző kód. Lásd az alábbi táblázatot.
status_msg: Egy szöveg, amely részletes információkat ad a kérés állapotáról.
document_token: Csak akkor van jelen, ha a kérés sikeres.

állapot	állapot_üzenet
`sikeres`	Siker
`error_unsupported_version`	Nem támogatott verzió
`error_internal`	Hiba történt
`error_no_credit`	Nincs elegendő kreditje
`error_unsupported_format`	Nem támogatott fájlformátum
`error_maintenance`	A szerver jelenleg karbantartás alatt áll, kérjük, próbálja meg később

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

Megjegyzés

Az API valójában nem használja a JSON-RPC hibasémát. Ehelyett az API saját hibasémát tartalmaz egy sikeres JSON-RPC eredményen belül.

Eredmények lekérése¶

Útvonalak¶

/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

Kérelem¶

jsonrpc (kötelező)

lásd JSON-RPC2

method (kötelező)

lásd JSON-RPC2

id (kötelező)

lásd JSON-RPC2

params

version (kötelező): A verziónak meg kell egyeznie a /parse kéréshez megadott verzióval.
document_token (kötelező): Az a document_token, amelyhez a jelenlegi feldolgozási állapotot szeretné lekérni.
account_token (kötelező): The token of the IAP account that was used to submit the document.

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

Válasz¶

Amikor a feldolgozás eredményeit lekérjük, a felismerhető mezők nagymértékben változhatnak a dokumentum típusától függően. Minden válasz egy szótárak listája, egy-egy minden dokumentumhoz. A szótár kulcsai a mező nevei, az értékek pedig a mezők értékei.

jsonrpc

lásd JSON-RPC2

id

lásd JSON-RPC2

result

status

A kérés állapotát jelző kód. Lásd az alábbi táblázatot.

status_msg

Egy szöveg, amely részletes információkat ad a kérés állapotáról.

results

Csak akkor van jelen, ha a kérés sikeres.

full_text_annotation: Contains the unprocessed full result from the OCR for the document.

állapot	állapot_üzenet
`sikeres`	Siker
`error_unsupported_version`	Nem támogatott verzió
`error_internal`	Hiba történt
`error_maintenance`	A szerver jelenleg karbantartás alatt áll, kérjük, próbálja meg később
`error_document_not_found`	A dokumentum nem található
`error_unsupported_size`	A dokumentum elutasításra került, mert túl kicsi
`error_no_page_count`	Nem sikerült megszerezni a PDF fájl oldalszámát
`error_pdf_conversion_to_images`	Nem sikerült a PDF-et képekké konvertálni
`error_password_protected`	A PDF fájl jelszóval védett
`error_too_many_pages`	A dokumentum túl sok oldalt tartalmaz

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

Gyakori mezők¶

`feature_result`¶

Minden olyan mezőt, amelyet ki szeretnénk nyerni a dokumentumból, mint például az összeg vagy az esedékességi dátum, jellemzőknek is nevezünk. Az adott dokumentumtípushoz kapcsolódó összes kinyert jellemző kimerítő listája az alábbi szakaszokban található.

Minden jellemző esetében visszaadunk egy jelöltlistát, és kiemeljük azt a jelöltet, amelyet a modellünk a legmegfelelőbbnek jósol a jellemzőhöz.

selected_value (opcionális): A legjobb jelölt ehhez a jellemzőhöz.
selected_values (opcionális): A legjobb jelöltek ehhez a jellemzőhöz.
candidates (opcionális): Az összes jelölt listája ehhez a funkcióhoz, csökkenő megbízhatósági pontszám szerint rendezve.

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

jelölt¶

Minden jelölthöz megadjuk annak reprezentációját és pozícióját a dokumentumban. A jelöltek csökkenő alkalmassági sorrendben vannak rendezve.

content: A jelölt reprezentációja.
coords: [center_x, center_y, width, height, rotation_angle]. A pozíció és a méretek az oldal méretéhez viszonyítva relatívak, ezért 0 és 1 között vannak. A szög az óramutató járásával megegyező irányú forgatás fokokban mérve.
page: Az eredeti dokumentum azon oldala, amelyen a jelölt található (0-tól kezdődik).

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

Számlák¶

A számlák összetettek, és sok különböző mezőt tartalmazhatnak. Az alábbi táblázat kimerítő listát ad az összes mezőről, amelyet ki tudunk nyerni egy számlából.

Funkció neve	Specificities
`SWIFT_code`	A `content` egy szótár, amely karakterláncként van kódolva. Információkat tartalmaz a észlelt SWIFT kódról (vagy BIC). Kulcsok: `bic` észlelt BIC (karakterlánc). `name` (opcionális) bank neve (karakterlánc). `country_code` a bank ISO3166 alpha-2 országkódja (karakterlánc). `city` (opcionális) a bank városa (karakterlánc). `verified_bic` Igaz, ha a BIC megtalálható az adatbázisunkban (bool). A név és a város csak akkor jelenik meg, ha a verified_bic igaz.
`iban`	`content` egy karakterlánc
`aba`	`content` egy karakterlánc
`VAT_Number`	`content` egy karakterlánc A user_infos perspektíva értékétől függően ez lesz a szállító vagy az ügyfél ÁFA száma. Ha a perspektíva ügyfél, akkor a szállító ÁFA száma lesz. Ha szállító, akkor az ügyfél ÁFA száma.
`qr-bill`	`content` egy karakterlánc
`payment_ref`	`content` egy karakterlánc
`purchase_order`	`content` egy karakterlánc `selected_value` helyett `selected_values` használata
`country`	`content` egy karakterlánc
`currency`	`content` egy karakterlánc
`date`	`content` egy karakterlánc Formátum: ÉÉÉÉ-HH-NN
`due_date`	Ugyanaz, mint a `date` esetében
`total_tax_amount`	`content` egy lebegőpontos szám
`invoice_id`	`content` egy karakterlánc
`subtotal`	`content` egy lebegőpontos szám
`total`	`content` egy lebegőpontos szám
`supplier`	`content` egy karakterlánc
`client`	`content` egy karakterlánc
`email`	`content` egy karakterlánc
`website`	`content` egy karakterlánc

`invoice_lines` feature¶

It is returned as a list of dictionaries where each dictionary represents an invoice line.

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

Bank statements¶

The following table gives a list of all the fields that are extracted from bank statements.

Funkció neve	Specificities
`balance_start`	`content` egy lebegőpontos szám
`balance_end`	`content` egy lebegőpontos szám
`date`	`content` egy karakterlánc

`bank_statement_lines` feature¶

It is returned as a list of dictionaries where each dictionary represents a bank statement line.

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

Költség¶

A költségek kevésbé összetettek, mint a számlák. Az alábbi táblázat kimerítő listát ad az összes mezőről, amelyet ki tudunk nyerni egy költségjelentésből.

Funkció neve	Specificities
`leírás`	`content` egy karakterlánc
`country`	`content` egy karakterlánc
`date`	`content` egy karakterlánc
`total`	`content` egy lebegőpontos szám
`currency`	`content` egy karakterlánc

Pályázó¶

Ez a dokumentumtípus az önéletrajzok feldolgozására szolgál. Az alábbi táblázat kimerítő listát ad az összes mezőről, amelyet ki tudunk nyerni egy önéletrajzból.

Funkció neve	Specificities
`name`	`content` egy karakterlánc
`email`	`content` egy karakterlánc
`phone`	`content` egy karakterlánc
`mobile`	`content` egy karakterlánc

Integrációs tesztelés¶

Az integráció teszteléséhez használhatja az integration_token-t account_token-ként a /parse kérésben.

Ennek a tokennek a használata teszt üzemmódba helyezi Önt, és lehetővé teszi, hogy szimulálja a teljes folyamatot anélkül, hogy ténylegesen feldolgozna egy dokumentumot, és anélkül, hogy minden sikeres dokumentum feldolgozásért egy kreditet számláznának.

A teszt üzemmódban az egyetlen technikai különbség az, hogy a rendszer nem dolgozza fel az elküldött dokumentumot, és a /get_result válasza egy előre meghatározott.

A számlák teljes folyamatának python megvalósítása itt található.

API kinyerés¶

Áttekintés¶

Verzió¶

Folyamat¶

Feldolgozás¶

Útvonalak¶

Kérelem¶

Válasz¶

Eredmények lekérése¶

Útvonalak¶

Kérelem¶

Válasz¶

Gyakori mezők¶

feature_result¶

jelölt¶

Számlák¶

invoice_lines feature¶

Bank statements¶

bank_statement_lines feature¶

Költség¶

Pályázó¶

Integrációs tesztelés¶

`feature_result`¶

`invoice_lines` feature¶

`bank_statement_lines` feature¶