Skip to content

Downloading documents

Pobieranie dokumentów

Na podstawie przesłanych przez T-API danych, w Pergaminie tworzone są dokumenty. Użytkownicy mogą je zobaczyć w systemie, ale także pobierać w postaci plików PDF i zapisywać na swoich urządzeniach.

Uzyskanie ID dokumentów

Do pobrania plików PDF z transakcji niezbędne jest poznanie identyfikatorów dokumentów. Można je uzyskać poprzez żądanie GET /api/v2/documents oraz parametry:

  • board_id - identyfikator zespołu,
  • transaction[id] - nazwa transakcji,
  • transaction[data_stream] - nazwa strumienia danych w konkretnej transakcji.

Przykładowy request: 

curl --location --globoff 'https://api.pergam.in/api/v2/documents?board_id={boardId}&transaction[id]={transactionName}&transaction[data_stream]={dataStreamName}&per_page=1' \
--header 'Authorization: Bearer {token}'

Pobieranie dokumentów na dysk urządzenia

Znając ID dokumentów, można je wykorzystać w requeście odpowiadającym za przygotowanie plików do pobrania. Wszystkie zadania pobierania dokumentów z Pergaminu są kolejkowane.

Za pośrednictwem Pergaminu możliwe jest pobranie 1 dokumentu, jak i paczki dokumentów. W przypadku paczki dokumentów może być ona kompresowana do zbiorczego pliku z rozszerzeniem .zip. Możliwe jest również nadanie takiemu plikowi hasła zabezpieczającego.

Request do przygotowania zadania pobierania dokumentu lub dokumentów wysyłany jest za pośrednictwem metody POST do endpointa /api/v2/pdfs.

Wzór payloadu: 

{
  "documents": [
    {
      "id": 123,
      "excluded_external_files_ids": [],
      "excluded_attachments_ids": [],
      "render_certificate": true,
      "render_base_contract": true
    }
  ],
  "zip": false,
  "zip_name": "string",
  "zip_password": "string",
  "inline": true
}
Powyższy wzór zawiera pola:

  • id - wskazujące identyfikator dokumentu,
  • excluded_external_files_ids - umożliwiające podanie identyfikatorów plików zewnętrznych, które mają być pominięte podczas pobierania,
  • excluded_attachments_ids - pozwalające na wskazanei identyfikatorów załączników szablonowych, które mają być pominięte podczas pobierania,
  • render_certificate - typu boolean, określajace, czy pobierany dokument ma być opatrzony certyfikatem podpisu.
  • render_base_contract - określające, czy ma być pobrany dokument główny.

Przykładowy payload pobierania 1 pliku bez kompresowania: 

{
    "documents":[{"id":171410}],
    "zip":false,
    "inline":false
}
Przykładowy payload pobierania 2 plików bez kompresowania: 
{
    "documents":[{"id":171410},{"id":171409}],
    "zip":false,
    "inline":false
}
Przykładowy payload pobierania 2 plików z kompresją bez hasła i z bez nadawania konkretnej nazwy: 
{
    "documents":[{"id":171410},{"id":171409}],
    "zip":true,
    "inline":false
}
Przykładowy payload pobierania 2 plików z kompresją bez hasła i z własną nazwą paczki: 
{
    "documents":[{"id":171410},{"id":171409}],
    "zip":true,
    "zip_name": "documents",
    "inline":false
}
Przykładowy payload pobierania 2 plików z kompresją z hasłem i z własną nazwą paczki: 
{
    "documents":[{"id":171410},{"id":171409}],
    "zip":true,
    "zip_name": "documents",
    "zip_password": "ttYK1kEWsqbjfG0",
    "inline":false
}

W odpowiedzi każdego z powyższych requestów wskazany będzie ID zadania. Na jeg podstawie możliwe jest odpytywanie systemu o status, a w efekcie o linki pobierania dokumentów.

Przykładowa odpowiedź po wysłaniu requestu z przygotowaniem zadania pobierania plików PDF: 

{
    "data": {
        "id": "{jobId}",
        "status": "waiting",
        "progress": 0,
        "processed": 0,
        "failed": 0,
        "total": 2,
        "response": {},
        "messages": [],
        "__links": [
            {
                "rel": "self",
                "type": "GET",
                "href": "https://api.pergam.in/api/v2/batches/{jobId}"
            }
        ]
    }
}
Podany w powyższej odpwoiedzi ID zadania należy wykorzystać w requeście GET /api/v2/batches/{jobId}. Żądanie to zwróci informację na temat linka do pobierania 1 dokumentu, kilku dokumentów lub paczki dokumentów - w zależności od przesłanego wcześniej requestu zadania.

Przykład zwróconej odpowiedzi: 

{
    "data": {
        "id": "{jobId}",
        "status": "finished",
        "progress": 100,
        "processed": 2,
        "failed": 0,
        "total": 2,
        "response": {
            "type": "DOWNLOAD",
            "urls": [
                {
                    "id": 000000,
                    "url": "{link}"
                },
                {
                    "id": 000001,
                    "url": "{link}"
                }
            ]
        },
        "messages": [],
        "__links": [
            {
                "rel": "self",
                "type": "GET",
                "href": "{jobId}"
            }
        ]
    }
}