Ú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 Server vydá JWT token na základě úspěšného ověření pomocí

OAuth Password Grant - pro uživatele
OAuth Client Credentials Grant - pro klientské aplikace

# 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":240,"token_type":"Bearer","scope":"v1.public"}

# Vyžádání JWT tokenu pro klientskou aplikaci id:AD1D9FA386F2BF94CBC574B704D1FB89DC... secret: 3364F6A9FF2CD3BE77...
curl -X POST -d "grant_type=client_credentials&client_id=AD1D9FA386F2BF94CBC574B704D1FB89DC&client_secret=3364F6A9FF2CD3BE77" "https://demoidentity.redque.com/connect/token"

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

Klientská aplikace

Klientská aplikace slouží k integraci Redque API do účetních systémů. Klientská aplikace může být jakákoliv aplikace, která umí komunikovat pomocí HTTP protokolu.

Autentizace klientské aplikace se provádí pomocí OAuth Client Credentials Grant.

Vytvoření klientské aplikace

Vytvoření klientské aplikace je akce, která slouží k vytvoření nového klienta pro integraci s Redque API. Tato akce umožňuje nastavit název klienta, jeho roli a povolení.

Pro vytvoření klientské aplikace je třeba provést HTTP POST požadavek na endpoint https://demoapi.redque.com/v1/configuration/client-application. V hlavičce požadavku je třeba uvést autorizační token (Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9) a typ obsahu (Content-Type: application/json). V těle požadavku je potřeba uvést název klienta, jeho roli a povolení ve formátu JSON.

# Vytvoření klientské aplikace
curl -X 'POST' \
  'https://demoapi.redque.com/v1/configuration/client-application' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9' \
  -H 'Content-Type: application/json' \
  -d '{
  "ClientName": "NazevKlienta",
  "Role": "Approver",
  "Enabled": true
}'

# Odpověď serveru
{
  "clientApplicationId": "8074D940D9E88447A2452B4A52290B4",
  "clientApplicationSecret": "4418bf620cd8534173220596a23bf9deb"
}

Získání klientské aplikace

Požadavek slouží k získání informací o konkrétní klientské aplikaci pomocí jejího identifikátoru. Provede se HTTP GET požadavek na endpoint https://demoapi.redque.com/v1/configuration/client-application/{client_application_id}. V hlavičce požadavku je třeba uvést autorizační token (Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9).

# Získání klientské aplikace pomocí ID
curl -X 'GET' \
  'https://demoapi.redque.com/v1/configuration/client-application/8074D940D9E88447A2452B4A52290B4' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

  # Odpověď serveru
  {
  "clientApplicationId": "97135B39CB65469FED01199744FB9FBC9EDE9A90E540C",
  "clientName": "NazevKlienta",
  "role": "Uploader",
  "enabled": true,
  "accountingUnitId": "9CB65469FED011",
  "additionalAcountingUnitIds": ["9CB65469FED011997", "D01199744FB9FBC9"]
}

Získání seznamu klientských aplikací

Požadavek slouží k získání seznamu všech klientských aplikací integrovaných s Redque API. Provede se HTTP GET požadavek na endpoint https://demoapi.redque.com/v1/configuration/client-application. V hlavičce požadavku je třeba uvést autorizační token (Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9).

# Získání seznamu všech klientských aplikací
curl -X 'GET' \
  'https://demoapi.redque.com/v1/configuration/client-application' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

# Odpověď serveru
{
  "list": [
    {
      "clientApplicationId": "135B39CB65469FED01199744FB9FBC9EDE9A90E540C",
      "clientName": "NazevKlienta",
      "role": "TenantAdmin",
      "enabled": true,
      "accountingUnitId": "9CB65469FED011",
      "additionalAcountingUnitIds": ["9CB65469FED011997", "D01199744FB9FBC9"]
    }]}

Aktualizace klientské aplikace

Požadavek slouží k aktualizaci informací o existující klientské aplikaci pomocí jejího identifikátoru. Provede se HTTP PATCH požadavek na endpoint https://demoapi.redque.com/v1/configuration/client-application/{client_application_id}. V hlavičce požadavku je třeba uvést autorizační token (Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9) a typ obsahu (Content-Type: application/json). V těle požadavku je potřeba uvést aktualizované informace o klientské aplikaci ve formátu JSON.

# Aktualizace klientské aplikace
curl -X 'PATCH' \
  'https://demoapi.redque.com/v1/configuration/client-application/8074D940D9E88447A2452B4A52290B4' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'
  -H 'Content-Type: application/json' \
  -d '{
    "ClientName": "TestClientAppllication",
    "Role": "Approver",
    "Enabled": true,
    "additionalAcountingUnitIds": [
      "JFUzUxMiIsInR5cCI6ImF0", "IsInR5cCI6ImF0JFUzUxMi"
    ],
    "clientApplicationId": "zUxMiIsInR5cCI6ImF0ng"
  }'

  # Odpověd serveru
  HTTP/1.1 200 OK

