API
Utilizando la API de DiMaker, puede crear archivos con datos personales y, si es necesario, entregarlos a los destinatarios. Las solicitudes a la API pueden realizarse tanto desde otro servidor como desde un navegador mediante solicitudes CORS.
Cómo comenzar
En la sección "Integración" - "Tokens API", debe obtener un token seguro para las solicitudes y permitir el uso de este token. Además, es necesario crear un documento que contenga variables para los datos personales, así como una plantilla de correo electrónico para envíos por correo electrónico y una carpeta en el Disco para los archivos generados.
Creación de archivos
Para crear archivos, es necesario enviar solicitudes POST-DATA, POST-JSON o GET a la dirección
https://dimaker.app/api/v1/create/
con los datos indicados a continuación.
Codificación de la solicitud - UTF-8. Los campos obligatorios están marcados con un asterisco.
-
secure*
Token (cadena de 36 caracteres)
-
doc_id*
ID del documento (cadena de 36 caracteres) que se utilizará para crear el archivo. Se puede obtener el ID en la barra de direcciones cuando el documento está abierto. El documento no debe estar en la papelera, pero puede estar en cualquier carpeta de Documentos.
-
mask*
Cadena JSON que contiene todas las variables a reemplazar en forma de clave (variable) - valor (texto de reemplazo). Puede contener datos para crear varios archivos (sin límite en la cantidad).
Ejemplo para un archivo:
[{"%name": "Ivánov", "%puntos":"100"}]
Ejemplo para varios archivos:
[{"%name": "Ivánov", "%puntos":"100"}, {"%name": "Petrov", "%puntos":"200"}, {"%name": "Sidorov", "%puntos":"300"}]
Para especificar una dirección de correo electrónico, debe usar %email, para el nombre del archivo - %filename. Para enviar los archivos creados a varias direcciones de correo electrónico, deben indicarse separadas por comas. El estado de envío al Disco se mostrará por la primera dirección.
Deben utilizarse comillas dobles de acuerdo con el estándar. Si el valor de la clave contiene comillas, deben ser escapadas.Para enviar una imagen en un bloque de imágenes, puede utilizarse un enlace directo (http:// o https://) o una imagen codificada en Base64. En el segundo caso, la cadena debe comenzar con "data:image/".
Método alternativo
Si no es posible enviar una cadena JSON, las cadenas de reemplazo se pueden enviar como campos de la solicitud. Cada variable de reemplazo debe comenzar con el prefijo mask_, por ejemplo, mask_name y contener el valor de reemplazo. En este caso, en el documento se buscará la variable después del prefijo. Por ejemplo, al campo mask_name le corresponde la variable %name. Para especificar una dirección de correo electrónico en este caso debe utilizarse mask_email, y para el nombre del archivo - mask_filename. -
mail_id
ID de la plantilla de correo (cadena de 36 caracteres) para el envío por correo electrónico. Se puede obtener el ID en la barra de direcciones cuando la plantilla está abierta. Si la variable no se transmite, no se enviará el correo.
-
email_send
Hora de envío del correo con el archivo. Puede tomar los siguientes valores:
onfinish - Enviar todos los correos después de crear todos los archivos (por defecto)
oncreate - Enviar correos inmediatamente después de crear el archivo. Al crear un solo archivo, onfinish y oncreate son idénticos.
timeout - Enviar correos después de un intervalo de tiempo. En este caso, es necesario proporcionar dos parámetros adicionales:
email_timeout_value - valor numérico del intervalo después del cual enviar correos, valor entero
email_timeout_unit - unidad de medida del intervalo. Puede tomar el valor "m" (minutos), "h" (horas), "d" (días).
Alternativamente, para indicar la hora exacta de envío, debe pasar el tiempo en formato unix time en email_timeout_timestamp. Si se transmiten email_timeout_value y email_timeout_timestamp, la última tendrá prioridad. -
folder_id
ID de la carpeta en el Disco (cadena de 36 caracteres) para guardar los archivos. Si la carpeta no existe, se creará automáticamente al crear el primer archivo.
-
storage_period
Tiempo de almacenamiento de archivos en el Disco. Si no se especifica este parámetro, los archivos se almacenan indefinidamente hasta su eliminación manual. Para eliminar después de un intervalo de tiempo debe tomar el valor:
timeout. En este caso, es necesario proporcionar dos parámetros adicionales:
storage_period_timeout_value - valor numérico del intervalo después del cual eliminar los archivos, valor entero
storage_period_timeout_unit - unidad de medida del intervalo. Puede tomar el valor "m" (minutos), "h" (horas), "d" (días).
Alternativamente, para indicar la hora exacta de eliminación, debe pasar el tiempo en formato unix time en storage_period_timeout_timestamp. Si se transmiten storage_period_timeout_value y email_timeout_timestamp, la última tendrá prioridad. -
page_id
Número de página (número o cadena), si el documento tiene varias páginas. Puede pasar un solo número (primera página - 0), o números (separados por comas) de las páginas que se deben usar para crear el archivo.
-
result
Determina el formato en que se devolverá el resultado. Puede tomar los siguientes valores:
- Sin valor. Se devolverá una cadena JSON con el resultado de la solicitud (ver más abajo)
- link. En caso de una solicitud exitosa, se devolverá una cadena que contiene un enlace al archivo creado (si en la solicitud se crearon varios archivos, el enlace al primero). Para obtener el archivo en sí, debe acceder al enlace proporcionado. La preparación de los archivos en sí lleva tiempo, de 1 a 5 segundos por archivo. Hasta que el archivo esté creado, la solicitud a esta dirección devolverá un error 404. Si la solicitud no resultó en la creación del archivo, se devolverá una cadena JSON con el error (ver más abajo).
- file. En caso de una solicitud exitosa, se devolverá el archivo listo (si en la solicitud se crearon varios archivos, solo el primero). Como la creación del archivo tarda de 1 a 5 segundos, el retorno ocurrirá solo después de que el archivo esté creado. Si hay muchas solicitudes a la API, el tiempo de creación del archivo aumentará. Si el archivo no está listo en 30 segundos, la API devolverá un error 404 (aunque la solicitud de creación del archivo finalmente se ejecutará). Si la solicitud no resultó en la creación del archivo, se devolverá una cadena JSON con el error (ver más abajo). Si se espera que haya más de 1 solicitud a la API cada 5 segundos, no se debe usar este parámetro.
Resultado
El servidor devolverá una cadena JSON, con los siguientes posibles valores:
-
result
Resultado de la solicitud. Puede tomar los siguientes valores:
error - error en la solicitud. No se crearon archivos.
success - solicitud exitosa para crear archivos. Dependiendo del escenario de uso de la API, se puede informar sobre la creación exitosa de archivos o mostrar un formulario para obtener los archivos. -
create_id
ID de generación. Solo en caso de ejecución exitosa de la solicitud. Puede ser útil para otras solicitudes a la API.
-
files
Matriz que contiene los ID de los archivos creados. Solo en caso de ejecución exitosa de la solicitud. Para obtener el archivo en formato JPG, es necesario acceder a https://dimaker.app/getfile/{ID}/. Para descargar el archivo PDF, debe agregar pdf/ a la dirección. La API devuelve el ID del archivo de inmediato, sin embargo, la preparación de los archivos en sí lleva tiempo - de 1 a 5 segundos por cada archivo. Hasta que el archivo esté creado, la solicitud a https://dimaker.app/getfile/{ID}/ devolverá un error 404.
-
url
URL para mostrar el widget de descarga de archivos. Solo en caso de ejecución exitosa de la solicitud. Es necesario crear un Iframe con la URL proporcionada. Simplemente acceder a la URL no dará resultado. El dominio del sitio web donde se obtiene el archivo debe estar correctamente especificado en las configuraciones de la API.
La creación de cada archivo toma 1 segundo + varios segundos para procesar todo el grupo. Inmediatamente después de enviar la solicitud, se puede abrir el Iframe con las URL proporcionadas. Si la creación de archivos aún no ha finalizado, se mostrará un mensaje correspondiente. Tan pronto como los archivos estén listos, se ofrecerá la opción de descargarlos.
Se puede mostrar el widget de descarga en una ventana de diálogo sobre la página. Para ello, se debe crear un Iframe con los siguientes estilos adicionales: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Se debe agregar ?view=modal a la barra de direcciones. Y colocar este iframe en el cuerpo. -
error_text
Solo en caso de error. Descripción del error. Posibles errores: token seguro incorrecto, máscara de reemplazo, ID de documento, ID de plantilla de correo, ID de carpeta en el Disco, o error interno del servidor.
Ejemplo de datos devueltos en una solicitud exitosa:
{
"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"
]
}
Creación de varios archivos en una sola solicitud
En una sola solicitud se puede enviar una petición para crear varios archivos desde diferentes documentos. Con este tipo de solicitud, se pueden crear varios archivos, por ejemplo, utilizando plantillas en ruso e inglés. Al enviar una sola solicitud, el servidor creará el número necesario de archivos.
Para enviar este tipo de solicitud, la variable doc_id debe ser una matriz (nombre de la variable - doc_id[]). En este caso, en una sola solicitud se pueden tener varias variables doc_id[] - para crear varios archivos. Otras variables, como mail_id, email_send, folder_id también se pueden enviar en forma de matrices, para que cada archivo sea enviado con una plantilla específica, en un momento específico, o guardado en una carpeta específica. Si no es necesario, el único campo que debe ser una matriz es doc_id.
Por ejemplo, es necesario crear dos archivos de diferentes documentos y colocarlos en diferentes carpetas en el Disco. Para ello se deben enviar dos variables doc_id[] y dos variables folder_id[] (en el mismo orden). Además, si el objetivo es enviarlos en un solo correo, se debe especificar un mail_id, y en email_send[] primero indicar "manual", y luego "oncreate". En este caso primero se creará un archivo, luego el segundo. Y solo después de crear el segundo se enviará con el correo indicado en mail_id.
Enviarse el archivo después de su creación
El archivo se enviará al correo electrónico de la cuenta inmediatamente después de su creación. En el campo "Plantilla de correo" se puede elegir qué plantilla usar para el envío. Previamente, en Plantillas de correos se puede crear una plantilla separada para el envío de correos al correo electrónico de la cuenta. Si en el texto del correo se escribe la variable %data, en este lugar se agregarán todos los datos del archivo en forma de tabla.
Eliminación de archivos
Para eliminar archivos, es necesario enviar solicitudes POST-DATA, POST-JSON o GET a la dirección
https://dimaker.app/api/v1/drive/files/delete/
con los datos indicados a continuación.
Codificación de la solicitud - UTF-8. Los campos obligatorios están marcados con un asterisco.
-
secure*
Token (cadena de 36 caracteres)
-
file_id
ID del archivo (cadena de 36 caracteres), que se eliminará. El ID del archivo se devuelve en la matriz de archivos al crearlo a través de la API. El archivo no debe estar en la papelera.
O
-
file_ids
Matriz de ID de archivos (cadena de 36 caracteres) que se eliminarán si se requieren eliminar varios archivos en una sola solicitud.
O
creater_id
ID de generación (cadena de 36 caracteres), si el archivo fue creado a través de la API. El ID de generación se puede pasar en lugar de file_id o file_ids. En este caso, se eliminarán todos los archivos con este ID de generación. El ID de generación se devuelve en el campo create_id al crear archivos a través de la API.
delete_forever
Si se debe eliminar el archivo definitivamente, sin moverlo a la papelera. Por defecto, el archivo se traslada a la papelera. Puede tomar los siguientes valores:
- 0 - mover a la papelera (por defecto)
- 1 - eliminar definitivamente
Los archivos de la papelera se eliminan automáticamente 60 días después de moverse a la papelera.
Ejemplo
Ejemplo de una solicitud correcta para eliminar archivos:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}
Resultado
El servidor devolverá una cadena JSON, con los siguientes posibles valores:
-
result
Resultado de la solicitud. Puede tomar los siguientes valores:
error - error en la solicitud. No se eliminaron archivos.
success - solicitud exitosa para la eliminación de archivos. -
files
Matriz que contiene los ID de los archivos eliminados. Solo en caso de ejecución exitosa de la solicitud.
-
error_text
Solo en caso de error. Descripción del error. Posibles errores: token seguro incorrecto, ID de archivo, ID de generación, o error interno del servidor.
Ejemplo de datos devueltos en una solicitud exitosa:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}