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škeré změny provedené přes API se ihned zobrazí ve webové aplikaci Alice.

Tato dokumentace je návodem pro implementátory integrace a je rozdělena do tří příruček:

  1. Začínáme - registrace, vytvoření klientské aplikace a autentizace.
  2. Vytěžení dokumentů - nahrání dokumentu, sledování průběhu vytěžení a získání vytěžených dat.
  3. Synchronizace do účetního systému - automatický export vytěžených dokumentů do účetního (či jiného externího) systému.

Přehled integračního procesu

Nahrání dokumentu Vytěžení Zařazení do fronty k exportu Stažení dokumentu v požadovaném formátu Označení exportovaného dokumentu
POST /v1/documents automaticky POST /v1/documents/export GET /v1/documents/{documentId}/file/export?exportFormat=<FormátExportu> PATCH /v1/documents/markAsExported nebo PATCH /v1/documents/markAsExportFailure

Začínáme

Tato příručka vás provede od registrace až k prvnímu autentizovanému volání Redque API. Na jejím konci budete mít vytvořenou klientskou aplikaci a přístupový token, se kterým můžete začít vytěžovat dokumenty.

Registrace

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

Prostředí a adresy

- Adresa
Webová aplikace (Alice) https://app.redque.com/
API https://api.redque.com/
Identity Server https://identity.redque.com/

Autentizace

Redque API využívá autentizační protokol OAuth 2.0. Pro volání API je třeba nejdříve získat autentizační JWT token (Access Token) od Identity Serveru. Získaný JWT token se pak posílá 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í

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

Pro trvalou integraci doporučujeme používat klientskou aplikaci a Client Credentials Grant. Uživatelský token (Password Grant) potřebujete jednorázově pouze k vytvoření klientské aplikace v následujících krocích.

Krok 1: Získání uživatelského tokenu (Password Grant)

Uživatelský token získáte odesláním přihlašovacích údajů na Identity Server:

# 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"}

Získaný access_token použijte v následujícím kroku k vytvoření klientské aplikace.

Krok 2: Vytvoření klientské aplikace

Klientská aplikace představuje vaši integraci - může to být jakákoliv aplikace, která umí komunikovat pomocí HTTP protokolu. Vytvoříte ji pomocí endpointu POST /v1/client-applications/client-application (autorizovaného uživatelským tokenem z kroku 1):

# Vytvoření klientské aplikace
curl -X POST \
  'https://api.redque.com/v1/client-applications/client-application' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientName": "MojeIntegrace",
    "role": "Approver",
    "enabled": true,
    "accountingUnitId": "a1b2c3d4e5f6",
    "additionalAccountingUnitIds": ["g7h8i9j0k1l2", "m3n4o5p6q7r8"]
  }'

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

Parametry požadavku

Parametr Typ Popis
clientName string Povinný. Název klientské aplikace.
role string Povinný. Role určující oprávnění aplikace: Uploader, Processor, Approver, TenantAdmin, AccountingUnitProcessor nebo AccountingUnitApprover.
enabled boolean Povolení/zakázání klientské aplikace.
accountingUnitId string ID hlavní účetní jednotky, se kterou aplikace pracuje.
additionalAccountingUnitIds pole string ID dalších účetních jednotek.

Krok 3: Získání tokenu klientské aplikace (Client Credentials Grant)

S přístupovými údaji klientské aplikace získáte token pro volání API:

# 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"}

Tímto tokenem autorizujete všechna další volání API. Pokračujte příručkou Vytěžení dokumentů.

Práce s tokenem

Doporučení pro implementaci:

Správa klientských aplikací

Seznam existujících klientských aplikací získáte pomocí endpointu POST /v1/client-applications/client-application/list:

# Získání seznamu všech klientských aplikací
curl -X POST \
  'https://api.redque.com/v1/client-applications/client-application/list' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{}'

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

Klientskou aplikaci, kterou již nepoužíváte, deaktivujte pomocí endpointu DELETE /v1/client-applications/client-application/{clientApplicationId}:

# Deaktivace klientské aplikace
curl -X DELETE \
  'https://api.redque.com/v1/client-applications/client-application/8074D940D9E88447A2452B4A52290B4' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...'

# Odpověď serveru
HTTP/1.1 200 OK

Vytěžení dokumentů

Redque API podporuje dva základní způsoby vytěžení dokumentu:

Pro integraci s účetním systémem (viz příručka Synchronizace do účetního systému) použijte vytěžení s uložením. Pokud potřebujete pouze získat vytěžená data do vlastní aplikace, zvolte vytěžení bez uložení.