Deaktivace klientské aplikace

Požadavek, který slouží k deaktivaci konkrétní klientské aplikace pomocí jejího identifikátoru. Pro provedení této akce je potřeba provést HTTP DELETE požadavek na endpoint https://demoapi.redque.com/v1/configuration/client-application/{client_application_id}. V hlavičce požadavku je třeba uvést autorizační token (Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9). Po úspěšném provedení požadavku se klientská aplikace úspěšně deaktivuje.

# Deaktivace klientské aplikace
curl -X 'DELETE' \
  'https://demoapi.redque.com/v1/configuration/client-application/557B043540E14F3AB1AC9593ECB2D6C148074D940D9E88447A2452B4A52290B4' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

  # Odpověd serveru
  HTTP/1.1 200 OK

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

Integrace do účetních systémů s použitím exportu dokumentů

Nahraný dokument je potřeba označit jako určený k exportu. To lze provést pomocí endpointu POST /v1/documents/export nebo v aplikaci Alice.

Pro zjištění, zda existují dokumenty k exportu, můžeme volat endpoint POST /v1/documents/list/forExport pro získání seznamu všech dokumentů určených k exportu nebo endpoint POST /v1/documents/list/idsForExport pro získání seznamu ID dokumentů určených k exportu.

Zařazení dokumentu do exportu

Pro zařazení dokumentu do seznamu dokumentů určených k exportu můžete volat endpoint POST /v1/documents/export

# Zařazení dokumentu do exportu
curl -X POST -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/documents/export"

# Odpověd serveru
HTTP/1.1 200 OK

{
  "documentId": "6c60fe70642f0816445ad5"
}

# Odpověd serveru
HTTP/1.1 202 Accepted

Získání seznam kompletních dokumentů určených k exportu

Tato metoda vrací kompletní dokumenty, které jsou určeny k exportu.

# Zíkání seznamu všech dokumentů určených k exportu
curl -X POST -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/documents/list/forExport"

{}

# Odpověd serveru
HTTP/1.1 200 OK

{
  "list": [
    {
      "documentId": "6c60fe70642f0816445ad5",
      "externalDocumentId": null,
      "folderId": "3F9493019816BCB1B40573A1557663AD35",
      "pageCount": 1,
      "fileName": "objednavka-vzor.png",
      "documentClass": "czech_order",
      "accountingUnitId": "0ED1F081414F7A724FC37C05ADD6E7A53AA4888566A94B",
      "creationTime": "2023-10-10T14:19:10.003Z",
      "size": 138,
      "contentType": "image/png",
      "extractionTime": "2023-10-10T14:19:28.978Z",
      "isAttachment": false,
      "isValidated": true,
      "fields": {
        "order_number": {
          "fieldName": "order_number",
          "fieldValue": "0001",
          "fieldValueJson": "0001"
        },
        "supplier_name": {
          "fieldName": "supplier_name",
          "fieldValue": "Firma A s.r.o.",
          "fieldValueJson": "Firma A s.r.o."
        },
        ...
      }
    },
    ...
  ],
  "hasMore": false,
  "offset": 0
}

# Odpověd serveru
HTTP/1.1 202 Accepted


Returns documents

Získání seznamu ID dokumentů určených k exportu

Tato metoda vrací pouze ID dokumentů, které jsou určeny k exportu.

# Zíkání seznamu všech ID dokumentů určených k exportu
curl -X POST -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/documents/list/forExport"

{
}

# Odpověd serveru
HTTP/1.1 200 OK

{
  "list": [
    {
      "documentId": "6c60fe70642f0816445ad5",
      "externalDocumentId": null,
      "accountingUnitId": "86DDD21CF093C3A56CED74EE",
      "isAttachment": false,
      "isValidated": false,
      "folderId": "0E62B94D32B6A1D1F177890278263CE4CE9CBC21CF"
    },
    ...
  ],
  "hasMore": false,
  "offset": 0
}

# Odpověd serveru
HTTP/1.1 202 Accepted

Returns documents

Stažení dokumentu v požadovaném formátu

Dokumenty určené k exportu lze stáhnout v požadovaném formátu pomocí endpointu GET /v1/documents/{documentId}/file/export?exportFormat=<FormatCilovehoDokumentu>.

# Zíkání seznamu všech ID dokumentů určených k exportu
curl -X GET -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/documents/6c60fe70642f0816445ad5/file/export?exportFormat=Xml'

# Odpověd serveru
HTTP/1.1 200 OK

Označení dokumentu jako úspěšně exportovaného

