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

Generátor oslovení

Vrátí 5. pádový tvar (vokativ) českých jmen a příjmení. Vhodné pro automatická oslovení v e-mailech a obchodní komunikaci. Cena: 0,025 kreditu za volání.

Request (JSON)

Příklad

curl -X POST https://api.microservices.cz/v1/osloveni/generate \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Petr","last_name":"Novák","format":"polite"}'

Odpověď

{
  "ok": true,
  "data": {
    "vocative": "Petře Nováku",
    "first_name_vocative": "Petře",
    "last_name_vocative": "Nováku",
    "gender_detected": "m",
    "confidence": "high",
    "polite": "pane Nováku"
  },
  "meta": { "request_id": "req_..." }
}

Alternativní tvary

Některá jména mají v 5. pádu dva gramaticky správné tvary (např. Marcel → „Marceli" i „Marcele", Petr jako příjmení → „Petře" i „Petre"). V poli vocative vždy vrátíme jeden hlavní (primární) tvar, alternativy jsou v vocative_alternatives.

// Request
{"first_name":"Marcel","last_name":"Vortel","format":"first"}

// Response
{
  "ok": true,
  "data": {
    "vocative": "Marceli",
    "first_name_vocative": "Marceli",
    "last_name_vocative": "Vorteli",
    "gender_detected": "m",
    "confidence": "high",
    "polite": "pane Vorteli",
    "vocative_alternatives": {
      "first_name": ["Marcele"],
      "last_name":  ["Vortele"]
    }
  }
}

Pole vocative_alternatives je v odpovědi jen tehdy, když alespoň jedno jméno má víc tvarů. Pokud klient toto pole ignoruje, dostane prostě jeden běžný tvar — žádný breaking change pro existující integrace.

Confidence

• high — jméno bylo nalezeno v databázi (přes 269 tisíc českých jmen)
• medium — fallback pravidlo se známou koncovkou
• low — obecné jazykové pravidlo
• unknown — jméno ponecháno v 1. pádě

JavaScript SDK

const r = await client.generateVocative({
  first_name: 'Petr',
  last_name: 'Novák',
  format: 'polite',
});
console.log(r.vocative); // "Petře Nováku"
console.log(r.polite);   // "pane Nováku"

Meta odpovědi

Každá odpověď v meta obsahuje total_names_in_db — aktuální počet jmen v databázi (cachováno na 1 hodinu).

{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "req_...",
    "total_names_in_db": 269092
  }
}

Statistiky databáze jmen

Vrátí celkový počet jmen v databázi a rozdělení podle typu. Zdarma (neúčtuje kredity), výsledek je serverově cachovaný na 1 hodinu.

Vyžaduje API klíč se scope osloveni:generate — stejný jako pro generování.

Příklad

curl -X GET https://api.microservices.cz/v1/osloveni/stats \
  -H "Authorization: Bearer ak_live_..."

Odpověď

{
  "ok": true,
  "data": {
    "total": 269092,
    "first_names": 35370,
    "last_names": 233722,
    "with_alternatives": 2103
  }
}

JavaScript SDK

const { data } = await client.getVocativeStats();
console.log(data.total); // 269092

Vývojářské nástroje

Sada nástrojů pro vývojáře — generování hesel, hashů, UUID, encoding a HMAC. Zdarma, limit 30 dotazů za minutu na API klíč. Vyžaduje scope dev:tools.

POST /v1/dev/password

curl -X POST https://api.microservices.cz/v1/dev/password \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"random","length":16,"count":5,"symbols":true,"exclude_ambiguous":true}'

type: random | passphrase (4 slova oddělená spojovníkem) | pin (jen číslice). Vrací pole passwords + entropy_bits.

POST /v1/dev/hash

curl -X POST https://api.microservices.cz/v1/dev/hash \
  -H "Authorization: Bearer ak_live_..." \
  -d '{"input":"hello","algorithm":"sha256","encoding":"hex"}'

Algoritmy: md5, sha1, sha256, sha384, sha512, sha3-256, sha3-512. Encoding: hex, base64, base64url. S "multiple": true vrátí všechny algoritmy najednou.

POST /v1/dev/password-hash

// Hash
{"mode":"hash","password":"secret","algorithm":"bcrypt","cost":12}

// Verify
{"mode":"verify","password":"secret","hash":"$2y$12$..."}

// Info (rozparsuje hash a vrátí algoritmus + parametry)
{"mode":"info","hash":"$argon2id$..."}

