Asynchronní razítková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:

{
  "data": {
    "signing": {
      "generateSignReport": {
        "hTMLReport": "OiJBMjU2S1ciLCJlbmMiOi…",
        "pDFReport": "OiJBMjU2S1ciLCJlbmMiOi…",
        "xMLReport": "OiJBMjU2S1ciLCJlbmMiOi…",
        "message": ""
      }
    }
  }
}

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 razítkování dokumentů je nutné zavolat koncový bod GraphQL API s mutací pro razítkování souborů, které předáme seznam identifikátorů dokumentů a parametry razítkování. Výsledkem bude URL, pomocí které lze čekat na dokončení operace, viz následující krok.

Parametry razítková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).

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

Metoda: POST

Hlavičky:

  • Accept: application/json

  • Authorization: Bearer <token>

  • Content-Type: application/json

GraphQL operace:

mutation timestampFiles(
  $files: [TimestampOperationParameters!]!
  $parameters: TimestampBatchParameters = null
) {
  signing {
    timestampFiles(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": "timestampFiles",
  "query": "mutation timestampFiles(\n  $files: …",
  "variables": {
    "files": [
      {
        "fileId": "eyJhbGciOiJIUzI1…"
      }
    ],
    "parameters": {
      "algorithmId": null
    }
  }
}

Výsledek:

{
  "data": {
    "signing": {
      "timestampFiles": {
        "jobOperationUrl": "https:// sofa.602.cz/api/sofa/v1/operations/job?wait=true&operationToken=eyJhbGciOiJBMjU2…",
        "jobOperationIdent": "4118d157-9489-4b87-a5ab-a57711c4ce53"
      }
    }
  }
}

Krok č. 4) Čekání na dokončení operace

Před stažením dokumentů opatřených časovým razítkem 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 časovým razítkem 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.