Asynchronní 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 seznam identifikátorů dokumentů a parametry podepisování. Výsledkem bude URL adresa, pomocí které lze čekat na dokončení operace, viz následující krok.

Parametry podepisování lze specifikovat globálně pro všechny dokumenty nebo samostatně pro každý dokument, případně lze kombinovat globální parametry s parametry jednotlivých dokumentů, přičemž parametry uvedené u jednotlivých dokumentů mají přednost před globálními parametry. 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), 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 signFiles(
  $files: [SignOperationParameters!]!
  $parameters: SignBatchParameters = null
) {
  signing {
    signFiles(files: $files, parameters: $parameters) {
      jobOperationUrl
      jobOperationIdent
    }
  }
}

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": "signFiles",
  "query": "mutation signFiles(\n  $files: …",
  "variables": {
    "files": [
      {
        "fileId": "eyJhbGciOiJIUzI1…"
      }
    ],
    "parameters": {
      "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": {
      "signFiles": {
        "jobOperationUrl": "https:// sofa.602.cz/api/sofa/v1/operations/job?wait=true&operationToken=eyJhbGciOiJBMjU2…",
        "jobOperationIdent": "4118d157-9489-4b87-a5ab-a57711c4ce53"
      }
    }
  }
}

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) Čekání na dokončení operace

Před stažením dokumentů opatřených podpisem je potřeba nejprve počkat na dokončení zpracování. K tomu slouží URL z výsledku GraphQL mutace z předchozího kroku, která vede na koncový bod Job Operations API, které slouží pro získání stavu probíhajících dlouhotrvajících operací. V případě zmíněné URL se pro zjednodušení jedná o synchronní volání, tzn. že koncový bod nevrací výsledek ihned, ale snaží se počkat co nejdéle na dokončení probíhající operace. V případě chyby, dokončení operace nebo vypršení časového limitu se vrátí výsledek, který obsahuje stavovou informaci (state), která může nabývat jednu z následujících hodnot:

done – operace byla úspěšně dokončena.
canceled – operace byla zrušena.
error – došlo k chybě.
pending – operace stále probíhá.
deleted - vypršela platnost operace (doba platnosti: 4 hodiny).

JSONPath pro získání stavu operace/podepisování:

$.state

JSONPath pro získání seznamu souborů (platné pouze pro stav done):

$.data.files

Kromě stavu pending jsou všechny ostatní stavy konečné, tzn. že nemá smysl koncový bod volat znovu. V případě úspěšného dokončení operace (done) se navíc vrací strukturovaná data ve formátu JSON, která obsahují výsledek operace obsahující identifikátory dokumentů opatřených podpisem doplněné o identifikátory původních dokumentů kvůli spárování.

Koncový bod: /api/sofa/v1/operations/job

Metoda: GET

Hlavičky:

Authorization: Bearer <token>

Příklad:

GET /api/sofa/v1/operations/job?wait=true&operationToken=eyJhbGciOiJBMjU2…
Host: sofaws.602.cz
Authorization: Bearer eyJhbGciOiJBMjU2…

Výsledek v případě úspěšného dokončení operace:

{
  "id": "8e9f882e-6f2a-4ce7-ba50-a7e208729b43",
  "type": "signpoint-sdk",
  "state": "done",
  "data": {
    "files": [
      {
        "state": "done",
        "fileId": "eyJhbGciOiJIUzI1…",
        "resultFileId": "eyJhbGciOiJIUzI1…"
      }
    ]
}

Výsledek v případě stále probíhající operace:

{
  "id": "8e9f882e-6f2a-4ce7-ba50-a7e208729b43",
  "type": "signpoint-sdk",
  "state": "pending",
  "data": null
}

Výsledek v případě chyby:

{
  "id": "8e9f882e-6f2a-4ce7-ba50-a7e208729b43",
  "type": "signpoint-sdk",
  "state": "error",
  "data": null
}

Krok č. 5) 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.