Ú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.

Registrace a přístup do Redque API

Uživatelský účet získáte zdarma zde.

-	Adresa
Webová aplikace (Alice)	https://app.redque.com/
API	https://api.redque.com/
Identity Server	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://identity.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://identity.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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. Kompletní seznam výchozích polí dokumentu naleznete zde.

# Vyžádání dokumentu pomocí ID získaného v předchozím volání
curl -X GET -H "Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9..." "https://api.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://api.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. Výsledný formát lze změnit pomocí parametru exportFormat na json, xml nebo isdoc. Výchozí formát je json. Každý objekt v objektu fields obsahuje název pole, hodnotu pole a hodnotu pole ve formátu JSON.

Rozdil mezi fieldValue fieldValueJson
- fieldValue - hodnota pole je extrahovaný řetězec
- fieldValueJson - reprezentace hodnoty pole fieldValue dle typu pole. Pokud nelze hodnotu převést do odpovídajícího typu, je hodnota pole vytěžený řetězec.

Kompletní seznam výchozích polí dokumentu naleznete zde.

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

# Odpověd serveru
HTTP/1.1 200 OK

{
  "operationId": "7517a987-ba17-4625-ab96-9aa7ec5e876e",
  "extractionTime": "2024-07-15T11:22:00.708Z",
  "isRetrieved": true,
  "retrievedDate": "2024-07-15T11:22:31.326Z",
  "fields": {
    "is_deposit_invoice": {
      "fieldName": "is_deposit_invoice",
      "fieldValue": "False",
      "fieldValueJson": false
    },
    "invoice_number_sm": {
      "fieldName": "invoice_number_sm",
      "fieldValue": "F2440655",
      "fieldValueJson": "F2440655"
    },
    "currency": {
      "fieldName": "currency",
      "fieldValue": "CZK",
      "fieldValueJson": "CZK"
    },
    ...
  }
}

# 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.

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://api.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://api.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://api.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://api.redque.com/v1/documents/markAsExported'

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

# Odpověd serveru
HTTP/1.1 200 OK