Vytěžení s uložením dokumentu

Krok 1: Nahrání dokumentu

Dokument nahrajete pomocí endpointu POST /v1/documents. Po nahrání se automaticky spustí proces vytěžení.

# Nahrání dokumentu
curl -X POST \
  'https://api.redque.com/v1/documents' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -F 'File=@Faktura_2025.pdf'

# Odpověď serveru
HTTP/1.1 200 OK

{
  "documentId": "0e9d4b614e1f4befa24c8649f63d8ede"
}

Parametry požadavku (multipart/form-data)

Parametr Typ Popis
File binary Povinný. Binární soubor dokumentu.
DocumentId string Vlastní (externí) ID dokumentu.
DocumentClass string Typ dokumentu.
AccountingUnitId string ID účetní jednotky, ke které dokument patří.

Varianty nahrání

Kromě základního nahrání souboru přes multipart/form-data můžete použít i tyto varianty:

Nahrání z JSON (Base64) - endpoint POST /v1/documents/fromJson pro klienty, kteří nemohou posílat multipart/form-data. Obsah souboru se předává zakódovaný v Base64.

# Vložení dokumentu z JSON (Base64)
curl -X POST \
  'https://api.redque.com/v1/documents/fromJson' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{"fileName": "Faktura_2025.pdf", "fileContent": "JVBERi0xLjQK..."}'

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

Nahrání bez vytěžení - endpoint POST /v1/documents/uploadOnly vloží dokument, aniž by spustil vytěžení. Slouží k importu dokumentu, jehož data už máte (např. z jiného systému) - proto v těle požadavku předáváte kromě obsahu souboru i kompletní stav dokumentu včetně polí:

# Vložení dokumentu bez vytěžení (import již vytěženého dokumentu)
curl -X POST \
  'https://api.redque.com/v1/documents/uploadOnly' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileName": "Faktura_2025.pdf",
    "fileContent": "JVBERi0xLjQK...",
    "state": "Extracted",
    "documentClass": "czech_invoice",
    "fields": {},
    "items": [],
    "source": "Api",
    "creationTime": "2025-01-15T10:00:00.000Z",
    "ownerId": "97135B39CB65469FED011",
    "pages": [],
    "pageCount": 1
  }'

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

Nahrání po stránkách - endpoint POST /v1/documents/uploadPage vkládá dokument po jednotlivých stránkách (PNG/JPEG). Vytěžení se spustí po nahrání poslední stránky (IsLastPage=true).

# Vložení stránky dokumentu
curl -X POST \
  'https://api.redque.com/v1/documents/uploadPage' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -F 'File=@stranka1.png' \
  -F 'PageIndex=0' \
  -F 'DocumentId=0e9d4b614e1f4befa24c8649f63d8ede' \
  -F 'IsLastPage=false'

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

Parametry požadavku uploadPage (multipart/form-data)

Parametr Typ Popis
File binary Povinný. Soubor stránky ve formátu PNG/JPEG.
PageIndex integer Povinný. Index stránky.
DocumentId string Povinný. ID dokumentu.
IsLastPage boolean Povinný. Příznak poslední stránky - true spustí vytěžení.
DocumentClass string Typ dokumentu.
AccountingUnitId string ID účetní jednotky.
ExtractItems boolean Vytěžit položky dokumentu.

Krok 2: Čekání na dokončení vytěžení

Vytěžení probíhá automaticky po nahrání dokumentu. Systém Redque analyzuje dokument a extrahuje z něj relevantní data (číslo faktury, dodavatel, částky atd.). O dokončení vytěžení se dozvíte dvěma způsoby - webhookem, nebo opakovaným dotazováním (pollingem).

Webhook (doporučeno)

Doporučujeme vytvořit webhook s událostí ExtractionFinished - Redque pak po dokončení vytěžení sám zavolá vaši URL a vaše integrace se nemusí opakovaně dotazovat na stav dokumentu. Webhook vytvoříte pomocí endpointu POST /v1/tenant/webHooks:

# Vytvoření webhooku volaného po dokončení vytěžení
curl -X POST \
  'https://api.redque.com/v1/tenant/webHooks' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Notifikace o dokončení vytěžení",
    "url": "https://example.com/webhook",
    "eventType": "ExtractionFinished",
    "exportFormat": "Json",
    "isActive": true,
    "clientApplicationId": "8074D940D9E88447A2452B4A52290B4"
  }'

