microservices.cz

Autentizace

Všechny API požadavky vyžadují hlavičku Authorization s Bearer tokenem. API klíče vygenerujete v administraci.

Authorization: Bearer ak_live_...

Každý klíč má nastavené scopes (oprávnění), které určují, jaké služby může volat.

Prostředí

Parsování faktury

Extrahuje strukturovaná data z faktury pomocí AI. Podporuje PDF, JPEG, PNG, WEBP a ISDOC/ISDOCX do 20 MB.

Request

Příklad

curl -X POST https://api.microservices.cz/v1/invoice/parse \
  -H "Authorization: Bearer ak_live_..." \
  -F "file=@faktura.pdf"

Re-parse lepším modelem

curl -X POST https://api.microservices.cz/v1/invoice/parse \
  -H "Authorization: Bearer ak_live_..." \
  -F "file=@faktura.pdf" \
  -F "model=full"

Odpověď

{
  "ok": true,
  "data": {
    "supplier": {
      "name": "Dodavatel s.r.o.",
      "ico": "12345678",
      "dic": "CZ12345678",
      "address": "Ulice 123, 110 00 Praha"
    },
    "invoice_number": "FV-2026-0042",
    "variable_symbol": "20260042",
    "issue_date": "2026-03-15",
    "due_date": "2026-04-14",
    "currency": "CZK",
    "total_without_vat": 10000.00,
    "vat_amount": 2100.00,
    "total_with_vat": 12100.00,
    "items": [
      {
        "description": "Konzultační služby",
        "quantity": 10,
        "unit": "hod",
        "unit_price": 1000.00,
        "vat_rate": 21,
        "total": 12100.00
      }
    ],
    "confidence": 0.95,
    "totals_warning": null
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "credits_used": 2.0,
    "credits_remaining": 148.0,
    "processing_ms": 3420
  }
}

Pokud je export=true, odpověď obsahuje navíc:

"accounting_export": {
  "external_id": "123456",
  "document_number": "PF-2026-00042",
  "status": "success",
  "error": null
}

Hromadné parsování faktur

Parsuje více faktur najednou. Přijímá pole souborů nebo ZIP archiv. Max 10 souborů na request.

Request

Příklad

curl -X POST https://api.microservices.cz/v1/invoice/parse-batch \
  -H "Authorization: Bearer ak_live_..." \
  -F "files[]=@faktura1.pdf" \
  -F "files[]=@faktura2.pdf"

Odpověď

{
  "ok": true,
  "data": {
    "results": [
      {"filename": "faktura1.pdf", "ok": true, "data": {...}},
      {"filename": "faktura2.pdf", "ok": false, "error": "Extrahovaná data jsou neúplná..."}
    ],
    "total": 2,
    "success": 1,
    "failed": 1
  },
  "meta": {
    "request_id": "req_...",
    "credits_used": 2.0,
    "credits_remaining": 146.0,
    "processing_ms": 5820
  }
}

Export do účetního systému

Exportuje data faktury do účetního systému nakonfigurovaného na daném API klíči (iDoklad, ABRA Flexi). Přijímá JSON — buď výstup z parsování nebo vlastní data.

Podporované systémy

Request

JSON body s daty faktury (stejná struktura jako výstup z /v1/invoice/parse):

curl -X POST https://api.microservices.cz/v1/invoice/export \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "supplier": {"name": "Dodavatel s.r.o.", "ico": "12345678"},
    "invoice_number": "FV-2026-0042",
    "issue_date": "2026-03-15",
    "due_date": "2026-04-14",
    "items": [{"description": "Služby", "quantity": 1, "unit_price": 1000.00}],
    "total_without_vat": 1000.00,
    "total_with_vat": 1210.00
  }'

Odpověď

{
  "ok": true,
  "data": {
    "provider": "idoklad",   // nebo "abra"
    "external_id": "123456",
    "document_number": "PF-2026-00042",
    "status": "success"
  },
  "meta": {
    "request_id": "req_...",
    "credits_used": 0.5,
    "credits_remaining": 147.5,
    "processing_ms": 1240
  }
}

Stav kreditů

Vrátí aktuální stav kreditů pro přihlášeného tenanta.

Odpověď

{
  "ok": true,
  "data": {
    "balance": 150.0,
    "reserved": 4.0,
    "available": 146.0,
    "currency": "credits"
  }
}

Historie využití

Vrátí seznam posledních API volání pro přihlášeného tenanta.

Parametry

Odpověď

{
  "ok": true,
  "data": [
    {
      "request_id": "req_a1b2c3d4e5",
      "service": "invoice-parse",
      "credits_used": 2.0,
      "processing_ms": 3420,
      "status": "success",
      "error_code": null,
      "created_at": "2026-03-27T10:15:30+00:00"
    }
  ]
}

Chybové kódy

Všechny chyby mají jednotný formát:

{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "Popis chyby",
    "docs_url": "https://docs.microservices.cz/errors/error_code"
  },
  "meta": {
    "request_id": "req_..."
  }
}

Rate Limiting

API požadavky jsou omezeny na 10 požadavků za minutu (výchozí, konfigurovatelné per tenant). Při překročení vrátí HTTP 429 s hlavičkou Retry-After.

Hlavičky

JavaScript SDK

Oficiální JavaScript SDK pro jednoduchou integraci. Funguje v prohlížeči i Node.js.

Instalace

