API
Usando la API DiMaker se pueden crear archivos con datos personales y enviarlos a los destinatarios según sea necesario. Las solicitudes a la API pueden venir de otro servidor o desde un navegador a través de solicitudes Cross-Origin Resource Sharing (CORS).
Por dónde empezar
En la sección "Integración" - "Tokens de API" es necesario obtener un token seguro para las solicitudes y autorizar su uso. Además, es necesario crear un documento que contenga variables para los datos personales, un modelo de correo electrónico para los envíos por correo electrónico y una carpeta en el Drive para los archivos preparados.
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 especificados abajo.
La codificación de la solicitud es 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. El ID se puede obtener en la barra de direcciones cuando el documento está abierto. El documento no debe estar en la papelera, pero puede estar en cualquier carpeta en Documentos.
-
mask*
Cadena JSON que contiene todas las variables a ser reemplazadas en forma de clave (variable) - valor (texto a reemplazar). Puede contener datos para crear varios archivos (sin límites en cantidad).
Ejemplo para un archivo:
[{"%nombre": "Ivanov", "%puntos":"100"}]
Ejemplo para varios archivos:
[{"%nombre": "Ivanov", "%puntos":"100"}, {"%nombre": "Petrov", "%puntos":"200"}, {"%nombre": "Sidorov", "%puntos":"300"}]
Para indicar la dirección de correo electrónico, se debe usar %email, y para el nombre del archivo - %nombreArchivo. Para enviar los archivos creados a múltiples direcciones de correo electrónico, se deben especificar separadas por comas. El estado de envío en el Drive se mostrará para la primera dirección.
Solo se pueden usar 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 imagen, se puede usar 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, los valores para reemplazar se pueden enviar como campos de la solicitud. Cada variable de reemplazo debe comenzar con el prefijo mask_, por ejemplo mask_nombre y contener el valor a reemplazar. En el documento se buscará la variable después del prefijo. Por ejemplo, el campo mask_nombre corresponde a la variable %nombre. Para indicar la dirección de correo electrónico en este caso, se debe usar mask_email, y el nombre del archivo - mask_nombreArchivo. -
mail_id
ID del modelo de correo electrónico (cadena de 36 caracteres) para enviar por correo electrónico. El ID se puede obtener en la barra de direcciones cuando el modelo está abierto. Si la variable no se envía, entonces no se enviará el correo.
-
email_send
Momento en el que enviar el correo con el archivo. Puede aceptar 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, se deben pasar otros dos parámetros:
email_timeout_value - valor numérico del intervalo de tiempo para enviar correos, valor entero
email_timeout_value - unidad de tiempo del intervalo de tiempo. Puede ser "m" (minutos), "h" (horas), "d" (días).
O, para especificar un tiempo de envío exacto, se debe pasar el tiempo en formato de tiempo Unix en email_timeout_timestamp. Si se pasan timeout y email_timeout_timestamp, la prioridad será el último. -
folder_id
ID de la carpeta en Drive (cadena de 36 caracteres) para guardar los archivos. Si la carpeta no existe, se creará automáticamente al crear el primer archivo.
-
page_id
Número de página (número o cadena) si el documento tiene varias páginas. Se puede pasar un solo número (primera página - 0), o los números (separados por comas) de las páginas que se deben usar para crear el archivo.
-
result
Define la forma en que se devuelve el resultado. Puede aceptar los valores:
- Valor no presente. 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 se crearon varios archivos en la solicitud, se devolverá el enlace al primero). Para obtener el archivo en sí, se debe acceder al enlace proporcionado. La preparación de los archivos reales tomará de 1 a 5 segundos por cada archivo. Hasta que el archivo esté creado, la solicitud a esta dirección devolverá un error 404. Si la solicitud no resulta en la creación del archivo, se devolverá una cadena JSON con un error (ver más abajo).
- archivo. En caso de una solicitud exitosa, se devolverá el archivo listo (si se crearon varios archivos en la solicitud, solo se devolverá el primero). Dado que la creación del archivo toma de 1 a 5 segundos, el retorno solo ocurrirá después de que el archivo esté creado. Con un gran número de solicitudes a la API, el tiempo de creación del archivo se incrementará. Si el archivo no se prepara en 30 segundos, la API devolverá un error 404 (aunque la solicitud para crear el archivo eventualmente se cumplirá). Si la solicitud no resulta en la creación del archivo, se devolverá una cadena JSON con un error (ver más abajo). Si se espera que haya más solicitudes a la API de las que se pueden hacer en 5 segundos, no se debe usar este parámetro.
Resultado
Como resultado, el servidor devolverá una cadena JSON que puede tener los siguientes valores:
-
resultado
El resultado de la solicitud. Puede tener los siguientes valores:
error - error en la solicitud. Archivos no creados.
éxito - solicitud exitosa para la creación de archivos. Dependiendo del escenario de uso de la API, se puede informar sobre la correcta creación de archivos o mostrar un formulario para recibir los archivos. -
create_id
ID de creación. Solo en caso de ejecución exitosa de la solicitud. Puede ser útil para otras solicitudes a la API.
-
archivos
Una 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, debe visitar https://dimaker.app/getfile/{ID}/. Para descargar un archivo PDF, debe agregar pdf/ a la dirección. La API devuelve el ID del archivo de inmediato, pero se requiere tiempo para preparar los archivos reales, de 1 a 5 segundos por cada archivo. Antes de que el archivo esté listo, al visitar https://dimaker.app/getfile/{ID}/ se devolverá un error 404.
-
url
URL para mostrar el widget de descarga de archivos. Solo en caso de ejecución exitosa de la solicitud. Debe crear un Iframe con la URL especificada. Simplemente visitar la URL no dará resultados. El dominio del sitio desde el que se está obteniendo el archivo debe estar correctamente configurado en la configuración de la API.
La creación de cada archivo lleva un segundo + algunos segundos para procesar todo el grupo. Justo después de enviar la solicitud, puede abrir el Iframe con la URL proporcionada. Si los archivos aún no están listos, se mostrará un mensaje correspondiente. Una vez que los archivos estén listos, se ofrecerá la descarga de los mismos.
Puede mostrar el widget de descarga en una ventana emergente sobre la página. Para esto, 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%); Debe agregar ?view=modal a la URL y colocar este Iframe en el body. -
error_text
Solo en caso de error. Descripción textual del error. Posibles errores: token de seguridad incorrecto, máscara para reemplazar, ID del documento, ID de la plantilla de carta, ID de la carpeta en Drive, o error interno del servidor.
Ejemplo de los datos devueltos en caso de 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 solicitud
En una sola solicitud se pueden enviar varias solicitudes para crear varios archivos desde diferentes documentos. Con esta solicitud se pueden crear varios archivos, por ejemplo, utilizando plantillas en ruso e inglés. Al enviar una solicitud, el servidor creará la cantidad necesaria de archivos.
Para enviar esta solicitud, la variable doc_id debe ser un array (nombre de la variable: doc_id[]). En este caso, en una sola solicitud puede haber varias variables doc_id[] - para crear varios archivos. Otras variables, como mail_id, email_send, folder_id también pueden enviarse como arrays para que cada archivo sea enviado con una determinada plantilla, en un momento determinado o guardado en una carpeta específica. Si esto no es necesario, solo el campo doc_id debe ser un array.
Por ejemplo, si necesita crear dos archivos a partir de diferentes documentos y colocarlos en diferentes carpetas en el Drive. Para ello, es necesario enviar dos variables doc_id[] y dos variables folder_id[] (en el mismo orden). Además, si la tarea es enviarlos en un solo correo electrónico, 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 la creación del segundo, se enviará el correo especificado en mail_id.
Enviar el archivo a sí mismo después de ser creado
El archivo será enviado por correo electrónico a la cuenta tan pronto como sea creado. En el campo "Plantilla de correo electrónico" se puede elegir qué plantilla utilizar para enviar. Previamente en Plantillas de correo se puede crear una plantilla separada para enviar correos electrónicos a la cuenta de correo. Si se escribe la variable %data en el texto del correo, todos los datos del archivo se agregarán en forma de tabla en ese lugar.
Eliminación de archivos
Para eliminar archivos se debe enviar POST-DATA, POST-JSON o GET solicitudes a la dirección
https://dimaker.app/api/v1/drive/files/delete/
con los datos indicados a continuación.
La codificación de la solicitud es 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 el array files al crear mediante API. El archivo no debe estar en la papelera.
O
-
file_ids
Array de IDs de archivos (cadena de 36 caracteres) que se eliminarán, si se requiere eliminar varios archivos en una sola solicitud.
O
creater_id
ID de creación (cadena de 36 caracteres), si el archivo fue creado a través de la API. Se puede pasar el ID de creación en lugar de file_id o file_ids. En este caso, se eliminarán todos los archivos con este ID de creación. El ID de creación se devuelve en el campo create_id al crear archivos mediante la API.
delete_forever
¿Eliminar el archivo de forma permanente, sin enviarlo a la papelera? Por defecto, el archivo se envía a la papelera. Puede tomar los siguientes valores:
- 0 - enviar a la papelera (por defecto)
- 1 - eliminar de forma permanente
Los archivos de la papelera se eliminan automáticamente después de 60 días de ser enviados a la papelera.
Ejemplo
Ejemplo de solicitud correcta para eliminar archivos:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}
Resultado
Como resultado, el servidor devolverá una cadena JSON que puede contener los siguientes valores posibles:
-
resultado
El resultado de la solicitud. Puede tener los siguientes valores:
error - solicitud fallida. Los archivos no se eliminaron.
success - solicitud de eliminación de archivos exitosa. -
archivos
Una matriz que contiene los ID de los archivos eliminados. Solo se muestra en caso de una solicitud exitosa.
-
texto_error
Solo en caso de error. Descripción textual del error. Posibles errores: token Secure incorrecto, ID de archivo incorrecto, ID de generación incorrecto, o error interno del servidor.
Ejemplo de datos devueltos en caso de una solicitud exitosa:
{
"resultado":"success",
"archivos":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}