Synchronní podepisová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 pod identitou konkrétního uživatele.

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

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.
impersonateUserId … LDAP identifikátor uživatele, jehož identitou má externí informační systém vystupovat (návod na zjištění tohoto identifikátoru je uveden na konci dokumentu).

Příklad:

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

{
  "login": "48a0ecdd540849f0af416307406467f0",
  "password": "wau3S99vx2d_NW2P",
  "impersonateUserId": "9e5f2f76-fff5-44c3-b943-06a95fdc08e2"
}

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 podepisování dokumentů je nutné zavolat koncový bod GraphQL API s mutací pro podepisování souborů, které předáme identifikátor dokumentu a parametry podepisování. Výsledkem je identifikátor dokumentu opatřeného podpisem. 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).
certificatePIN … PIN certifikátu.
sealParameters
- addTimestamp … příznak vložení časového razítka.
- addVisualSignature … příznak doplnění vizuálního podpisu.
- showParaphImage … příznak zobrazení obrázku parafy.
- 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), respektive 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), respektive 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 signFile($file: SignOperationParameters!) {
  signing {
    signFile(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": "signFile",
  "query": "mutation signFile(\n  $file: …",
  "variables": {
    "file": {
      "fileId": "eyJhbGciOiJIUzI1…",
      "algorithmId": null,
      "certificateId": "3fbc87f3-f5fb-4211-934a-881b76ca52b6-x3x",
      "certificatePIN": "12345",
      "sealParameters": {
        "addTimestamp": true,
        "addVisualSignature": true,
        "showParaphImage": 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": {
      "signFile": "eyJhbGciOiJIUzI1…"
    }
  }
}

Důležité poznámky:

Pro podepisování lokálními certifikáty je nutné využít služby podepisování pomocí formuláře.
PIN certifikátu je z bezpečnostních důvodů nutné vždy zadávat do proměnných (variables).
Na rozdíl od pečetění jsou některé parametry načítány z konfigurace podepisujícího (impersonovaného) uživatele, konkrétně se jedná o parametry: text, textHeader a image, takže je není nutné zadávat; pokud jsou uvedeny, mají vyšší prioritu před hodnotami načtenými z konfigurace.
Pro umístění vizuálního podpisu je možné využít služby automatického umístění na základě vyhledaného textu, případně ještě doplněné o šířku a výšku; v tomto případě není nutné zadávat poziční parametry: page, posX, posY, sizeX a sizeY, jelikož budou nahrazeny automaticky vypočítanými hodnotami.

Pro zjištění seznamu certifikátů lze použít následující GraphQL dotazy, resp. jejich upravené verze:

GraphQL operace:

query getCertificates(
  $isDeleted: Boolean! = false
  $isExpired: Boolean! = false
  $isRevoked: Boolean! = false
) {
  certificates {
    certificates(
      where: {
        and: [
          { sys: { isDeleted: $isDeleted } }
          { sys: { isExpired: $isExpired } }
          { sys: { isRevoked: $isRevoked } }
        ]
      }
    ) {
      edges {
        node {
          id
          hsmId
          subject
          certificateName
          serialNumber
          isDeleted
          isExpired
          isRevoked
          user {
            id
            userName
            completeName
          }
        }
      }
    }
  }
}

GraphQL operace:

query getCertificatesForUser(
  $userId: String!
  $isDeleted: Boolean! = false
  $isExpired: Boolean! = false
  $isRevoked: Boolean! = false
) {
  certificates {
    certificates(
      where: {
        and: [
          { eqString: { left: { sys: USER_ID }, right: { const: $userId } } }
          { sys: { isDeleted: $isDeleted } }
          { sys: { isExpired: $isExpired } }
          { sys: { isRevoked: $isRevoked } }
        ]
      }
    ) {
      edges {
        node {
          id
          hsmId
          subject
          certificateName
          serialNumber
          isDeleted
          isExpired
          isRevoked
        }
      }
    }
  }
}

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.