Skip to content

Batch mode of Smartlink generation

The main purpose of this mode is to generate thousands of smartlinks at a time.

In the Batch mode, Smartlink Creator gets one master smartlink and generates smartlinks like a master one but with other PDFs and parametrised assets.

Smartlink creation strategies

Strategy Description
smallest (default) Smartlink contains links to JS scripts and PDF file
mixed A part of the JS scripts will be placed inside of the Smartlink
original All the JS scripts and PDF file will be placed inside of the Smartlink

To start files generation, customer calls POST /api/batch/<batch_id>/start (multipart/form-data request) with following parameters:

Parameter Required? Description
batch_id yes Unique Batch ID. Used as folder name in the File Storage bucket for generated smartlinks. Symbols allowed:
api_url no* Path to the ARGOflow API to get information about smartlink provided in template_id parameter. Required if template_id is provided.
document_id no* Smartlink ID of template to be used for batch generation. Required if document_file is not provided
document_file no Template file (smartlink's JSON) to be used for batch. To get this JSON you can use a call like
data no JSON with parameters for replacements in a template. See data JSON example below
data_file no JSON file with parameters for replacements in a template. See data JSON example below
max_errors no Max amount of errors allowed before cancelling a batch
callback_emails no Comma-separated list of email to be informed once batch is finished
callback_url no Customer's callback URL. It will be used to inform customer about batch job status
strategy no Creation strategy. Can be "smallest" (default), "mixed", "original"

API responds with a job details. E.g.:

    "batch_id": "my-first-batch",
    "job_id": "e5c5daefbadfff523f5e1f4b7e60eab8",
    "status": "In progress",
    "started": "2021-06-25T13:13:10.477Z",
    "finished": null,
    "succeededCount": 0,
    "erroredCount": 0

Data (or data_file) example:

    "pdf": "",
    "reference_id": "5ef3501829bf41003d6da7b4",
    "suffix": "5f1ea1e9b982f900468aeb5b",
    "data": {
      "num_client": "240 000 009 425",
      "montant": "500",
      "date": "2020-10-11"
    "pdf": "",
    "reference_id": "5ef3501829bf41003d612345",
    "suffix": "5f1ea1e9b982f900468aeb77",
    "data": {
      "num_client": "240 000 009 738",
      "montant": "414,97",
      "date": "2021-01-12"
In the data file, pdf is a link to PDF file that will be augmented.\ reference_id is the client's unique document id.\ suffix is the unique sentence to be used for generated file name which will be like /<batch_id>/<reference_id>.<suffix>.html.\ data is the set of parameters that will be used for substitution in the template.

Generated files naming scheme

To be able to provide smartlinks directly from the storage (using NGINX as reverse proxy) we need to easily get smartlink's filename from the smartlink URL. Hackers can guess reference id and hence have a link to users data. To make this more difficult, we can add a second unique sentence (suffix) to be added to the smartlink file name. So link to the smartlink will looks like:<batch_id>/5ef3501829bf41003d6da7b4.5f1ea1e9b982f900468aeb5b.html
And file name will be

5ef3501829bf41003d6da7b4. 5f1ea1e9b982f900468aeb5b. html
Customer's Reference ID Suffix. Unique sentence to avoid guessing Extension

Other batch generation related calls:

Method Call Description
GET /api/batch/<batch_id>/<job_id>/cancel Cancel job
GET /api/batch/<batch_id>/<job_id>/status Get job's status
GET /api/batch/<batch_id>/<job_id>/log Get job's log