 API

Con l'API DiMaker è possibile generare file con dati personali e, se necessario, condividerli con i destinatari. Le richieste all'API possono essere effettuate sia da un server esterno che tramite richieste CORS dal browser.

Come iniziare

Nella sezione «Integrazione» - «Token API», è necessario ottenere un token Secure per le richieste e autorizzare l'uso di tale token. Inoltre, devi creare un documento che contenga variabili per i dati personali, un modello di email per l'invio, e una cartella nel disco per i file generati.

Creazione di file

Per creare file, è necessario inviare richieste POST-DATA, POST- o GET all'indirizzo
https://dimaker.app/api/v1/create/
con i dati indicati di seguito.
La codifica delle richieste è UTF-8. I campi obbligatori sono contrassegnati con un asterisco.

• secure*

  Token (stringa di 36 caratteri)

• doc_id*

  ID del documento (stringa di 36 caratteri) da utilizzare per la creazione del file. L'ID può essere trovato nella barra degli indirizzi quando il documento è aperto. Il documento non deve essere nel cestino, ma può essere contenuto in qualsiasi cartella nei Documenti.

• mask*

  Stringa contenente tutte le variabili da sostituire con il formato chiave (variabile) - valore (testo da sostituire). Può includere dati per la creazione di più file (senza limiti sulla quantità).
  Esempio per un file:
  [{"%name": "Rossi", "%punteggio":"100"}]
  Esempio per più file:
  [{"%name": "Rossi", "%punteggio":"100"}, {"%name": "Bianchi", "%punteggio":"200"}, {"%name": "Verdi", "%punteggio":"300"}]
  Per specificare un indirizzo email, usa %email, per il nome del file usa %filename. Per inviare file creati a più indirizzi email, separali con una virgola. Lo stato di invio nel Disco verrà visualizzato per il primo indirizzo.
  Utilizza solo doppi apici per seguire lo standard. Se il valore contiene apici, devono essere escapati.

  Per inviare immagini in un blocco immagine, puoi utilizzare un link diretto (http:// o https://) oppure un'immagine codificata in Base64. Nel secondo caso, la stringa deve iniziare con "data:image/".

  Metodo alternativo
  Se non puoi inviare una stringa , le variabili da sostituire possono essere inviate come campi della richiesta. Ogni variabile deve iniziare con il prefisso mask_, ad esempio mask_name, e contenere il valore da sostituire. Nel documento, la variabile sarà ricercata senza il prefisso. Ad esempio, al campo mask_name corrisponde la variabile %name. Per indirizzi email usa mask_email e per il nome file mask_filename.

• mail_id

  ID del modello email (stringa di 36 caratteri) per l'invio. Può essere trovato nella barra degli indirizzi quando il modello è aperto. Se non viene trasmessa, l’email non sarà inviata.

• email_send

  Orario di invio delle email con i file. Può assumere i seguenti valori:
  onfinish - Invia tutte le email dopo la creazione di tutti i file (default)
  oncreate - Invia immediatamente le email appena un file è stato creato. Per un singolo file onfinish e oncreate sono identici.
  timeout - Invia le email dopo un determinato intervallo di tempo. Servono due parametri aggiuntivi:
  email_timeout_value - valore numerico dell'intervallo di invio, intero
  email_timeout_unit - unità di misura dell'intervallo. Può essere "m" (minuti), "h" (ore), "d" (giorni).
  Oppure, per specificare un'ora precisa, devi trasmettere un valore in formato unix time in email_timeout_timestamp. Se vengono forniti sia timeout che email_timeout_timestamp, quest'ultimo avrà priorità.

• folder_id

  ID della cartella nel Disco (stringa di 36 caratteri) dove memorizzare i file. Se la cartella non esiste, verrà creata automaticamente alla prima generazione.

• page_id

  Numero della pagina (numero o stringa) se il documento contiene più pagine. Può essere specificato un numero singolo (pagina iniziale - 0) o un elenco (separati da virgole) di numeri di pagina da utilizzare per la generazione del file.

• result

  Definisce il formato del risultato restituito. Può assumere i seguenti valori:

  • Default: restituisce una stringa con il risultato della richiesta (vedi sotto)
  • link: in caso di successo, restituisce un link al file creato (nel caso di più file, al primo). Per scaricare il file bisogna accedere al link. La creazione richiede 1-5 secondi per file. Prima che un file sia completato, la richiesta genererà un errore 404. Se non è stato possibile creare il file, verrà restituita una stringa con l’errore.
  • file: in caso di successo restituisce direttamente il file (nel caso di più file, solo il primo). Poiché la creazione richiede 1-5 secondi per file, il ritorno avverrà dopo completamento. Se il file non viene generato entro 30 secondi, l’API restituirà un errore 404. Per richieste frequenti (>1 ogni 5 secondi), non utilizzare questo parametro.

Risultato

Il server restituirà una stringa con i seguenti valori:

• result

  Esito della richiesta. Può assumere i seguenti valori:
  error: errore nella richiesta, file non creati.
  success: file creati con successo. A seconda del contesto, puoi notificare l’avvenuta creazione o mostrare un modulo per il download.

• create_id

  ID generazione, restituito solo in caso di successo. Può essere utile per richieste successive all'API.

• files

  Array contenente gli ID dei file generati, restituito in caso di successo. Per scaricare un file JPG usa https://dimaker.app/getfile/{ID}/. Per il formato PDF, aggiungi pdf/. Gli ID vengono restituiti subito, ma i file richiedono 1-5 secondi per essere elaborati.

• url

  URL per il widget di download file, restituito in caso di successo. Per accedervi crea un iFrame con l'URL. La ricezione dei file è concessa solo se il dominio è stato configurato correttamente nelle impostazioni dell'API. Puoi visualizzare il widget in una finestra modale, utilizzando gli stili aggiuntivi specificati.

• error_text

  In caso di errore, fornisce una descrizione. Possibili errori: token Secure non valido, maschera variabili, ID documento, ID modello email, ID cartella nel Disco, o errore interno del server.

Esempio di risposta in caso di successo:
{
"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"
]
}

Altre integrazioni