API
Utilizzando l'API DiMaker è possibile creare file con dati personali e, se necessario, consegnarli ai destinatari. Le richieste API possono essere effettuate sia da un altro server sia dal browser attraverso richieste CORS.
Da dove iniziare
Nella sezione «Integrazione» - «Token API» è necessario ottenere un token Secure per le richieste e consentire l'utilizzo di questo token. Inoltre, è necessario creare un documento contenente variabili per i dati personali, nonché un modello di email per l'invio tramite posta elettronica e una cartella su Disco per i file pronti.
Creazione di file
Per creare file è necessario inviare richieste POST-DATA, POST-JSON o GET all'indirizzo
https://dimaker.app/api/v1/create/
con i dati indicati sotto.
La codifica della richiesta è UTF-8. I campi obbligatori sono contrassegnati da un asterisco.
-
secure*
Token (stringa, 36 caratteri)
-
doc_id*
ID del documento (stringa, 36 caratteri) utilizzato per la creazione del file. L'ID può essere ottenuto dalla barra degli indirizzi quando il documento è aperto. Il documento non deve trovarsi nel cestino, ma può essere presente in qualsiasi cartella Documenti.
-
mask*
Stringa JSON che contiene tutte le variabili per la sostituzione nel formato chiave (variabile) - valore (testo per la sostituzione). Può contenere dati per la creazione di più file (senza limitazioni sul numero).
Esempio per un file:
[{"%name": "Ivanov", "%points":"100"}]
Esempio per più file:
[{"%name": "Ivanov", "%points":"100"}, {"%name": "Petrov", "%points":"200"}, {"%name": "Sidorov", "%points":"300"}]
Per specificare indirizzi email usa %email, per indicare il nome del file usa %filename. Per inviare file creati a più indirizzi email specificali separandoli con una virgola. Lo stato di invio nel Disco viene mostrato per il primo indirizzo.
Si possono usare solo virgolette doppie come da standard. Se il valore della chiave contiene virgolette, queste devono essere escape eseguite.Per passare un'immagine in un blocco immagine puoi usare un URL diretto (http:// o https://), oppure un'immagine codificata in Base64. In questo caso la stringa deve iniziare con "data:image/".
Metodo alternativo
Se non è possibile inviare una stringa JSON, le stringhe per la sostituzione possono essere inviate come campi di richiesta. Ogni variabile per la sostituzione deve iniziare con il prefisso mask_, ad esempio mask_name e contenere il valore per la sostituzione. In questo caso nel documento verrà cercata la variabile dopo il prefisso. Ad esempio, il campo mask_name corrisponde alla variabile %name. Per indicare l'indirizzo email in questo caso usa mask_email e per il nome del file usa mask_filename. -
mail_id
ID del modello di email (stringa, 36 caratteri) per l'invio tramite posta elettronica. L'ID può essere ottenuto dalla barra degli indirizzi quando il modello è aperto. Se la variabile non viene trasmessa, l'email non sarà inviata.
-
email_send
Tempo di invio del messaggio email con il file. Può avere i seguenti valori:
onfinish - Invio di tutte le email dopo avere creato tutti i file (di default)
oncreate - Invio delle email subito dopo la creazione del file. In caso di creazione di un solo file, onfinish e oncreate sono identici.
timeout - Invio delle email dopo un intervallo di tempo. In questo caso è necessario specificare due ulteriori parametri:
email_timeout_value - valore numerico dell'intervallo di tempo dopo il quale inviare le email, un valore intero
email_timeout_unit - unità di misura dell'intervallo di tempo. Può assumere il valore "m" (minuti), "h" (ore), "d" (giorni).
Oppure, per specificare l'ora esatta di invio, devi trasmettere l'ora nel formato unix time in email_timeout_timestamp. Se vengono trasmessi sia email_timeout_value che email_timeout_timestamp, quest'ultimo ha priorità. -
folder_id
ID della cartella su Disco (stringa, 36 caratteri) dove salvare i file. Se la cartella non esiste, verrà creata automaticamente alla creazione del primo file.
-
storage_period
Periodo di conservazione dei file su Disco. Se il parametro non è specificato, i file saranno conservati indefinitamente fino alla cancellazione manuale. Per la cancellazione dopo un intervallo di tempo devi impostare il valore a:
timeout. In questo caso è necessario specificare due ulteriori parametri:
storage_period_timeout_value - valore numerico del periodo dopo il quale cancellare i file, un valore intero
storage_period_timeout_unit - unità di misura del periodo. Può avere il valore "m" (minuti), "h" (ore), "d" (giorni).
Oppure, per specificare l'ora esatta di cancellazione, è necessario trasmettere l'ora in formato unix time in storage_period_timeout_timestamp. Se vengono trasmessi sia storage_period_timeout_value sia storage_period_timeout_timestamp, quest'ultimo ha priorità. -
page_id
Numero del foglio (numero o stringa), se nel documento ci sono più fogli. Si può trasmettere un numero (primo foglio - 0), o i numeri (separati da virgola) dei fogli da utilizzare per creare il file.
-
result
Determina il formato per restituire il risultato. Può assumere i seguenti valori:
- Valore mancante. Verrà restituita una stringa JSON con il risultato della richiesta (vedi sotto)
- link. In caso di richiesta riuscita verrà restituita una stringa contenente un collegamento al file creato (se la richiesta ha creato più file, il collegamento sarà al primo). Per ottenere il file stesso bisogna accedere al collegamento indicato. La preparazione dei file richiede tempo - da 1 a 5 secondi per ogni file. Prima che il file venga creato, la richiesta su questo indirizzo restituirà un errore 404. Se la richiesta non ha portato alla creazione del file, verrà restituita una stringa JSON con un errore (vedi sotto).
- file. In caso di richiesta riuscita verrà restituito il file pronto (se la richiesta ha creato più file, solo il primo). Poiché la creazione del file richiede 1-5 secondi, il ritorno avverrà solo dopo che il file sarà pronto. Se il numero di richieste API è elevato il tempo può aumentare. Se il file non viene preparato entro 30 secondi, l'API restituirà un errore 404 (anche se in definitiva la richiesta di creazione del file verrà eseguita). Se la richiesta non ha portato alla creazione del file, verrà restituita una stringa JSON con un errore (vedi sotto). Se si prevede che le richieste API superino 1 richiesta in 5 secondi, non usare questo parametro.
Risultato
Come risultato il server restituirà una stringa JSON che può assumere i seguenti valori possibili:
-
result
Risultato della richiesta. Può assumere i seguenti valori:
error - errore nella richiesta. File non creati.
success - richiesta di creazione file riuscita. A seconda dello scenario di utilizzo dell'API puoi segnalare il successo nella creazione dei file o mostrare un modulo di ricezione dei file. -
create_id
ID di generazione. Solo in caso di richiesta riuscita. Può essere utile per altre richieste API.
-
files
Array contenente gli ID dei file creati. Solo in caso di richiesta riuscita. Per ottenere il file nel formato JPG è necessario contattare https://dimaker.app/getfile/{ID}/. Per scaricare il file PDF è necessario aggiungere pdf/ all'indirizzo. L'API restituisce l'ID del file immediatamente, tuttavia la preparazione dei file richiede tempo - da 1 a 5 secondi per ogni file. Fino alla creazione del file, la richiesta a https://dimaker.app/getfile/{ID}/ restituirà un errore 404.
-
url
URL da visualizzare nel widget di download file. Solo in caso di richiesta riuscita. È necessario creare un Iframe con l'URL indicato. Un semplice accesso all'URL non darà risultato. Il dominio del sito da cui si ottiene il file deve essere correttamente indicato nelle impostazioni API.
La creazione di ciascun file richiede 1 secondo + alcuni secondi per elaborare l'intero gruppo. Subito dopo l'invio della richiesta si può aprire l'Iframe con l'URL indicato. Se la creazione dei file non è ancora terminata, verrà mostrato un messaggio corrispondente. Non appena i file saranno pronti, verrà proposto di scaricarli.
Si può mostrare il widget di download in una finestra di dialogo sopra la pagina. Per fare ciò, è necessario creare un Iframe con i seguenti stili aggiuntivi: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Alla stringa dell'indirizzo è necessario aggiungere ?view=modal. E posizionare questo iframe nel body. -
error_text
Solo in caso di errore. Descrizione testuale dell'errore. Possibili errori: Secure token errato, maschera per la sostituzione, ID documento, ID modello di email, ID cartella su Disco, oppure errore interno del server.
Esempio di dati restituiti in caso di richiesta riuscita:
{
"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"
]
}
Creazione di più file in una singola richiesta
In una singola richiesta è possibile inviare la richiesta per la creazione di più file da documenti diversi. Con una simile richiesta è possibile creare diversi file, ad esempio usando modelli in lingua russa e inglese. Inviando una richiesta unica, il server creerà il numero di file necessario.
Per inviare tale richiesta, la variabile doc_id deve essere un array (nome della variabile - doc_id[]). In questo caso in una singola richiesta possono essere presenti più variabili doc_id[] per creare più file. Altre variabili come mail_id, email_send, folder_id possono essere inviate anche come array, affinché ciascun file venga inviato con un modello specifico, a un'ora specifica o salvato in una cartella specifica. Se non necessario, deve essere un array solo il campo doc_id.
Ad esempio, per creare due file da documenti diversi e salvarli in cartelle diverse su Disco, è necessario inviare due variabili doc_id[] e due variabili folder_id[] (nello stesso ordine). Inoltre, se il file deve essere inviato con una singola email, è necessario indicare un unico mail_id, ed in email_send[] indicare prima "manual" poi "oncreate". In questo caso uno dei file verrà creato, seguito dal secondo. Solo dopo la creazione del secondo file l'invio verrà eseguito con l'email indicato in mail_id.
Inviare a te stesso il file dopo la creazione
Il file verrà inviato all'email dell'account non appena sarà creato. Nel campo «Modello di email» si può scegliere quale modello usare per l'invio. Prima di tutto, in Modelli di Email si può creare un modello separato per inviare email all'email dell'account. Se nel testo del messaggio si inserisce la variabile %data, tutti i dati del file saranno aggiunti in formato tabellare.
Cancellazione dei file
Per cancellare i file è necessario inviare richieste POST-DATA, POST-JSON o GET all'indirizzo
https://dimaker.app/api/v1/drive/files/delete/
con i dati indicati sotto.
La codifica della richiesta è UTF-8. I campi obbligatori sono contrassegnati da un asterisco.
-
secure*
Token (stringa, 36 caratteri)
-
file_id
ID del file (stringa, 36 caratteri) che verrà eliminato. L'ID del file viene restituito nell'array files durante la creazione tramite API. Il file non deve essere nel cestino.
O
-
file_ids
Array di ID file (stringa, 36 caratteri) che verranno eliminati, se necessario eliminare più file in una singola richiesta.
O
creater_id
ID di generazione (stringa, 36 caratteri), se il file è stato creato tramite API. L'ID di generazione può essere trasmesso in sostituzione di file_id o file_ids. In questo caso verranno eliminati tutti i file con questo ID di generazione. L'ID di generazione viene restituito nel campo create_id durante la creazione dei file tramite API.
delete_forever
Se cancellare definitivamente il file, senza spostarlo nel cestino. Di default il file è spostato nel cestino. Può assumere i valori:
- 0 - spostare nel cestino (di default)
- 1 - cancellare definitivamente
I file nel cestino vengono eliminati automaticamente 60 giorni dopo essere stati spostati nel cestino.
Esempio
Esempio di corretta richiesta di cancellazione file:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}
Risultato
Come risultato il server restituirà una stringa JSON che può assumere i seguenti valori possibili:
-
result
Risultato della richiesta. Può assumere i seguenti valori:
error - errore nella richiesta. File non cancellati.
success - richiesta di cancellazione file riuscita. -
files
Array contenente gli ID dei file cancellati. Solo in caso di richiesta riuscita.
-
error_text
Solo in caso di errore. Descrizione testuale dell'errore. Possibili errori: Secure token errato, ID file, ID di generazione, oppure errore interno del server.
Esempio di dati restituiti in caso di richiesta riuscita:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}