# Odpověď serveru
{
  "id": "wh123",
  "url": "https://example.com/webhook"
}

Parametry požadavku

Parametr Typ Popis
name string Povinný. Název webhooku.
url string Povinný. Adresa, kterou Redque při události zavolá.
eventType string Povinný. Typ události - pro notifikaci o dokončení vytěžení použijte ExtractionFinished.
exportFormat string Formát dat dokumentu předávaných webhookem (např. Json).
isActive boolean Povinný. Zapnutí/vypnutí webhooku.
clientApplicationId string ID klientské aplikace, ke které se webhook vztahuje.

Webhook aktualizujete pomocí PUT /v1/tenant/webHooks, smažete pomocí DELETE /v1/tenant/webHooks?webHookId={id} a jejich seznam získáte pomocí POST /v1/tenant/webHooks/list.

Polling

Alternativně můžete stav dokumentu opakovaně kontrolovat pomocí endpointu GET /v1/documents/{documentId} - sledujte pole state, dokud nenabude hodnoty Extracted (případně Validated):

# Kontrola stavu dokumentu
curl -X GET \
  'https://api.redque.com/v1/documents/0e9d4b614e1f4befa24c8649f63d8ede' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...'

# Odpověď serveru - dokument vytěžen
HTTP/1.1 200 OK

{
  "id": "0e9d4b614e1f4befa24c8649f63d8ede",
  "fileName": "Faktura_2025.pdf",
  "externalDocumentId": null,
  "state": "Extracted",
  "documentClass": "czech_invoice",
  "approvalState": "None",
  "source": "Api",
  "accountingUnitId": "a1b2c3d4e5f6",
  "pageCount": 1,
  "creationTime": "2025-01-15T10:00:00.000Z",
  "extractionTime": "2025-01-15T10:00:15.000Z",
  "contentType": "application/pdf",
  "isExtractedByFormat": false,
  "canBeExported": true,
  "canBeApproved": true,
  "canBeSentToApproval": true,
  "canBeShownInApproval": true,
  "fields": {
    "invoice_number_sm": {
      "value": "FA2025001",
      "wordIds": [1]
    },
    "issued_by_name_sm": {
      "value": "Dodavatel s.r.o.",
      "wordIds": [0]
    },
    "total_amount": {
      "value": "12500.00",
      "wordIds": [15]
    }
  },
  "items": [],
  "pages": [],
  "fieldsHistory": [],
  "validationErrors": [],
  "documentExportHistory": [],
  "attachments": []
}

Doporučený postup: první kontrolu proveďte přibližně 5 sekund po nahrání, dále se dotazujte každých 5-10 sekund. Pokud dokument není vytěžen ani po několika minutách, zkontrolujte, zda jeho stav neskončil hodnotou Failed nebo UnsupportedType.

Stavy dokumentu

Stav Popis
Uploading Probíhá nahrávání dokumentu (např. po stránkách).
Uploaded Dokument byl nahrán a čeká na zpracování.
PreProcessed Dokument byl předzpracován a čeká na vytěžení.
Extracting Probíhá vytěžení dokumentu.
Extracted Vytěžení dokončeno.
Validated Dokument byl validován (ručně nebo automaticky).
ReadyForExport Dokument je zařazen ve frontě k exportu.
Exported Dokument byl exportován do externího systému.
Returned Dokument byl vrácen vystaviteli.
Paused Zpracování dokumentu je pozastaveno.
Archived Dokument byl archivován.
Failed Při zpracování dokumentu došlo k chybě.
UnsupportedType Nepodporovaný typ souboru.
NoLicense Dokument nebyl vytěžen z důvodu chybějící licence.

Stavy DocumentWorkflowInProgress a DocumentWorkflowRejected souvisejí se schvalovacím workflow ve webové aplikaci Alice.

Krok 3: Načtení vytěžených dat

Vytěžená data najdete v poli fields odpovědi endpointu GET /v1/documents/{documentId} (viz krok 2). Kompletní seznam výchozích polí dokumentu naleznete zde.

Pokud chcete data ve strojově čitelném exportním formátu, použijte endpoint GET /v1/documents/{documentId}/file/export:

# Stažení vytěžených dat ve formátu JSON
curl -X GET \
  'https://api.redque.com/v1/documents/0e9d4b614e1f4befa24c8649f63d8ede/file/export?exportFormat=Json' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...'

Nahraný dokument je zároveň dostupný ve webové aplikaci Alice:

