# Verejné dočasné PTDF relácie

Verejný endpoint vytvorí z dokumentu PTDF 1.0 krátkodobý odkaz do editora
pasteToPrint. Nevyžaduje účet, API kľúč ani platobnú kartu.

Jeho OpenAPI kontrakt je MIT-licensed podľa
[`PTDF-LICENSE.md`](PTDF-LICENSE.md); licencia sa nevzťahuje na hostovanú
serverovú implementáciu.

`GET /api/v1/public/sessions` vráti aktuálnu verziu služby, revíziu PTDF
kontraktu a odkazy `schemaUrl`, `capabilitiesUrl` a `templatesUrl`. Producent
ich má načítať pred použitím capability-gated orientácie alebo šablóny.

```http
POST /api/v1/public/sessions HTTP/1.1
Host: www.pastetoprint.com
Content-Type: application/vnd.pastetoprint.ptdf+json

{
  "schemaVersion": "ptp.document/1",
  "title": "Objednávka revíznych prác",
  "locale": "sk-SK",
  "template": "order",
  "blocks": [
    {
      "type": "paragraph",
      "text": "Objednávame vykonanie revíznych prác."
    }
  ]
}
```

Úspešná požiadavka vráti stav `201`:

```json
{
  "success": true,
  "sessionId": "64-znakovy-nahodny-token",
  "documentId": "64-znakovy-nahodny-token",
  "sessionUrl": "https://www.pastetoprint.com/api/v2/documents/...",
  "sessionToken": "ptp_session_tajny-manazersky-token",
  "editorUrl": "https://www.pastetoprint.com/open/editorovy-token",
  "viewUrl": "https://www.pastetoprint.com/view/view-token",
  "importUrl": "https://www.pastetoprint.com/#agentImport=...",
  "viewImportUrl": "https://www.pastetoprint.com/#agentImport=...",
  "schemaVersion": "ptp.document/1",
  "formatName": "PTDF",
  "formatVersion": "1.0",
  "expiresAt": "2026-07-20T12:00:00+00:00",
  "expiresInSeconds": 3600,
  "sessionTtlSeconds": 3600,
  "permissions": {
    "allowEditing": true,
    "allowExport": true
  },
  "temporary": true,
  "requiresUserConfirmation": true
}
```

Klient má používateľovi odovzdať `editorUrl`. Obsah sa najskôr zobrazí v
kontrolnom dialógu a do editora sa vloží až po výslovnom potvrdení používateľa.
API nikdy automaticky netlačí, neposiela ani neexportuje dokument.

## Voliteľná obálka

Pri `Content-Type: application/json` možno poslať aj obálku:

```json
{
  "document": {
    "schemaVersion": "ptp.document/1",
    "blocks": [
      {
        "type": "paragraph",
        "text": "Dokument pripravený na kontrolu."
      }
    ]
  },
  "session": {
    "expiresIn": 1800,
    "allowEditing": true,
    "allowExport": true
  }
}
```

`expiresIn` môže byť 300 až 3600 sekúnd. Hodnoty `allowEditing` a `allowExport`
sú booleany a editor ich reálne vynucuje. `viewUrl` vždy zakáže úpravy bez
ohľadu na `allowEditing`; tlač ostáva dostupná, export sa riadi
`allowExport`.

Ide o obmedzenia rozhrania, nie DRM: držiteľ capability odkazu obsah vidí.
Do verejnej dočasnej session preto nevkladajte tajomstvá ani údaje, ktoré
vyžadujú identitu konkrétneho príjemcu.

Odpoveď obsahuje aj tajný `sessionToken`. Cez
`GET`, `PATCH` a `DELETE /api/v2/documents/{sessionId}` možno session spravovať
s hlavičkou `X-Session-Token`. Rovnaký token povoľuje upload obrázkov cez
`POST /api/v2/documents/{sessionId}/assets`. Token neposielajte v URL ani ho
nezapisujte do logov.

## Verejné limity

- najviac 100 KiB na jednu JSON požiadavku,
- najviac 5 nových relácií za hodinu z jednej IP adresy,
- predvolená a maximálna platnosť 60 minút,
- minimálna voliteľná platnosť 5 minút,
- bez trvalého uloženia,
- bez HTML, CSS, JavaScriptu a vzdialených obrázkov,
- s podporou sémantických blokov pre strany, adresy, dátumy, sumy, QR kódy,
  zaškrtávacie a podpisové polia či upozornenia,
- vždy s kontrolou a potvrdením používateľa.

Pri prekročení limitu endpoint vráti `429` a hlavičku `Retry-After`. Odpovede
obsahujú aj `X-RateLimit-Limit`, `X-RateLimit-Remaining` a
`X-RateLimit-Reset`.

Relácia sa odstráni po expirácii alebo explicitným `DELETE`. Prijatie či
odmietnutie náhľadu ju nespotrebuje, aby zostali funkčné následné `PATCH` a oba
používateľské odkazy. Capability odkaz môže prečítať jeho držiteľ, preto do
dokumentu nevkladajte heslá, prístupové tokeny ani iné tajomstvá.

## Strojovo čitateľné zdroje

- OpenAPI: [`/api/v1/public/sessions/openapi.yaml`](api/v1/public/sessions/openapi.yaml)
- PTDF 1.0: [`PTDF-1.0.md`](PTDF-1.0.md)
- JSON Schema: [`/api/document-schema/v1/schema.json`](api/document-schema/v1/schema.json)
- capability descriptor: [`capabilities.json`](api/document-schema/v1/capabilities.json)
- obchodný príklad: [`semantic-example.json`](api/document-schema/v1/semantic-example.json)
- landscape príklad: [`landscape-example.json`](api/document-schema/v1/landscape-example.json)
- coloring/raster drawing príklad: [`coloring-drawing-example.json`](api/document-schema/v1/coloring-drawing-example.json)
- šablóny: [`GET /api/v2/templates`](api/v2/templates)

`GET /api/v1/public/sessions` vráti aktuálne limity služby ako JSON.

Pre vyššie limity, idempotenciu a tokenové TTL tiery je určené
[`POST /api/v2/documents`](API-V2.md).