# pasteToPrint Document API v2

API v2 vytvára krátkodobú editorovú session zo štruktúrovaného dokumentu
**PTDF 1.0**. PTDF 1.0 je verejný názov doterajšieho Document Schema v1 a jeho
stabilný wire identifikátor ostáva `ptp.document/1`. API ani existujúci JSON sa
tým nemenia. Kanonické pomenovanie a kompatibilitný záväzok sú v
[`PTDF-1.0.md`](PTDF-1.0.md).

API neočakáva ani neprijíma voľné HTML alebo CSS. Vzhľad vytvára pasteToPrint zo
sémantických blokov.

Strojovo čitateľný kontrakt [`api/v2/openapi.yaml`](api/v2/openapi.yaml) je
zverejnený pod MIT licenciou. Licencia kontraktu neotvára serverovú
implementáciu ani prevádzkovanú službu; presná hranica je v
[`PTDF-LICENSE.md`](PTDF-LICENSE.md).

Pre malé jednorazové dokumenty bez registrácie a bez povinného
`Idempotency-Key` je k dispozícii
[`POST /api/v1/public/sessions`](PUBLIC-SESSIONS-API.md). Verejný endpoint má
samostatný limit 100 KiB, päť relácií za hodinu z jednej IP a TTL najviac jednu
hodinu. API v2 zostáva určené pre idempotentných a tokenových klientov.

## Endpoint

```http
POST /api/v2/documents HTTP/1.1
Host: www.pastetoprint.com
Content-Type: application/vnd.pastetoprint.ptdf+json
Idempotency-Key: order-2026-07-19-001

{
  "schemaVersion": "ptp.document/1",
  "title": "Objednávka revíznych prác",
  "locale": "sk-SK",
  "paper": {
    "size": "A4",
    "orientation": "portrait"
  },
  "template": "order",
  "blocks": [
    {
      "type": "heading",
      "level": 1,
      "text": "Objednávka revíznych prác"
    },
    {
      "type": "paragraph",
      "text": "Termín vykonania: do 30 dní."
    }
  ]
}
```

API prijíma `application/vnd.pastetoprint.ptdf+json` aj spätne kompatibilné
`application/json`. Oba typy prijímajú priamo PTDF 1.0 JSON; `application/json`
navyše podporuje API obálku pre session a layout nastavenia.

Ak klient potrebuje nastaviť okraje, použije pri `application/json` API obálku.
Okraje sú layout metadata session, nie nový člen zmrazeného PTDF 1.0:

```json
{
  "document": {
    "schemaVersion": "ptp.document/1",
    "title": "Dokument s vlastnými okrajmi",
    "paper": { "size": "A4", "orientation": "portrait" },
    "blocks": [
      { "type": "paragraph", "text": "Obsah dokumentu" }
    ]
  },
  "layout": {
    "marginsMm": {
      "top": 20,
      "right": 15,
      "bottom": 20,
      "left": 15
    }
  }
}
```

Všetky štyri hodnoty sú povinné, sú v milimetroch a môžu byť od `3` do `80`
vrátane desatinných hodnôt (server ich normalizuje na dve desatinné miesta).
Bez `layout` sa použijú predvolené okraje vybraného formátu papiera. Vendor
media type prijíma naďalej iba čistý PTDF dokument bez API obálky.

Úplný strojovo čitateľný kontrakt PTDF 1.0 je v
[`/api/document-schema/v1/schema.json`](/api/document-schema/v1/schema.json).
Príklad so sémantickými obchodnými blokmi `party`, `address`, `date`, `money`,
`qr_code`, `signature` a ďalšími je v
[`semantic-example.json`](/api/document-schema/v1/semantic-example.json).
OpenAPI 3.1 opis endpointu je v
[`/api/v2/openapi.yaml`](/api/v2/openapi.yaml).
Podporované hodnoty `template` vráti
[`GET /api/v2/templates`](/api/v2/templates).

## Odpoveď

Nová session vráti stav `201`:

