NAV

Úvod

Redque API poskytuje všechny dostupné funkcionality pro vytěžování dokumentů. Webová aplikace Alice rovněž využívá Redque API, veškerá data nahraná přes webovou aplikaci lze tak získat pomocí API a naopak vešekeré změny provedené přes API se ihned zobrazí ve webové aplikaci Alice.

Prostředí

Redque nabízí dvě nezávislá oddělená prostředí – Demo a Produkční prostředí. Obě prostředí mají stejné API i webové rozhraní (aplikace Alice), jediný rozdíl je v omezení počtu vytěžených dokumentů v Demo prostředí. Uživatelský účet pro Demo prostředí získáte zdarma zde.

- Demo prostředí Produkční prostředí
Webová aplikace (Alice) https://demo.redque.com/ https://web-v2.redque.com/
API https://demoapi.redque.com/ https://api.redque.com/
Identity Server https://demoidentity.redque.com/ https://identity.redque.com/

Autentizace

Redque API využívá OAuth 2.0 autentizační protokol. Pro volání API je třeba nejdříve získat autentizační JWT token (Access Token) od Identity Serveru. Získaný JWT token je pak posílat v HTTP hlavičce každého API požadavku:

Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...

Identity Serveru vydá JWT token na základě úspěšného ověření uživatele pomocí OAuth Password Grant:

# Vyžádání JWT tokenu pro uživatele jan.novak@gmail.com s heslem Redque123 (pozor na URL encoding u znaku @ a na to, že názvy parametrů příkazu curl jsou case-sensitive)
curl -X POST -d "grant_type=password&client_id=api_redque&username=jan.novak%40gmail.com&password=Redque123" "https://demoidentity.redque.com/connect/token"

# Odpověď serveru
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...","expires_in":3600,"token_type":"Bearer","scope":"v1.public"}

Vytěžení dokumentu

Redque API podporuje dva základní způsoby vytěžování dokumentu - Vložení dokumentu a Vytěžení bez uložení. V obou případech dojde automaticky k vytěžení dokumentu, avšak při Vložení dokumentu je dokument po skončení vytěžování nadále k dispozici a uživatel s ním pak může dále pracovat (ať již přes API, nebo ve webové aplikaci Alice). Při Vytěžení bez uložení je dokument pouze vytěžen, ale není nikde uložen.

Vložení dokumentu

Dokument se vkládá pomocí endpointu POST /v1/documents, dokument je dostupný jak přes API tak v aplikaci Alice.

# Vložení dokumentu Ukazkovy_dokument.pdf z lokálního počítače
curl -X POST -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." -F "File=@Ukazkovy_dokument.pdf" "https://demoapi.redque.com/v1/documents"

# Odpověď serveru
{"documentId":"0e9d4b614e1f4befa24c8649f63d8ede"}

Dokument lze načíst pomocí endpointu GET /v1/documents pomocí jeho ID, s dokumentem lze pak pomocí jeho ID pracovat i v ostatních endpointech API.

# Vyžádání dokumentu pomocí ID získaného v předchozím volání
curl -X GET -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/documents/0e9d4b614e1f4befa24c8649f63d8ede"

# Odpověď serveru
{
  "id": "0e9d4b614e1f4befa24c8649f63d8ede",  
  "fileName": "Ukazkovy_dokument.pdf",
  "state": "Extracted",  
  "documentClass": "czech_invoice",  
  "fields": {
    "invoice_number_sm": {
      "value": "FA987654",
      "wordIds": [
        1
      ]
    },
    "issued_by_name_sm": {
      "value": "Smyšlená společnost s.r.o.",
      "wordIds": [
        0
      ]
    },
    "issued_by_id_sm": {
      "value": "123456789",
      "wordIds": [
        16
      ]
    }
  ...
}

Vytěžení bez uložení

Dokument se odešle k vytěžení pomocí endpointu POST /v1/extract, kde je asynchronně zpracován. 

# Odeslání dokumentu Ukazkovy_dokument.pdf k vytěžování
curl -X POST -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." -F "File=@Ukazkovy_dokument.pdf" "https://demoapi.redque.com/v1/extract"

# Odpověď serveru
{
  "operationId": "f71b007b9ba740f69f52655a8d92a1cc"
}

Výsledek vytěžení se získá pomocí endpointu GET /v1/extract za pomoci ID operace, který vrátil předchozí endpoint. Endpoint GET /v1/extract vrátí HTTP kód 200 OK a spolu s ním vytěžená pole dokumentu, případně vrátí HTTP kód 202 Accepted, pokud vytěžení ještě neskončilo.

# Zíkání vytěženého dokumentu pomocí ID operace
curl -X GET -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/extract/f71b007b9ba740f69f52655a8d92a1cc"

# Odpověd serveru
HTTP/1.1 200 OK

{
  "operationId": "f71b007b9ba740f69f52655a8d92a1cc",
  "isSuccess": true,
  "extractionTime": "2023-08-29T16:08:40.672Z",  
  "fields": {
    "invoice_number_sm": {      
      "fieldValue": "FA987654"     
    },
    "issued_by_name_sm": {      
      "fieldValue": "Smyšlená společnost s.r.o.",      
    },
    ...
  }
}

# Odpověd serveru - vytěžování ještě neskončilo
HTTP/1.1 202 Accepted

Document is in state Extracting