Pokud chcete dokument předat účetnímu systému, pokračujte příručkou Synchronizace do účetního systému.

Vytěžení bez uložení

Krok 1: Odeslání dokumentu k vytěžení

Dokument odešlete k vytěžení pomocí endpointu POST /v1/extract, kde je asynchronně zpracován. Dokument není v systému uložen - slouží pouze pro jednorázové vytěžení.

# Odeslání dokumentu Ukazkovy_dokument.pdf k vytěžení
curl -X POST \
  'https://api.redque.com/v1/extract' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -F 'file=@Ukazkovy_dokument.pdf'

# Odpověď serveru
HTTP/1.1 200 OK

{
  "operationId": "f71b007b9ba740f69f52655a8d92a1cc"
}

Parametry požadavku (query string)

Parametr Typ Popis
externalDocumentId string Vlastní ID dokumentu.
tag string Identifikátor pro statistiky vytěžování.
extractFirstPageIndicesOnly boolean Vrátí pouze indexy stránek, kde začínají jednotlivé dokumenty - viz Detekce více dokumentů v souboru.
extractItems boolean Vytěžení položek dokumentu. Je nadřazeno nastavení tenanta.

Tělo požadavku používá multipart/form-data s polem file obsahujícím binární obsah dokumentu. Vrácené operationId použijte v kroku 2 k vyzvednutí výsledku.

Varianta: odeslání v JSON (Base64)

Dokument můžete odeslat k vytěžení také jako JSON požadavek s obsahem souboru zakódovaným v Base64 - endpoint POST /v1/extract/fromJson:

# Odeslání dokumentu k vytěžení pomocí JSON
curl -X POST \
  'https://api.redque.com/v1/extract/fromJson' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileName": "Faktura.pdf",
    "fileContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC...",
    "tag": "MojeIntegrace",
    "extractItems": true
  }'

# Odpověď serveru
HTTP/1.1 200 OK

{
  "operationId": "f71b007b9ba740f69f52655a8d92a1cc"
}

Tělo požadavku (JSON)

Parametr Typ Popis
fileName string Povinný. Název souboru s příponou.
fileContent string Povinný. Obsah souboru zakódovaný v Base64.
tag string Identifikátor pro statistiky vytěžování.
extractFirstPageIndicesOnly boolean Vrátí pouze indexy stránek, kde začínají jednotlivé dokumenty.
extractItems boolean Vytěžení položek dokumentu. Je nadřazeno nastavení tenanta.

Krok 2: Vyzvednutí výsledku

Výsledek vytěžení získáte pomocí endpointu GET /v1/extract/{operationId}. Opakujte dotaz, dokud server vrací 202 Accepted (vytěžení stále probíhá) - odpověď 200 OK obsahuje vytěžená data:

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

# Odpověď serveru - vytěžení dokončeno
HTTP/1.1 200 OK

{
  "operationId": "7517a987-ba17-4625-ab96-9aa7ec5e876e",
  "documentClass": "czech_invoice",
  "extractionTime": "2024-07-15T11:22:00.708Z",
  "isRetrieved": true,
  "retrievedDate": "2024-07-15T11:22:31.326Z",
  "isSuccess": true,
  "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"
    },
    "total_amount": {
      "fieldName": "total_amount",
      "fieldValue": "12500.00",
      "fieldValueJson": 12500.00
    },
    "issued_by_name_sm": {
      "fieldName": "issued_by_name_sm",
      "fieldValue": "Dodavatel s.r.o.",
      "fieldValueJson": "Dodavatel s.r.o."
    }
  },
  "items": []
}

# Odpověď serveru - vytěžení ještě neskončilo
HTTP/1.1 202 Accepted

Document is in state Extracting

Parametry požadavku

Parametr Umístění Typ Popis
operationId path string Povinný. ID operace vrácené při odeslání dokumentu k vytěžení.
exportFormat query string Formát výsledku: Xml, ISDOC nebo Json. Výchozí je Json.

HTTP odpovědi

Kód Popis
200 Vytěžení dokončeno. Vrací vytěžená data.
202 Redque stále zpracovává dokument - opakujte dotaz.

Doporučený postup: první dotaz proveďte přibližně 5 sekund po odeslání dokumentu, dále se dotazujte každých 5-10 sekund.

Detekce více dokumentů v souboru

Pokud při odeslání dokumentu nastavíte parametr extractFirstPageIndicesOnly=true, Redque místo vytěžení dat vrátí pole firstPageIndicies s indexy stránek, na kterých začínají jednotlivé dokumenty. Hodí se pro rozdělení velkého PDF obsahujícího více dokumentů:

