API
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"]
}