 API

Usando a API DiMaker, você pode criar arquivos com dados pessoais e, se necessário, disponibilizá-los para os destinatários. As solicitações para a API podem acontecer tanto de outro servidor quanto do navegador, através de solicitações CORS.

Por onde começar

Na seção "Integração" - "Tokens API", você deve obter um Secure token para as solicitações e permitir o uso deste token. Além disso, é necessário criar um documento que contenha variáveis para dados pessoais, bem como um modelo de e-mail para envio e uma pasta no Disco para os arquivos prontos.

Criação de arquivos

Para criar arquivos, você precisa enviar solicitações POST-DATA, POST-JSON ou GET para o endereço
https://dimaker.app/api/v1/create/
com os dados indicados abaixo.
Codificação da solicitação - UTF-8. Campos obrigatórios são marcados com um asterisco.

• secure*

  Token (string, 36 caracteres).

• doc_id*

  ID do documento (string, 36 caracteres) que será usado para criar o arquivo. O ID pode ser obtido na barra de endereço quando o documento está aberto. O documento não deve estar na lixeira, mas pode estar em qualquer pasta de Documentos.

• mask*

  String JSON contendo todas as variáveis para substituição no formato "chave (variável) - valor (texto para substituição)". Pode conter dados para criar vários arquivos (sem restrições de quantidade).
  Exemplo para um arquivo:
  [{"%name": "Ivanov", "%balos":"100"}]
  Exemplo para vários arquivos:
  [{"%name": "Ivanov", "%balos":"100"}, {"%name": "Petrov", "%balos":"200"}, {"%name": "Sidorov", "%balos":"300"}]
  Para indicar o e-mail, use %email, para o nome do arquivo - %filename. Para enviar arquivos criados para vários e-mails, indique-os separados por vírgula. O status de envio no Disco será exibido pelo primeiro endereço.
  Apenas aspas duplas devem ser usadas conforme o padrão. Se o valor da chave contiver aspas, elas devem ser escapadas.

  Para a transferência de imagens no bloco com imagem, pode-se usar um link direto (http:// ou https://) ou uma imagem codificada em Base64. No segundo caso, a string deve começar com "data:image/".

  Método alternativo
  Se enviar uma string JSON não for possível, os strings para substituição podem ser enviados como campos da solicitação. Cada variável para substituição deve começar com o prefixo "mask_", por exemplo, mask_name e conter o valor de substituição. No documento, será feita uma busca pela variável após o prefixo. Por exemplo, o campo mask_name corresponde à variável %name. Para indicar o e-mail neste caso, use mask_email, e para o nome do arquivo - mask_filename.

• mail_id

  ID do modelo de e-mail (string, 36 caracteres) para envio por e-mail. O ID pode ser obtido na barra de endereço quando o modelo está aberto. Se esta variável não for passada, o e-mail não será enviado.

• email_send

  Tempo para enviar o e-mail com o arquivo. Pode ter os seguintes valores:
  onfinish - Enviar todos os e-mails após a criação de todos os arquivos (padrão)
  oncreate - Enviar e-mails imediatamente após a criação do arquivo. Na criação de um único arquivo, onfinish e oncreate são idênticos.
  timeout - Enviar e-mails após um intervalo de tempo. Neste caso, é necessário passar mais dois parâmetros:
  email_timeout_value - valor numérico do intervalo, em que os e-mails devem ser enviados, valor inteiro
  email_timeout_unit - unidade do intervalo de tempo. Pode ser "m" (minutos), "h" (horas), "d" (dias).
  Ou, para indicar o tempo exato de envio, passe o horário no formato unix time em email_timeout_timestamp. Caso sejam passados email_timeout_value e email_timeout_timestamp, o último terá prioridade.

• folder_id

  ID da pasta no Disco (string, 36 caracteres) para salvar os arquivos. Se a pasta não existir, será criada automaticamente na criação do primeiro arquivo.

• storage_period

  Tempo de armazenamento dos arquivos no Disco. Se o parâmetro não for especificado, os arquivos são mantidos por tempo indeterminado, até exclusão manual. Para exclusão após um período de tempo, deve-se utilizar o valor:
  timeout. Neste caso, é necessário passar mais dois parâmetros:
     storage_period_timeout_value - valor numérico do intervalo, após o qual os arquivos devem ser excluídos, valor inteiro
     storage_period_timeout_unit - unidade do intervalo de tempo. Pode ser "m" (minutos), "h" (horas), "d" (dias).
  Ou, para indicar o tempo exato de exclusão, passe o horário no formato unix time em storage_period_timeout_timestamp. Se forem passados storage_period_timeout_value e email_timeout_timestamp, o último terá prioridade.

• page_id

  Número da página (número ou string), se o documento contiver várias páginas. Pode-se passar um único número (a primeira página - 0) ou números (separados por vírgula) das páginas a serem usadas para criar o arquivo.

• result

  Determina em qual forma retornar o resultado. Pode ter os seguintes valores:

  • Sem valor. Retornará uma string JSON com o resultado da solicitação (ver abaixo)
  • link. Na solicitação bem-sucedida, retornará uma string contendo um link para o arquivo criado (se a solicitação foi a criação de vários arquivos, será o link do primeiro). Para obter o arquivo, será necessário acessar o link fornecido. A preparação dos arquivos leva tempo - de 1 a 5 segundos para cada arquivo. Antes que o arquivo seja criado, uma solicitação para este endereço retornará um erro 404. Se a solicitação não levou à criação do arquivo, será retornada uma string JSON com o erro (ver abaixo).
  • file. Na solicitação bem-sucedida, será retornado o arquivo pronto (se a solicitação foi a criação de vários arquivos, somente o primeiro). Como a criação do arquivo leva de 1 a 5 segundos, o retorno ocorrerá apenas após o arquivo ser criado. Em caso de um grande número de solicitações à API, o tempo de criação do arquivo aumenta. Se o arquivo não for preparado em 30 segundos, a API retornará erro 404 (embora a solicitação de criação do arquivo acabe sendo executada). Se a solicitação não levou à criação do arquivo, será retornada uma string JSON com o erro (ver abaixo). Se espera-se que as solicitações para a API ultrapassem 1 solicitação a cada 5 segundos, não use este parâmetro.

Resultado

Como resultado, o servidor retornará uma string JSON, aceitando os seguintes valores possíveis:

• result

  Resultado da solicitação. Pode ter os seguintes valores:
  error - erro na solicitação. Arquivos não foram criados.
  success - solicitação bem-sucedida de criação de arquivos. Dependendo do cenário de uso da API, é possível notificar sobre a criação bem-sucedida dos arquivos ou exibir um formulário de recebimento de arquivos.

• create_id

  ID de criação. Apenas na execução bem-sucedida de uma solicitação. Pode ser útil para outras solicitações à API.

• files

  Array contendo os IDs dos arquivos criados. Apenas na execução bem-sucedida de uma solicitação. Para obter o próprio arquivo em formato JPG, solicite em https://dimaker.app/getfile/{ID}/. Para baixar o arquivo PDF, adicione pdf/ ao endereço. A API retorna o ID do arquivo imediatamente, no entanto, a preparação dos arquivos leva tempo - de 1 a 5 segundos para cada arquivo. Antes que o arquivo seja criado, uma solicitação para https://dimaker.app/getfile/{ID}/ retornará um erro 404.

• url

  String URL para exibição de um widget de download de arquivos. Apenas na execução bem-sucedida de uma solicitação. É necessário criar um Iframe com o URL indicado. Simplesmente seguir o URL não trará resultados. O domínio do site onde ocorre o recebimento do arquivo deve ser corretamente indicado nas configurações da API.
  A criação de cada arquivo leva 1 segundo + alguns segundos para processar todo o grupo. Imediatamente após o envio de uma solicitação, você pode abrir o Iframe com o URL indicado. Se a criação dos arquivos ainda não estiver completa, uma mensagem correspondente será exibida. Assim que os arquivos estiverem prontos, será ofertado o download.
  É possível exibir o widget de download em uma janela de diálogo sobre a página. Para isso, deve-se criar um Iframe com os seguintes estilos adicionais: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgb(0 0 0 / 72%); Adicione à barra de endereço ?view=modal. E coloque esse iframe no body.

• error_text

  Apenas em caso de erro. Descrição textual do erro. Possíveis erros: Secure token inválido, máscara para substituição, ID do documento, ID do modelo de e-mail, ID da pasta no Disco, ou erro interno do servidor.

Exemplo de dados retornados para uma solicitação bem-sucedida:
{
"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"
]
}

