 API

Con la API de DiMaker se pueden generar archivos con datos personalizados y, si es necesario, enviarlos a los destinatarios. Las solicitudes a la API pueden realizarse tanto desde otro servidor como desde un navegador mediante solicitudes CORS.

Cómo empezar

En la sección «Integraciones» - «Tokens API» debes obtener un token seguro (Secure token) para las solicitudes y permitir su uso. Además, es necesario crear un documento que contenga variables para los datos personalizados, configurar una plantilla de correo electrónico para los envíos y definir una carpeta en el Disco para los archivos generados.

Creación de archivos

Para generar archivos se debe enviar una solicitud POST-DATA, POST- o GET a la siguiente dirección:
https://dimaker.app/api/v1/create/
con los datos detallados a continuación.
La codificación de la solicitud debe ser UTF-8. Los campos obligatorios están marcados con un asterisco (*).

• secure*

  Token (cadena de caracteres de 36 símbolos).

• doc_id*

  ID del documento (cadena de caracteres de 36 símbolos) que se utilizará para generar el archivo. El ID se obtiene en la barra de direcciones al abrir el documento. El documento no debe estar en la papelera, pero puede estar ubicado en cualquier carpeta de Documentos.

• mask*

  Cadena que contiene todas las variables y sus valores de reemplazo en formato clave - valor (texto a reemplazar). Puede incluir datos para generar múltiples archivos (sin límite en número).
  Ejemplo para un archivo:
  [{"%name": "García", "%puntos":"100"}]
  Ejemplo para varios archivos:
  [{"%name": "García", "%puntos":"100"}, {"%name": "Martínez", "%puntos":"200"}, {"%name": "López", "%puntos":"300"}]
  Para especificar direcciones de correo electrónico usa %email, y para nombres de archivo utiliza %filename. Si deseas enviar archivos a varios destinatarios por correo electrónico, deben ser enumerados separados por comas. En ese caso, el estado del envío aparecerá en Disco según la primera dirección.
  Solo se admiten comillas dobles según el estándar. Si el valor contiene comillas, estas deben ser escapadas.

  Para cargar imágenes en bloques de imagen, se puede usar ya sea 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 , los valores de reemplazo se pueden enviar como campos separados en la solicitud. Cada variable debe llevar el prefijo mask_, por ejemplo, mask_name, con el valor correspondiente. Así, una variable llamada mask_name en el campo de envío corresponderá a %name en el documento. Para correos electrónicos, utiliza mask_email; y para los nombres de archivos, usa mask_filename.

• mail_id

  ID de la plantilla de correo electrónico (cadena de caracteres de 36 símbolos). El ID se obtiene en la barra de direcciones al abrir la plantilla. Si no se especifica esta variable, no se enviará ningún correo electrónico.

• email_send

  Determina cuándo enviar el correo con el archivo adjunto. Puede tomar los siguientes valores:
  onfinish - Enviar todos los correos tras la generación de todos los archivos (por defecto).
  oncreate - Enviar los correos inmediatamente tras la creación de cada archivo. Para un único archivo, onfinish y oncreate son equivalentes.
  timeout - Enviar correos tras un intervalo de tiempo. En este caso, es necesario indicar dos parámetros adicionales:
  email_timeout_value - valor numérico del intervalo de tiempo tras el cual enviar los correos, un número entero.
  email_timeout_unit - unidad de tiempo del intervalo. Puede ser "m" (minutos), "h" (horas) o "d" (días).
  Alternativamente, para especificar un tiempo exacto de envío, usa el formato Unix Time en email_timeout_timestamp. Si se indican tanto timeout como email_timeout_timestamp, tendrá prioridad el último.

• folder_id

  ID de la carpeta en el Disco (cadena de caracteres de 36 símbolos) donde se guardarán los archivos. Si la carpeta no existe, se creará automáticamente al generarse el primer archivo.

• page_id

  Número de página (valor numérico o cadena de caracteres). Si el documento tiene varias páginas, se puede indicar un único número (primera página - 0) o varios números separados por comas.

• result

  Determina en qué formato se devolverá el resultado. Las opciones son:

  • Sin valor. Se devolverá una cadena con los resultados de la solicitud (detallados más adelante).
  • link. En caso de éxito, se devolverá un enlace al archivo generado (o al primer archivo si la solicitud incluye múltiples generaciones). El archivo estará disponible tras un tiempo (1-5 segundos por archivo). Si el enlace se accede antes, devolverá un error 404 hasta que el archivo esté listo. Si la solicitud no genera un archivo, se devolverá un con el error.
  • file. En caso de éxito se devolverá el archivo generado directamente (solo el primero si se generaron varios). Como los archivos toman tiempo en generarse, el resultado demorará hasta que el archivo esté listo. Si no se genera en menos de 30 segundos, se devolverá un error 404. Este parámetro no es recomendado si hay más solicitudes concurrentes de 1 por cada 5 segundos debido a tiempo de espera.

Resultado

El servidor devolverá una cadena con los siguientes valores posibles:

• result

  El estado de la solicitud. Puede ser: error - Error en la solicitud. No se han creado archivos.
  success - Éxito en la generación de archivos. Dependiendo del caso de uso del API, puedes notificar que los archivos han sido creados o mostrar un formulario para descargarlos.

• create_id

  ID de la generación. Solo se incluye en caso de éxito en la solicitud. Este ID es útil para otras solicitudes al API.

• files

  Array de ID que representan los archivos generados. Solo en caso de éxito. Para obtener un archivo específico en formato JPG accede a https://dimaker.app/getfile/{ID}/. Para descargar el archivo en PDF, añade pdf/ al enlace. Aunque el ID del archivo está disponible de inmediato, su generación puede tardar entre 1 y 5 segundos por archivo. Si se accede antes de que el archivo esté listo, se dará un error 404.

• url

  Enlace a un widget para descargar archivos. Solo en caso de éxito. Para usar este URL se debe crear un iframe y añadirlo al sitio. Acceder directamente al URL no funcionará. El dominio del sitio donde se recibe el archivo debe estar configurado correctamente en los ajustes del API.
  La creación de cada archivo toma 1 segundo más unos segundos adicionales para procesar el grupo completo. Puedes abrir el iframe inmediatamente tras enviar la solicitud; si los archivos aún no están listos, el mensaje correspondiente se mostrará en el widget, y cuando estén disponibles se ofrecerá a los usuarios descargarlos.
  Se recomienda usar un estilo modal para el iframe: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Añade ?view=modal al URL y coloca el iframe en el elemento "body".

• error_text

  Solo en caso de error. Contiene una descripción del problema. Los errores comunes incluyen el uso de un token Secure inválido, máscaras de sustitución incorrectas, o IDs inválidos para el documento, plantilla de correo o carpeta en el Disco.

Ejemplo de respuesta en caso de 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"
]
}

Generar múltiples archivos en una solicitud

Es posible enviar una solicitud a la API para crear múltiples archivos desde diferentes documentos. Esto permite generar archivos, por ejemplo, en diferentes idiomas, enviando una sola solicitud. El servidor procesará todos los archivos necesarios según los detalles dados.

Otras integraciones