<script src="https://api.microservices.cz/sdk.js"></script>

Použití

const client = Microservices.init({
  apiKey: 'ak_live_...'
});

// Parsování faktury
const result = await client.parseInvoice(fileInput.files[0]);
console.log(result.data.invoice_number);
console.log(result.data.total_with_vat);

// Stav kreditů
const balance = await client.getCreditBalance();
console.log('Dostupné:', balance.data.available);

Zpracování chyb

try {
  const result = await client.parseInvoice(file);
} catch (err) {
  if (err instanceof Microservices.MicroservicesError) {
    console.error(err.code);   // 'insufficient_credits'
    console.error(err.status); // 402
  }
}

SDK automaticky retry při HTTP 429 (max 3 pokusy, exponential backoff).

PHP SDK

Standalone PHP klient — žádné závislosti kromě PHP 8.1+ s ext-curl.

Instalace

// Stáhněte soubor
curl -o MicroservicesClient.php https://api.microservices.cz/sdk/MicroservicesClient.php

// Nebo zkopírujte do projektu
require_once 'MicroservicesClient.php';

Použití

require_once 'MicroservicesClient.php';

$client = new MicroservicesClient('ak_live_...');

// Parsování faktury
$result = $client->parseInvoice('/path/to/faktura.pdf');
echo $result['invoice_number'];
echo $result['total_with_vat'];

// Parsování + export do účetního systému
$result = $client->parseAndExport('/path/to/faktura.pdf');
echo $result['accounting_export']['document_number'];

// Hromadné parsování (max 10 souborů)
$results = $client->parseInvoiceBatch([
    '/path/to/faktura1.pdf',
    '/path/to/faktura2.pdf',
]);

// Samostatný export (přijme výstup z parseInvoice nebo vlastní data)
$export = $client->exportInvoice($result);

// Stav kreditů
$balance = $client->getBalance();
echo 'Dostupné: ' . $balance['available'];

// Historie využití
$usage = $client->getUsage(['from' => '2026-03-01', 'limit' => 10]);

Zpracování chyb

try {
    $result = $client->parseInvoice('faktura.pdf');
} catch (MicroservicesException $e) {
    echo $e->errorCode;    // 'insufficient_credits'
    echo $e->getCode();    // 402 (HTTP status)
    echo $e->getMessage(); // 'Nedostatek kreditů'
}

SDK automaticky retry při HTTP 429 (max 3 pokusy, exponential backoff 1s/2s/4s).

Embeddable Widget

Widget umožňuje vložit parsování faktur přímo do vašeho webu. Stačí dvě řádky HTML — vše ostatní (UI, komunikace s API, stylování) řeší widget automaticky.

Základní použití

Vložte do stránky <div> s vaším API klíčem a načtěte skript:

<div id="mswidget-invoice"
     data-api-key="ak_live_...">
</div>
<script src="https://api.microservices.cz/widget/widget.js"></script>

Widget vykreslí formulář pro nahrání faktury s drag-and-drop, zobrazí parsovaná data a nabídne export do účetního systému (pokud je na API klíči nakonfigurován).

Konfigurace

Widget se konfiguruje přes data-* atributy na mount elementu:

Příklad s dark theme

<div id="mswidget-invoice"
     data-api-key="ak_live_..."
     data-theme="dark"
     data-accent-color="#10b981">
</div>
<script src="https://api.microservices.cz/widget/widget.js"></script>

JavaScript API

Widget nabízí event systém pro reakci na akce uživatele:

// Faktura úspěšně parsována
MicroservicesWidget.on('parsed', function(data) {
    console.log('Dodavatel:', data.supplier.name);
    console.log('Částka:', data.total_with_vat);
});

// Faktura odeslána do účetního systému
MicroservicesWidget.on('exported', function(data) {
    console.log('Číslo dokladu:', data.document_number);
});

// Chyba
MicroservicesWidget.on('error', function(message) {
    console.error('Widget error:', message);
});

Jak widget funguje

1. Upload — uživatel nahraje fakturu (drag-and-drop nebo výběr souboru)
2. Parsování — widget zavolá POST /v1/invoice/parse s vaším API klíčem
3. Review — zobrazí parsovaná data (dodavatel, položky, částky)
4. Export — pokud má API klíč nakonfigurovaný účetní systém, nabídne odeslání přes POST /v1/invoice/export

Více widgetů na stránce

Můžete vložit více widgetů s různými API klíči nebo službami. Každý mount point musí mít unikátní id začínající na mswidget-:

<div id="mswidget-invoice" data-api-key="ak_live_klic1"></div>
<div id="mswidget-invoice-2" data-api-key="ak_live_klic2" data-service="invoice"></div>
<script src="https://api.microservices.cz/widget/widget.js"></script>

Požadavky

• Moderní prohlížeč s podporou Shadow DOM (Chrome 53+, Firefox 63+, Safari 10+, Edge 79+)
• API klíč se scope invoice:parse (pro parsování) a volitelně invoice:export (pro export)
• CORS je povolený — widget funguje z jakékoliv domény

Verzování

Aktuální verze API je v1. Všechny endpointy mají prefix /v1/.

Každá odpověď obsahuje hlavičku X-API-Version: 1.

Při budoucích breaking changes bude představena nová verze (/v2/), přičemž /v1/ zůstane funkční po přechodné období s hlavičkou X-API-Deprecation: true.