# Odpověď serveru při extractFirstPageIndicesOnly=true
HTTP/1.1 200 OK

{
  "operationId": "43464f45-665c-4b9b-9ba1-bfb1b0d67407",
  "extractionTime": "0001-01-01T00:00:00",
  "isRetrieved": false,
  "retrievedDate": "0001-01-01T00:00:00",
  "fields": {},
  "items": [],
  "isSuccess": true,
  "firstPageIndicies": [1, 2, 3]
}

Práce s vytěženými poli: fieldValue vs. fieldValueJson

Každé vytěžené pole obsahuje hodnotu ve dvou podobách:

Synchronizace do účetního systému

Vytěžené dokumenty lze z Redque získat ve formátech určených přímo pro účetní systémy, nebo v obecných formátech (JSON, XML) pro vlastní zpracování. Tato příručka popisuje kompletní synchronizační cyklus - od zařazení dokumentu do fronty k exportu až po potvrzení úspěšného zaúčtování.

Předpokladem je dokument nahraný a vytěžený podle příručky Vytěžení dokumentů.

Přehled synchronizačního cyklu

Krok Endpoint
1. Zařazení dokumentu do fronty k exportu POST /v1/documents/export
2. Zjištění dokumentů čekajících na export POST /v1/documents/list/forExport nebo POST /v1/documents/list/idsForExport
3. Stažení dokumentu v exportním formátu GET /v1/documents/{documentId}/file/export?exportFormat=…
4. Potvrzení výsledku exportu PATCH /v1/documents/markAsExported nebo PATCH /v1/documents/markAsExportFailure

Krok 1: Zařazení dokumentu do fronty k exportu

Po vytěžení (a případné validaci) dokument zařadíte do fronty k exportu pomocí endpointu POST /v1/documents/export:

# Zařazení dokumentu do fronty k exportu
curl -X POST \
  'https://api.redque.com/v1/documents/export' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "0e9d4b614e1f4befa24c8649f63d8ede"
  }'

# Odpověď serveru
HTTP/1.1 200 OK

Hromadné zařazení více dokumentů

Pro zařazení více dokumentů najednou použijte endpoint POST /v1/documents/export/list:

# Hromadné zařazení dokumentů do fronty k exportu
curl -X POST \
  'https://api.redque.com/v1/documents/export/list' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '["0e9d4b614e1f4befa24c8649f63d8ede", "1a2b3c4d5e6f7g8h9i0j"]'

# Odpověď serveru
HTTP/1.1 200 OK

Krok 2: Zjištění dokumentů čekajících na export

Seznam dokumentů čekajících ve frontě k exportu, včetně kompletních vytěžených dat, získáte pomocí endpointu POST /v1/documents/list/forExport:

# Získání seznamu dokumentů k exportu
curl -X POST \
  'https://api.redque.com/v1/documents/list/forExport' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "control": {
      "skip": 0,
      "take": 50
    }
  }'

# Odpověď serveru
HTTP/1.1 200 OK

{
  "list": [
    {
      "documentId": "0e9d4b614e1f4befa24c8649f63d8ede",
      "externalDocumentId": null,
      "pageCount": 1,
      "fileName": "Faktura_2025.pdf",
      "documentClass": "czech_invoice",
      "accountingUnitId": "a1b2c3d4e5f6",
      "accountingUnitExternalId": null,
      "creationTime": "2025-01-15T10:00:00.000Z",
      "size": 125,
      "contentType": "application/pdf",
      "extractionTime": "2025-01-15T10:00:15.000Z",
      "isValidated": true,
      "fields": {
        "invoice_number_sm": {
          "fieldName": "invoice_number_sm",
          "fieldValue": "FA2025001",
          "fieldValueJson": "FA2025001"
        },
        "total_amount": {
          "fieldName": "total_amount",
          "fieldValue": "12500.00",
          "fieldValueJson": 12500.00
        }
      },
      "items": [],
      "note": null
    }
  ],
  "hasMore": false,
  "offset": 0
}

Parametry těla požadavku

Parametr Typ Popis
control.skip integer Počet přeskočených záznamů (stránkování).
control.take integer Maximální počet vrácených záznamů.
accountingUnitId string Omezení na konkrétní účetní jednotku.
accountingUnitExternalId string Omezení na účetní jednotku podle externího ID.

