API

Dokument został automatycznie przetłumaczony przy użyciu technologii uczenia maszynowego.

Za pomocą API DiMaker można tworzyć pliki z danymi osobowymi i, w razie potrzeby, dostarczać je odbiorcom. Zapytania do API mogą pochodzić zarówno z innego serwera, jak i z przeglądarki przez CORS request.

Od czego zacząć

W sekcji „Integracja” - „Tokeny API” należy uzyskać Bezpieczny tokken do zapytań i umożliwić jego użycie. Ponadto, konieczne jest utworzenie dokumentu zawierającego zmienne dla danych osobowych, a także szablonu wiadomości e-mail do wysyłek oraz folderu w Dysku dla gotowych plików.

Tworzenie plików

Aby tworzyć pliki, należy wysyłać zapytania POST-DATA, POST-JSON lub GET na adres
https://dimaker.app/api/v1/create/
z danymi podanymi poniżej.
Kodowanie zapytania - UTF-8. Pola wymagane są oznaczone gwiazdką.

  • secure*

    Tokken (ciąg znaków, 36 znaków)

  • doc_id*

    ID dokumentu (ciąg znaków, 36 znaków), który będzie używany do tworzenia pliku. ID można uzyskać z paska adresu, kiedy dokument jest otwarty. Dokument nie powinien być w koszu, ale może znajdować się w dowolnej tece Dokumentów.

  • mask*

    JSON-ciąg zawierający wszystkie zmienne do zamiany w formie klucz (zmienna) - wartość (tekst do zamiany). Może zawierać dane do tworzenia kilku plików (bez ograniczeń co do liczby).
    Przykład dla jednego pliku:
    [{"%name": "Ivanov", "%points":"100"}]
    Przykład dla kilku plików:
    [{"%name": "Ivanov", "%points":"100"}, {"%name": "Petrov", "%points":"200"}, {"%name": "Sidorov", "%points":"300"}]
    Aby wskazać adres e-mail, użyj %email, a dla nazwy pliku - %filename. Aby wysłać utworzone pliki na kilka adresów e-mail, należy je podać oddzielone przecinkami. Status wysyłki w Dysku będzie wyświetlany dla pierwszego adresu.
    Można używać tylko cudzysłowów zgodnie ze standardem. Jeśli wartość klucza zawiera cudzysłowy, muszą być one zmaskowane.

    Aby przekazać obraz w bloku z obrazem, można użyć bezpośredniego linku (http:// lub https://) lub zakodowanego w Base64 obrazu. W tym drugim przypadku ciąg powinien zaczynać się od "data:image/".

    Alternatywna metoda
    Jeśli nie ma możliwości wysłania JSON-ciągu, można wysłać ciągi do zamiany jako pola zapytania. Każda zmienna do zamiany powinna zaczynać się prefiksem mask_, na przykład mask_name i zawierać wartość do zamiany. W dokumencie zostanie przeprowadzone wyszukiwanie zmiennej za prefiksem. Przykładowo, polu mask_name odpowiada zmienna %name. Aby wskazać adres e-mail w tym przypadku, należy użyć mask_email, a nazwę pliku - mask_filename.

  • mail_id

    ID szablonu wiadomości (ciąg znaków, 36 znaków) do wysyłki e-mail. ID można uzyskać z paska adresu, kiedy szablon jest otwarty. Jeśli zmienna nie jest przekazana, to wiadomość nie będzie wysłana.

  • email_send

    Czas wysyłania wiadomości z plikiem. Może przyjąć następujące wartości:
    onfinish - Wyślij wszystkie wiadomości po utworzeniu wszystkich plików (domyślnie)
    oncreate - Wyślij wiadomości natychmiast po utworzeniu pliku. Przy tworzeniu jednego pliku, onfinish i oncreate są identyczne.
    timeout - Wyślij wiadomości po określonym czasie. W tym przypadku należy przekazać jeszcze dwa parametry:
    email_timeout_value - wartość cyfrowa odstępu czasu, po którym wysyłać wiadomości, wartość całkowita
    email_timeout_unit - jednostka miary odstępu czasu. Może przyjąć wartość "m" (minuty), "h" (godziny), "d" (dni).
    Lub, aby wskazać dokładny czas wysyłki, należy przekazać czas w formacie unix time w email_timeout_timestamp. Jeśli podano zarówno email_timeout_value, jak i email_timeout_timestamp, priorytet będzie miał ten drugi.

  • folder_id

    ID folderu w Dysku (ciąg znaków, 36 znaków) do przechowywania plików. Jeśli folderu nie ma, to zostanie utworzony automatycznie przy tworzeniu pierwszego pliku.

  • storage_period

    Czas przechowywania plików w Dysku. Jeśli parametr nie jest wskazany, pliki będą przechowywane bezterminowo, do ręcznego usunięcia. Aby usunąć po określonym czasie, należy przyjąć wartość:
    timeout. W tym przypadku należy przekazać jeszcze dwa parametry:
       storage_period_timeout_value - wartość cyfrowa odstępu czasu, po którym usunąć pliki, wartość całkowita
       storage_period_timeout_unit - jednostka miary odstępu czasu. Może przyjąć wartość "m" (minuty), "h" (godziny), "d" (dni).
    Lub, aby wskazać dokładny czas usunięcia, należy przekazać czas w formacie unix time w storage_period_timeout_timestamp. Jeśli podano zarówno storage_period_timeout_value, jak i email_timeout_timestamp, priorytet będzie miał ten drugi.

  • page_id

    Kolejny numer arkusza (liczba lub ciąg), jeśli dokument zawiera kilka arkuszy. Można przekazać jeden numer ( pierwszy arkusz - 0), lub numery (oddzielone przecinkiem) arkuszy, które należy wykorzystać do tworzenia pliku.

  • result

    Określa w jakiej formie zwrócić wynik. Może przyjąć wartości:

    • Brak wartości. Zwrócony zostanie JSON-ciąg z wynikiem zapytania (patrz poniżej)
    • link. Przy pomyślnym zapytaniu zostanie zwrócony ciąg zawierający link do utworzonego pliku (jeśli w zapytaniu było tworzenie kilku plików, to link do pierwszego). Aby pobrać sam plik, należy udać się pod wskazany adres. Przygotowanie samych plików zajmuje od 1 do 5 sekund na każdy plik. Do momentu, gdy plik zostanie utworzony, zapytanie pod ten adres będzie zwracać błąd 404. Jeśli zapytanie nie przyniosło utworzenia pliku, zostanie zwrócony JSON string z błędem (patrz poniżej).
    • file. Przy pomyślnym zapytaniu zostanie zwrócony sam gotowy plik (jeśli w zapytaniu było tworzenie kilku plików, to tylko pierwszy). Ponieważ utworzenie pliku zajmuje od 1 do 5 sekund, zwrot nastąpi dopiero po utworzeniu pliku. Przy dużej liczbie zapytań do API czas utworzenia pliku może się wydłużyć. Jeśli plik nie zostanie przygotowany w ciągu 30 sekund, API zwróci błąd 404 (mimo że zapytanie ostatecznie zostanie wykonane). Jeśli spodziewana liczba zapytań do API przekracza 1 zapytanie na 5 sekund, nie zaleca się stosowania tego parametru.

Wynik

W rezultacie serwer zwróci JSON-ciąg, przyjmując następujące możliwe wartości:

  • result

    Wynik zapytania. Może przyjąć następujące wartości:
    error - błąd zapytania. Pliki nie zostały utworzone.
    success -pomyślne zapytanie o utworzenie plików. W zależności od scenariusza użycia API, można poinformować o pomyślnym utworzeniu plików lub wyświetlić formularz pobierania plików.

  • create_id

    ID generacji. Tylko przy pomyślnym wykonaniu zapytania. Może być użyteczne dla innych zapytań do API.

  • files

    Tablica zawierająca ID utworzonych plików. Tylko przy pomyślnym wykonaniu zapytania. Aby pobrać sam plik w formacie JPG, należy udać się do https://dimaker.app/getfile/{ID}/. Aby pobrać plik w formacie PDF, należy dodać do adresu pdf/. API zwraca ID pliku od razu, jednak przygotowanie samych plików zajmuje od 1 do 5 sekund na każdy plik. Do momentu, gdy plik zostanie utworzony, zapytanie do https://dimaker.app/getfile/{ID}/ będzie zwracać błąd 404.

  • url

    URL do wyświetlenia widgetu pobierania plików. Tylko przy pomyślnym wykonaniu zapytania. Należy utworzyć Iframe z podanym URL. Samo przejście do URL nie przyniesie rezultatu. Domenę strony, na której następuje pobieranie pliku, należy poprawnie wskazać w ustawieniach API.
    Tworzenie każdego pliku zajmuje 1 sekundę + kilka sekund na przetworzenie całej grupy. Zaraz po wysłaniu zapytania można otwierać Iframe z podanym URL. Jeśli tworzenie plików nie zostało jeszcze zakończone, wyświetlony zostanie odpowiedni komunikat. Gdy pliki będą gotowe, zostanie zaproponowane ich pobranie.
    Można wyświetlić widget pobierania w oknie dialogowym na stronie. W tym celu należy utworzyć Iframe z następującymi dodatkowymi stylami: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Do adresu URL należy dodać ?view=modal. I umieścić ten iframe w body.

  • error_text

    Tylko w przypadku błędu. Tekstowy opis błędu. Możliwe błędy: niepoprawny Bezpieczny tokken, maska do zamiany, ID dokumentu, ID szablonu wiadomości, ID folderu w Dysku, lub wewnętrzny błąd serwera.

Przykład danych zwracanych przy pomyślnym zapytaniu:
{
"result":"success",
"create_id":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"url":"https://embed.dimaker.app/widgets/get/927ebf68-2f55-4b20-a18c-c1171ee113db/b4caf05b-6757-4d9c-b4bc-1924a9b31796/",
"files":[
"369dc61e-40c2-46c0-81f4-e31ca8c33cc2",
"d94c6efb-0076-438b-bb84-fead9c1ae556",
"716e1081-c8ee-442b-b0b0-0681b2ed5d90"
]
}

Tworzenie kilku plików w jednym zapytaniu

W jednym zapytaniu można wysłać prośbę o utworzenie kilku plików z różnych dokumentów. Za pomocą takiego zapytania można utworzyć kilka plików, na przykład, używając szablonów w języku polskim i angielskim. Wysyłając jedno zapytanie, serwer utworzy potrzebną liczbę plików.

Aby wysłać takie zapytanie, zmienna doc_id powinna być tablicą (nazwą zmiennej jest doc_id[]). W takim przypadku w jednym zapytaniu może być kilka zmiennych doc_id[] - do tworzenia kilku plików. Inne zmienne, takie jak mail_id, email_send, folder_id również mogą być wysyłane w postaci tablic, aby każdy z plików był wysyłany określonym szablonem, o określonym czasie lub zapisany w określonym folderze. Jeśli nie ma takiej potrzeby, tablicą powinno być tylko pole doc_id.

Na przykład, konieczne jest utworzenie dwóch plików z różnych dokumentów i umieszczenie ich w różnych folderach w Dysku. W tym celu należy wysłać dwie zmienne doc_id[] i dwie zmienne folder_id[] (w tej samej kolejności). Ponadto, jeśli zadaniem jest wysyłanie ich jednym mailem, należy wskazać jedno mail_id, a w email_send[] najpierw wskazać "manual", a następnie "oncreate". W takim przypadku najpierw zostanie utworzony jeden plik, a następnie drugi. I dopiero po utworzeniu drugiego nastąpi wysyłka z podaną w mail_id wiadomością.

Wysyłanie pliku do siebie po utworzeniu

Plik zostanie wysłany na adres e-mail konta od razu po jego utworzeniu. W polu „Szablon wiadomości” można wybrać, jaki szablon użyć do wysyłki. Wcześniej w Szablonach wiadomości można utworzyć osobny szablon do wysyłki wiadomości na adres e-mail konta. Jeśli w treści wiadomości zapiszesz zmienną %data, w tym miejscu zostaną dodane wszystkie dane pliku w formie tabeli.

Usuwanie plików

Aby usunąć pliki, należy wysłać zapytania POST-DATA, POST-JSON lub GET na adres
https://dimaker.app/api/v1/drive/files/delete/
z podanymi poniżej danymi.
Kodowanie zapytania - UTF-8. Pola wymagane są oznaczone gwiazdką.

  • secure*

    Tokken (ciąg znaków, 36 znaków)

  • file_id

    ID pliku (ciąg znaków, 36 znaków), który będzie usunięty. ID pliku zwracane jest w tablicy files przy tworzeniu przez API. Plik nie powinien być w koszu.

    ALBO

  • file_ids

    Tablica ID plików (ciąg znaków, 36 znaków), które będą usunięte, jeśli wymagane jest usunięcie kilku plików w jednym zapytaniu.

    ALBO

  • creater_id

    ID generacji (ciąg znaków, 36 znaków), jeśli plik został utworzony przez API. ID generacji można przekazać zamiast file_id lub file_ids. W tym przypadku wszystkie pliki z tym ID generacji zostaną usunięte. ID generacji zwracane jest w polu create_id przy tworzeniu plików przez API.

    delete_forever

    Czy usunąć plik na stałe, bez przenoszenia do kosza. Domyślnie plik jest przenoszony do kosza. Może przyjąć wartości:

    • 0 - przenieść do kosza (domyślnie)
    • 1 - usunąć na stałe

    Pliki z kosza są usuwane automatycznie po 60 dniach od przeniesienia do kosza.

Przykład

Przykład prawidłowego zapytania o usunięcie plików:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Wynik

W rezultacie serwer zwróci JSON-ciąg, przyjmując możliwe wartości:

  • result

    Wynik zapytania. Może przyjąć następujące wartości:
    error - błąd zapytania. Pliki nie zostały usunięte.
    success -pomyślne zapytanie o usunięcie plików.

  • files

    Tablica zawierająca ID usuniętych plików. Tylko przy pomyślnym wykonaniu zapytania.

  • error_text

    Tylko w przypadku błędu. Tekstowy opis błędu. Możliwe błędy: niepoprawny Bezpieczny tokken, ID pliku, ID generacji, lub wewnętrzny błąd serwera.

Przykład danych zwracanych przy pomyślnym zapytaniu:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}


Inne integracje

Gotowy, by zacząć?

Otwórz Otwórz aplikację webową