Criação de vários arquivos em uma única solicitação

Em uma única solicitação, é possível requisitar a criação de vários arquivos de documentos diferentes. Com esse tipo de solicitação, pode-se criar vários arquivos, por exemplo, usando modelos em russo e inglês. Enviando uma única solicitação, o servidor criará a quantidade de arquivos necessária.

Para enviar tal solicitação, a variável doc_id deve ser um array (nome da variável - doc_id[]). Neste caso, uma única solicitação pode conter várias variáveis doc_id[] para criar vários arquivos. Outras variáveis, como mail_id, email_send, e folder_id também podem ser enviadas em forma de array para que cada arquivo seja enviado com um determinado modelo, em um tempo específico ou salvo em uma pasta específica. Se isso não for necessário, apenas o campo doc_id deve ser um array.

Por exemplo, é necessário criar dois arquivos de documentos diferentes e colocá-los em pastas diferentes no Disco. Para isso, você deve enviar duas variáveis doc_id[] e duas variáveis folder_id[] (na mesma ordem). Além disso, se a intenção é enviá-los com o mesmo e-mail, deve-se especificar um mail_id, e no email_send[] inicialmente "manual" e depois "oncreate". Assim, primeiro um arquivo será criado, depois o segundo. E somente após a criação do segundo, ocorrerá o envio com o e-mail especificado no mail_id.