Pokud odpověď obsahuje "hasMore": true, načtěte další stránku zvýšením hodnoty control.skip o počet již načtených záznamů.

Pouze ID dokumentů

Pokud potřebujete jen zjistit, zda ve frontě čekají dokumenty, použijte úspornější endpoint POST /v1/documents/list/idsForExport:

# Získání ID dokumentů k exportu
curl -X POST \
  'https://api.redque.com/v1/documents/list/idsForExport' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{}'

# Odpověď serveru
HTTP/1.1 200 OK

{
  "list": [
    {
      "documentId": "0e9d4b614e1f4befa24c8649f63d8ede",
      "externalDocumentId": null,
      "accountingUnitId": "a1b2c3d4e5f6",
      "accountingUnitExternalId": null,
      "isValidated": true
    }
  ],
  "hasMore": false,
  "offset": 0
}

Doporučení: pro pravidelnou kontrolu fronty používejte idsForExport (levný dotaz) a kompletní data si vyžádejte přes forExport, případně stáhněte v exportním formátu, až když fronta obsahuje dokumenty.

Krok 3: Stažení dokumentu v exportním formátu

Dokument z fronty stáhnete v požadovaném formátu pomocí endpointu GET /v1/documents/{documentId}/file/export:

# Stažení dokumentu ve formátu JSON
curl -X GET \
  'https://api.redque.com/v1/documents/0e9d4b614e1f4befa24c8649f63d8ede/file/export?exportFormat=Json' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...'

# Stažení dokumentu ve formátu XML
curl -X GET \
  'https://api.redque.com/v1/documents/0e9d4b614e1f4befa24c8649f63d8ede/file/export?exportFormat=Xml' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...'

# Stažení dokumentu ve formátu ISDOC
curl -X GET \
  'https://api.redque.com/v1/documents/0e9d4b614e1f4befa24c8649f63d8ede/file/export?exportFormat=Isdoc' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...'

Dostupné formáty exportu

Formát Popis
Json JSON formát s vytěženými daty.
Xml XML formát s vytěženými daty.
Isdoc Standardizovaný formát pro elektronické faktury v ČR.

Krok 4: Potvrzení výsledku exportu

Po úspěšném zpracování dokumentu v účetním systému dokument označte jako exportovaný pomocí endpointu PATCH /v1/documents/markAsExported - tím jej odeberete z fronty k exportu:

# Označení dokumentu jako exportovaného
curl -X PATCH \
  'https://api.redque.com/v1/documents/markAsExported' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "documentId": "0e9d4b614e1f4befa24c8649f63d8ede",
      "accoutingProviderDocumentNumber": "FA2025001",
      "exportType": "Other",
      "exportedByApplicationName": "MojeIntegrace"
    }
  ]'

# Odpověď serveru
HTTP/1.1 200 OK

Parametry označení

Parametr Typ Popis
documentId string Povinný. ID dokumentu.
accoutingProviderDocumentNumber string Číslo dokladu v cílovém systému.
exportType string Typ cílového systému z číselníku DocumentExportType - např. iDoklad, MoneyS3, AbraFlexi, Fakturoid, Dynamics; pro nezalistovaný systém použijte Other.
exportedByApplicationName string Název aplikace, která export provedla.

Označení neúspěšného exportu

Pokud zpracování v účetním systému selže, označte dokument pomocí endpointu PATCH /v1/documents/markAsExportFailure. Důvod selhání se zobrazí u dokumentu ve webové aplikaci Alice:

# Označení neúspěšného exportu
curl -X PATCH \
  'https://api.redque.com/v1/documents/markAsExportFailure' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6ImF0K2p3dCJ9...' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "documentId": "0e9d4b614e1f4befa24c8649f63d8ede",
      "failureReason": "Chyba připojení k účetnímu systému"
    }
  ]'

# Odpověď serveru
HTTP/1.1 200 OK
Parametr Typ Popis
documentId string Povinný. ID dokumentu.
failureReason string Povinný. Důvod selhání exportu.

Doporučení pro implementaci

Chyby

Redque API používá následující chybové kódy:

Kód chyby Popis
400 Bad Request -- Nevalidní požadavek. Zkontrolujte požadavek.
401 Unauthorized -- Volání není autorizováno.
403 Forbidden -- Neoprávněný přístup ke zdroji.
404 Not Found -- Nenalezeno.
405 Method Not Allowed -- Nepovolená metoda.
500 Internal Server Error -- Problém je na naší straně.
503 Service Unavailable -- Služba není dostupná. Zkuste to později.