```json
{
  "success": true,
  "documentId": "64-znakový-náhodný-token",
  "sessionId": "64-znakový-verejný-identifikátor",
  "sessionUrl": "https://www.pastetoprint.com/api/v2/documents/...",
  "sessionToken": "ptp_session_tajný-manažérsky-token",
  "editorUrl": "https://www.pastetoprint.com/open/editorový-token",
  "viewUrl": "https://www.pastetoprint.com/view/view-token",
  "importUrl": "https://www.pastetoprint.com/#agentImport=...",
  "viewImportUrl": "https://www.pastetoprint.com/#agentImport=...",
  "nativeDeepLink": "pastetoprint://open/...",
  "pwaDeepLink": "web+pastetoprint://open/...",
  "schemaVersion": "ptp.document/1",
  "expiresAt": "2026-07-19T21:15:00+00:00",
  "expiresInSeconds": 900,
  "sessionTtlSeconds": 900,
  "ttlTier": "anonymous",
  "authentication": {
    "mode": "anonymous",
    "tier": "anonymous",
    "scopes": [
      "document:create"
    ]
  },
  "permissions": {
    "allowEditing": true,
    "allowExport": true
  },
  "layout": {
    "marginsMm": { "top": 20, "right": 15, "bottom": 20, "left": 15 }
  },
  "requiresUserConfirmation": true
}
```

`requiresUserConfirmation` je konzervatívny signál pre klienta, pretože API
nevie, či cieľový editor už obsahuje dokument. pasteToPrint môže spravovaný
editovateľný PTDF automaticky vložiť iba do úplne prázdneho editora. Vtedy
zobrazí oznámenie s jednokrokovým `Späť`; pri neprázdnom alebo read-only editore
zostáva explicitná voľba `Pridať`, `Nahradiť` alebo `Zrušiť`.

AI má používateľovi vrátiť alebo otvoriť `editorUrl`. Používateľ výsledný návrh
skontroluje; modal potvrdí vždy okrem bezpečného automatického vloženia do
prázdneho editora opísaného vyššie. API nespúšťa tlač ani export automaticky.
Voliteľné protokolové odkazy a bezpečný HTTPS fallback sú opísané v
[`DEEP-LINKS.md`](DEEP-LINKS.md).

`sessionId` nie je oprávnenie a sám nestačí na načítanie dokumentu.
`editorUrl` a `viewUrl` obsahujú dva rozdielne capability tokeny. View odkaz
vždy vypne úpravy; export sa riadi hodnotou `allowExport`.

Tieto práva riadia rozhranie a pracovný tok pasteToPrint, nie DRM. Držiteľ
capability odkazu vie obsah zobraziť a operačný systém môže umožniť snímku,
kopírovanie či vlastnú tlač. Na ochranu tajných údajov capability odkazy
nepoužívajte ako náhradu autorizácie používateľa.

`sessionToken` je tajný manažérsky capability token. Posiela sa iba v hlavičke
`X-Session-Token`, nikdy v URL. Klient ho potrebuje na anonymné `GET`, `PATCH`,
`DELETE` a upload assetov. Tokenový API klient môže namiesto neho použiť svoj
Bearer token s príslušným scope, ale iba pre session, ktorú sám vytvoril.

## Správa session

Aktuálny dokument, práva a revíziu načíta:

```http
GET /api/v2/documents/{sessionId}
X-Session-Token: ptp_session_...
```

Odpoveď obsahuje `ETag`, napríklad `"session-1"`. Dokument alebo práva sa
aktualizujú atomicky:

```http
PATCH /api/v2/documents/{sessionId}
Content-Type: application/json
X-Session-Token: ptp_session_...
If-Match: "session-1"

{
  "document": {
    "schemaVersion": "ptp.document/1",
    "blocks": [
      {
        "type": "paragraph",
        "text": "Aktualizovaný dokument"
      }
    ]
  },
  "permissions": {
    "allowEditing": false,
    "allowExport": true
  },
  "layout": {
    "marginsMm": { "top": 18, "right": 14, "bottom": 18, "left": 14 }
  }
}
```

`PATCH` môže poslať iba `layout` bez zmeny dokumentu. Hodnota `"layout": null`
odstráni vlastné okraje a obnoví predvolené hodnoty aktuálneho formátu papiera.

Neaktuálny `If-Match` vráti `412 session_revision_conflict`. Okamžité
odstránenie session, oboch používateľských capability odkazov aj assetov:

```http
DELETE /api/v2/documents/{sessionId}
X-Session-Token: ptp_session_...
```

## Session assety

Rasterový obrázok možno nahrať ako `multipart/form-data` pole `file` alebo ako
JSON s bezpečným Data URL:

```http
POST /api/v2/documents/{sessionId}/assets
Content-Type: application/json
X-Session-Token: ptp_session_...

{
  "name": "logo.png",
  "dataUrl": "data:image/png;base64,..."
}
```