Enviar arquivo para si mesmo após a criação

O arquivo será enviado para o e-mail da conta assim que for criado. No campo "Modelo de e-mail", é possível escolher qual modelo usar para o envio. Préviamente nos Modelos de E-mail, você pode criar um modelo separado para o envio de e-mails para a conta. Se no texto do e-mail for escrita a variável %data, todos os dados do arquivo serão inseridos em formato de tabela nesse local.

Exclusão de arquivos

Para excluir arquivos, você deve enviar solicitações POST-DATA, POST-JSON ou GET para o endereço
https://dimaker.app/api/v1/drive/files/delete/
com os dados indicados abaixo.
Codificação da solicitação - UTF-8. Campos obrigatórios são marcados com um asterisco.

• secure*

  Token (string, 36 caracteres).

• file_id

  ID do arquivo (string, 36 caracteres) que será excluído. O ID do arquivo é retornado no array files ao criar através da API. O arquivo não deve estar na lixeira.

  OU

• file_ids

  Array de IDs dos arquivos (string, 36 caracteres) que serão excluídos, se for necessário excluir múltiplos arquivos em uma única solicitação.

  OU

• create_id

  ID da criação (string, 36 caracteres), se o arquivo foi criado através da API. O ID da criação pode ser passado em vez de file_id ou file_ids. Nesse caso, todos os arquivos com esse ID da criação serão excluídos. O ID da criação é retornado no campo create_id ao criar arquivos através da API.

  delete_forever

  Excluir o arquivo permanentemente, sem movê-lo para a lixeira. Por padrão, o arquivo é movido para a lixeira. Pode ter os valores:

  • 0 - mover para a lixeira (padrão)
  • 1 - excluir permanentemente

  Os arquivos na lixeira são automaticamente excluídos 60 dias após o envio para a lixeira.

Exemplo

Exemplo de uma solicitação correta para exclusão de arquivos:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Resultado

Como resultado, o servidor retornará uma string JSON, aceitando os seguintes valores possíveis:

• result

  Resultado da solicitação. Pode ter os seguintes valores:
  error - erro na solicitação. Arquivos não foram excluídos.
  success - solicitação bem-sucedida de exclusão de arquivos.

• files

  Array contendo os IDs dos arquivos excluídos. Apenas na execução bem-sucedida de uma solicitação.

• error_text

  Apenas em caso de erro. Descrição textual do erro. Possíveis erros: Secure token inválido, ID do arquivo, ID de criação, ou erro interno do servidor.

Exemplo de dados retornados para uma solicitação bem-sucedida:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

Outras integrações