Algoritmy: bcrypt (cost 4-14), argon2id, argon2i. Použijte pro testovací data nebo migrace; pro produkci hashujte na vlastním serveru.

POST /v1/dev/uuid

{"type":"v7","count":10}                          // UUID v7 (time-sorted)
{"type":"nanoid","length":21,"alphabet":"url"}    // Nano ID
{"type":"ulid","count":5}                         // ULID

Typy: v4 (random UUID), v7 (time-sorted, vhodné pro DB PK), ulid, nanoid (alphabety: default, url, numbers, hex, lowercase), short.

POST /v1/dev/random

{"type":"bytes","length":32,"format":"base64url"}
{"type":"token","token_style":"api_key"}
{"type":"integer","min":1,"max":100}
{"type":"pick","items":["a","b","c"]}

Kryptograficky bezpečné náhodné hodnoty. Token styly: api_key, jwt_secret, session_id, csrf, webhook_secret.

POST /v1/dev/encode

{"operation":"encode","format":"base64","input":"hello"}
{"operation":"decode","format":"hex","input":"68656c6c6f"}
{"format":"jwt","input":"eyJhbGc..."}             // dekóduje JWT (bez ověření podpisu)

Formáty: base64, base64url, hex, url, html. Plus speciální mód jwt pro debugging JWT tokenů.

POST /v1/dev/hmac

// Sign
{"mode":"sign","input":"data","secret":"my-key","algorithm":"sha256","encoding":"hex"}

// Verify
{"mode":"verify","input":"data","secret":"my-key","signature":"...","algorithm":"sha256"}

HMAC podpisy pro webhook ověřování, API auth a podobně. Algoritmy: sha256, sha512, sha1, sha384.

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://www.microservices.cz/docs/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>

TypeScript

SDK obsahuje typové definice (sdk.d.ts) — všechny metody a návratové typy jsou typované, autocomplete funguje v každém moderním IDE bez další konfigurace.

Faktury

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

// Parsování — základní
const { data } = await client.parseInvoice(fileInput.files[0]);
console.log(data.invoice_number, data.total_with_vat);

// Parsování + embedded QR/ABO/SEPA + platba dnes
const result = await client.parseInvoice(file, {
  model: 'full',
  include: ['qr', 'abo', 'sepa'],
  payment_date: 'today',
});
document.getElementById('qr').innerHTML = `<img src="${result.data.payment.qr_svg}">`;

// Dávkové parsování (ZIP s více fakturami)
const batch = await client.parseInvoiceBatch(zipFile);

// Export do iDokladu / ABRA Flexi
await client.exportInvoice(data);

// Nahlásit chybně rozpoznanou fakturu
await client.sendParseFeedback(file, 'Špatně rozpoznaný dodavatel', data);

Generátor oslovení (5. pád)

const { data } = await client.generateVocative({
  first_name: 'Petr',
  last_name: 'Novák',
  format: 'polite',
});
console.log(data.vocative); // "pane Nováku"

Vývojářské nástroje (client.dev.*, zdarma, 30/min)

// Hesla
const pw = await client.dev.password({ type: 'random', length: 20, count: 5 });

// Hash (SHA-256, MD5, bcrypt…)
const sha = await client.dev.hash({ input: 'hello', algorithm: 'sha256' });
const bc = await client.dev.passwordHash({ mode: 'hash', password: 'secret', algorithm: 'bcrypt' });

// UUID v7 (time-sorted, vhodné pro DB primární klíče)
const ids = await client.dev.uuid({ type: 'v7', count: 10 });

// Náhodná data / tokeny
const bytes = await client.dev.random({ type: 'bytes', length: 32, format: 'hex' });
const apiKey = await client.dev.random({ type: 'token', token_style: 'api_key' });

// Encoding / decoding
const enc = await client.dev.encode({ operation: 'encode', format: 'base64', input: 'hello' });
const jwt = await client.dev.encode({ format: 'jwt', input: 'eyJhbGc...' });

// HMAC podpisy (webhook ověřování)
const sig = await client.dev.hmac({ input: 'payload', secret: 'shared', algorithm: 'sha256' });

Účet

const balance = await client.getCreditBalance();
const logs = await client.getUsage({ service: 'invoice-parse', limit: 50 });

Zpracování chyb

try {
  await client.parseInvoice(file);
} catch (err) {
  if (err instanceof Microservices.MicroservicesError) {
    console.error(err.code);   // 'insufficient_credits'
    console.error(err.status); // 402
    console.error(err.detail); // { code, message, docs_url, ... }
  }
}

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

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.