Odpoveď vráti `assetId`, napríklad `ast_...`. Nasledujúci `PATCH` ho môže
dočasne použiť namiesto `dataUrl` v bloku `image` alebo `logo`. Server overí,
že asset patrí danej session, a pred uložením ho prevedie na validný PTDF Data
URL. Asset nie je verejná URL, limit je 1 MiB na obrázok a 24 obrázkov na
session; odstráni sa spolu so session.

## Idempotencia

`Idempotency-Key` je povinný, má 8 až 128 znakov a môže obsahovať písmená,
číslice, bodku, podčiarkovník, dvojbodku a pomlčku. Kľúč je na anonymnom
endpointe oddelený podľa IP adresy.

- prvá požiadavka vráti `201` a `Idempotency-Replayed: false`,
- rovnaký normalizovaný dokument s rovnakým kľúčom vráti pôvodnú session,
  stav `200` a `Idempotency-Replayed: true`,
- iný dokument s už použitým kľúčom vráti `409`,
- ak bola pôvodná session odstránená alebo vypršala, opakovanie vráti `410`.

Anonymná session aj jej idempotentný záznam majú TTL najviac 15 minút;
tokenové session sa riadia tierom uvedeným nižšie. Obsah sa neukladá natrvalo.
Do dokumentu nevkladajte heslá, API tokeny ani iné tajomstvá.

## Autentifikácia a TTL

Bez `Authorization` API funguje anonymne s TTL najviac 15 minút. Nakonfigurovaný
AI klient môže použiť:

```http
Authorization: Bearer ptp_ai_...
X-Document-TTL: 86400
```

`standard` token povoľuje session do 24 hodín a `trusted` token do 7 dní.
Endpoint vyžaduje scope `document:create`. Skutočná TTL je v odpovedi
`sessionTtlSeconds`, `ttlTier` a hlavičke `X-Document-TTL-Applied`.

Formát bezpečnej hashovanej konfigurácie, generátor tokenov a pravidlá
revokácie sú v [`DOCUMENT-API-AUTH.md`](DOCUMENT-API-AUTH.md).

## MCP a AI Builder

AI klienti s podporou Model Context Protocol môžu použiť lokálny `stdio`
server opísaný v [`MCP-SERVER.md`](MCP-SERVER.md). Poskytuje nástroje
`list_templates`, `get_document_schema`, `validate_document`,
`create_document`, `update_document` a `get_document_links`. Bearer token aj
dočasný správcovský token zostávajú v MCP procese a neposielajú sa modelu ako
parametre ani ako súčasť výsledkov.

## Šablóny

Pole `template` je stabilný identifikátor, napríklad `order` alebo
`price_offer`. Musí byť uvedený vo verejnom Template Catalog v1:

```http
GET /api/v2/templates HTTP/1.1
Host: www.pastetoprint.com
Accept: application/json
```

Editor z ID vyberie vlastný bezpečný prezentačný profil a použije ho v editore,
náhľade, tlači aj PDF. AI neposiela CSS a šablóna nemení obsah `blocks`.
Neznáme ID sa odmietne stavom `422` a chybou `unsupported_template`.

## Kompatibilita

Pôvodné `POST /api/v1/document` zostáva dostupné pre klientov posielajúcich
`text`, HTML/CSS alebo obrázkové položky. Pre nové AI integrácie je preferované
API v2 so štruktúrovaným PTDF 1.0 (`ptp.document/1`).

API v2 používa zmrazenú PTDF revíziu `2026-08-01`; revízia nie je členom
dokumentu. Aktuálne enumy, limity a konverzie klient zistí z
[`capabilities.json`](api/document-schema/v1/capabilities.json). Pri neznámych
schopnostiach prijímateľa použije `portrait` a `blank`. `landscape` a šesť
`coloring_*` ID použije až po capability alebo Template Catalog discovery.

Verejné validné vstupy:

- [`landscape-example.json`](api/document-schema/v1/landscape-example.json)
- [`coloring-drawing-example.json`](api/document-schema/v1/coloring-drawing-example.json)

Kresba sa cez PTDF prenáša iba ako rastrový `image`. API neuchováva
`ptp.drawing/1`, vrstvy, vektory, históriu ani drawing metadata. Klient, ktorý
taký export vytvára, musí používateľovi oznámiť `drawingFlattened`.

Smer spätnej kompatibility a presná revízna história sú v
[`PTDF-COMPATIBILITY.md`](PTDF-COMPATIBILITY.md).