Po úspěšném zpracování dokumentu(ů) je třeba dokument(y) označit jako exportovaný(é) pomocí endpointu PATCH /v1/documents/markAsExported a tím je odstranit z seznamu dokumentů určených k exportu.

# Označení dokumentu(ů) po úspěšném exportu
curl -X PATCH -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://demoapi.redque.com/v1/documents/markAsExported'

[
  {
    "documentId": "6c60fe70642f0816445ad5",
    "exportType": "TypSystemuKamBylDokumentImportovan"
  }
]

# Odpověd serveru
HTTP/1.1 200 OK

Vlastní číselníky

Slouží k definování a správě seznamu hodnot, které mají specifický význam nebo použití v aplikaci. Číselníky umožňují centralizovanou správu a aktualizaci hodnot, což usnadňuje údržbu a zajišťuje konzistenci dat v systému. Vytvoření vlastního číselníku je proces, který umožňuje definovat a konfigurovat nový seznam hodnot s příslušnými klíči, hodnotami a tagy. Pomocí HTTP POST požadavku a specifikace názvu, mapování pro export a seznamu hodnot je možné vytvořit nový číselník. Každá hodnota v číselníku je definována klíčem, hodnotou a tagem, který může obsahovat další atributy nebo informace.

Vytvoření vlastního číselníku

Tato metoda slouží k vytvoření vlastního číselníku pomocí HTTP POST požadavku. Číselník obsahuje název, mapování pro export a seznam hodnot s jejich klíčem, hodnotou a tagem.

# Vytvoření vlastního číselníku
curl -X 'POST' \
  'https://demoapi.redque.com/v1/enums' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9 \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "TestEnum",
  "exportMapping": "None",
  "values": [
    {
      "key": "TestValue",
      "value": "string",
      "tag": {
        "objectAttribute": {},
        "arrayAttribute": [],
        "stringAttribute": "value"
      }
    }
  ]
}'
# Odpověd serveru
6_c628775462_f6_d2_c5_b7_test_enum

Získání vlastního číselníku podle ID

Příklad získání vlastního číselníku pomocí HTTP GET požadavku.

# Získání vlastního číselníku podle ID
curl -X 'GET' \
  'https://demoapi.redque.com/v1/enums/bbf50_b1_a560_d16_f4_bb866_cfdba35_a540_test_enum' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

# Odpověd serveru
{
  "name": "TestEnum",
  "exportMapping": "None",
  "values": [
    {
      "key": "TestValue",
      "value": "string",
      "tag": {
        "objectAttribute": {},
        "arrayAttribute": [],
        "stringAttribute": "value"
      }
    }
  ]
}

Získání seznamu všech číselníků

Příklad získání seznamu všech číselníků pomocí HTTP GET požadavku.

# Zíkání seznamu všech číselníků
curl -X 'GET' \
  'https://demoapi.redque.com/v1/enums' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

# Odpověd serveru
[
  {
    "id": "string",
    "name": "TestEnum",
    "exportMapping": "None",
    "values": [
      {
        "key": "ez2R1Zf3ye_test_enum",
        "value": "TestValue",
        "tag": {
          "objectAttribute": {},
          "arrayAttribute": [],
          "stringAttribute": "value"
        },
        "hidden": false
      }
    ]
  },
  {
    "id": "string",
    "name": "TestEnum2",
    "exportMapping": "None",
    "values": [
      {
        "key": "eez2R1Zf3ye_test_enum2",
        "value": "TestValue2",
        "tag": {
          "objectAttribute": {},
          "arrayAttribute": [],
          "stringAttribute": "value2"
        },
        "hidden": false
      }
    ]
  }
]

Aktualizace vlastního číselníku

Příklad aktualizace vlastního číselníku podle ID.

# Aktualizace vlastního číselníku
curl -X 'PUT' \
  'https://demoapi.redque.com/v1/enums/c099_bbf50_b1_a560_d16_f4_bb866_cfdba35_a540_test_enum' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

  # Odpověd serveru
HTTP/1.1 200 OK

Editace vlastního číselníku

Příklad editace vlastního číselníku podle ID.

# Editace vlastního číselníku
curl -X 'PATCH' \
  'https://demoapi.redque.com/v1/enums/c5_b7_fa7_c2_ada3_c099_bbf50_b1_a560_d16_f4_bb866_cfdba35_a540_test_enum' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

# Odpověd serveru
HTTP/1.1 200 OK

Smazání vlastního číselníku

Příklad smazání vlastního číselníku podle ID.

# Smazání vlastního číselníku
curl -X 'DELETE' \
  'https://demoapi.redque.com/v1/enums/ada3_c099_bbf50_b1_a560_d16_f4_bb866_cfdba35_a540_test_enum' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9'

# Odpověd serveru
HTTP/1.1 200 OK