Synchronní pečetění souborů

Krok č. 1) Přihlášení

Pro přístup k API je nutné nejprve získat přístupový token pomocí koncového bodu pro přihlášení externího informačního systému.

Koncový bod: /api/sofa/v1/auth/extis/login

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Content-Type: application/json

Parametry:

  • login … uživatelské jméno externího informačního systému.

  • password … heslo externího informačního systému.

Příklad:

POST /api/sofa/v1/auth/extis/login HTTP/1.1
Host: sofaws.602.cz
Accept: application/json
Content-Length: …
Content-Type: application/json

{
  "login": "48a0ecdd540849f0af416307406467f0",
  "password": "wau3S99vx2d_NW2P"
}

Výsledek:

{
  "token": "eyJhbGciOiJBMjU2…"
}

Krok č. 2) Nahrání souborů

V dalším kroku je nutné nahrát dokumenty jeden po druhém do výchozího úložiště (default) pomocí koncového bodu File API. Výsledkem bude seznam identifikátorů souborů použitý v dalším kroku.

Koncový bod: /api/sofa/v2/file?storeId=default

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Authorization: Bearer <token>

  • Content-Type: multipart/form-data

Parametry:

  • file … soubor dokumentu (ve verzi 2.0 se již nepoužívá hlavička FileId s parametry kódovanými ve formátu JSON, ale přenáší se standardní cestou pro upload souborů podle RFC 2854, tzn. že se název souboru uvádí v hlavičce Content-Disposition, velikost souboru v hlavičce Content-Length a typ souboru v hlavičce Content-Type).

Příklad:

POST /api/sofa/v2/file?storeId=default HTTP/1.1
Host: sofaws.602.cz
Accept: application/json
Authorization: Bearer eyJhbGciOiJBMjU2…
Content-Length: …
Content-Type: multipart/form-data; boundary="-----086735ab-f408-405e-9628-4eb525d56d71"

-------086735ab-f408-405e-9628-4eb525d56d71
Content-Disposition: form-data; name="file"; filename="Document.pdf"
Content-Length: …
Content-Type: application/pdf

…binary file content…
-------086735ab-f408-405e-9628-4eb525d56d71--

Výsledek:

{
  "fileId": "eyJhbGciOiJIUzI1…"
}

Krok č. 3) Spuštění GraphQL mutace

Pro pečetění dokumentů je nutné zavolat koncový bod GraphQL API s mutací pro pečetění souborů, které předáme identifikátor dokumentu a parametry pečetění. Výsledkem je identifikátor dokumentu opatřeného pečetí. Aktuálně jsou podporované následující parametry:

  • algorithmId … identifikátor algoritmu, např. SHA-256 nebo SHA-512 (výchozí hodnota: SHA-256).

  • certificateId … identifikátor certifikátu (HSM ID) (výchozí hodnota: default).

  • sealParameters

    • addTimestamp … příznak vložení časového razítka.

    • addVisualSignature … příznak doplnění vizuálního podpisu.

    • reason … důvod podpisu.

    • location … umístění.

    • contact … kontakt.

    • parametry vizuálního podpisu, pouze pokud addVisualSignature = true:

      Umístění:

      • page … číslo stránky počítáno od začátku dokumentu (kladná hodnota), resp. od konce dokumentu (záporná hodnota).

      • posX … souřadnice levého okraje vizuálního podpisu v rozlišení 72 DPI.

      • posY … souřadnice horního okraje vizuálního podpisu v rozlišení 72 DPI od dolního okraje stránky (kladná hodnota), resp. od horního okraje stránky (záporná hodnota).

      • sizeX … šířka vizuálního podpisu v rozlišení 72 DPI.

      • sizeY … výška vizuálního podpisu v rozlišení 72 DPI.

      Text:

      • text … text vizuálního podpisu.

      • textHeader … textová hlavička vizuálního podpisu.

      Obrázek:

      • image … obrázek vizuálního podpisu (Base-64 kódovaný PNG soubor).

  • signingProperties

    • signerName … jméno podepisujícího.

    • signerPhoneNumber … telefonní číslo podepisujícího.

    • signatureAutoLocationWidth … šířka automatického umístění vizuálního podpisu.

    • signatureAutoLocationHeight … výška automatického umístění vizuálního podpisu.

    • signatureAutoLocationSearchText … text automatického umístění vizuálního podpisu.

Koncový bod: /api/sofa/v1/graphql

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Authorization: Bearer <token>

  • Content-Type: application/json

GraphQL operace:

mutation sealFile($file: SealOperationParameters!) {
  signing {
    sealFile(file: $file)
  }
}

Příklad:

POST /api/sofa/v1/graphql HTTP/1.1
Host: sofaws.602.cz
Accept: application/json
Authorization: Bearer eyJhbGciOiJBMjU2…
Content-Length: …
Content-Type: application/json

{
  "operationName": "sealFile",
  "query": "mutation sealFile(\n  $file: …",
  "variables": {
    "file": {
      "fileId": "eyJhbGciOiJIUzI1…",
      "algorithmId": null,
      "certificateId": null,
      "sealParameters": {
        "addTimestamp": true,
        "addVisualSignature": true,
        "reason": null,
        "location": null,
        "contact": null,
        "page": 1,
        "posX": 10,
        "posY": -10,
        "sizeX": 250,
        "sizeY": 50,
        "text": "Text podpisu",
        "textHeader": null,
        "image": null
      },
      "signingProperties": {
        "signerName": "Test",
        "signerPhoneNumber": "Test",
        "signatureAutoLocationWidth": null,
        "signatureAutoLocationHeight": null,
        "signatureAutoLocationSearchText": null
      }
    }
  }
}

Výsledek:

{
  "data": {
    "signing": {
      "sealFile": "eyJhbGciOiJIUzI1…"
    }
  }
}

Krok č. 4) Stažení souborů

Posledním krokem je stažení podepsaných souborů jeden po druhém pomocí koncového bodu File API:

Koncový bod: /api/sofa/v2/file

Metoda: GET

Hlavičky:

  • Authorization: Bearer <token>

  • Parametry:

  • fileId … identifikátor stahovaného dokumentu.

Příklad:

GET /api/sofa/v2/file?fileId=eyJhbGciOiJIUzI1…
Host: sofaws.602.cz
Authorization: Bearer eyJhbGciOiJBMjU2…

Výsledek:

Výsledkem je stahovaný dokument.

Název souboru lze získat buď standardně z hlavičky Content-Disposition, nebo File API v2 nastavuje pro snazší zpracování hlavičku X-Sofa-FileName.