Document API

Base URL: https://document.sls.epilot.io
Full API Docs: https://docs.epilot.io/api/document

Usage

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.document.getTemplateMeta(...)

Tree-shakeable import

import { getClient, authorize } from '@epilot/sdk/document'

const documentClient = getClient()
authorize(documentClient, () => '<token>')
const { data } = await documentClient.getTemplateMeta(...)

Operations

Documents

getTemplateMeta
generateDocumentV2
convertDocument

Schemas

S3Reference
ErrorOutput
InvalidCustomVariableErrorDetails
InvalidCustomVariableErrorDetail
InternalErrorDetails
InternalErrorDetail
DocxTemplaterErrorDetails
DocxTemplaterErrorDetail
ErrorCode
TemplateSettings
DocumentMetaRequest
DocumentMetaResponse
DocumentGenerationV2Request
DocumentGenerationV2Response
ConvertDocumentRequest
ConvertDocumentResponse

`getTemplateMeta`

Get metadata for a document template

POST /v2/documents:meta

const { data } = await client.getTemplateMeta(
  null,
  {
    template_document: {
      s3ref: {
        bucket: 'document-api-prod',
        key: 'uploads/my-template.pdf'
      }
    }
  },
)

Response

{
  "page_margins": {
    "top": 2.54,
    "bottom": 2.54,
    "left": 2.54,
    "right": 2.54,
    "header": 2.54,
    "footer": 2.54
  },
  "variables": ["order.billing_contact.0.salutation", "order.billing_contact.0.title", "order_table", "stayHardStatic", "opportunity[attribute_name]", "opportunity[\"attribute_name\"]", "opportunity.[attribute_name]", "attribute_name", "opportunities.0.attribute_name", "opportunities[0].attribute_name", "contact.opportunities[0].attribute_name", "opportunities[Primary].attribute_name"]
}

`generateDocumentV2`

Generates documents from templates with variables.

POST /v2/documents:generate

const { data } = await client.generateDocumentV2(
  {
    job_id: 'example',
    mode: 'example',
    preview_mode: 'example',
  },
  {
    template_document: {
      filename: 'my-template-{{order.order_number}}.docx',
      s3ref: {
        bucket: 'document-api-prod',
        key: 'uploads/my-template.pdf'
      }
    },
    context_entity_id: 'bcd0aab9-b544-42b0-8bfb-6d449d02eacc',
    user_id: 100321,
    language: 'de',
    variable_payload: {
      additionalProperties: 'string'
    },
    context_data: {
      additionalProperties: 'string'
    },
    template_settings: {
      custom_margins: {
        top: 2.54,
        bottom: 2.54
      },
      suggested_margins: {
        top: 2.54,
        bottom: 2.54
      },
      display_margin_guidelines: true,
      enable_data_table_margin_autofix: false,
      template_with_datatable: false,
      enabled_template_settings_persistence: false,
      misconfigured_margins: false,
      file_entity_id: '1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p'
    }
  },
)

Response

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "job_status": "STARTED",
  "message": "string",
  "ics_output": {
    "output_document": {
      "s3ref": {
        "bucket": "document-api-preview-prod",
        "key": "preview/my-appointment.ics"
      }
    }
  },
  "pdf_output": {
    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.pdf",
    "output_document": {
      "s3ref": {
        "bucket": "document-api-preview-prod",
        "key": "preview/my-template.pdf"
      }
    }
  },
  "docx_output": {
    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.docx",
    "output_document": {
      "s3ref": {
        "bucket": "document-api-preview-prod",
        "key": "preview/my-template.docx"
      }
    }
  },
  "xlsx_output": {
    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.xlsx",
    "output_document": {
      "s3ref": {
        "bucket": "document-api-preview-prod",
        "key": "preview/my-template.xlsx"
      }
    }
  },
  "error_output": {
    "error_message": "string",
    "error_code": "PARSE_ERROR",
    "error_details": [
      {
        "explanation": "string",
        "context": {
          "invalid_variables": [
            {
              "variable": "string",
              "error": "string"
            }
          ]
        }
      }
    ]
  },
  "variable_payload": {
    "additionalProperties": "string"
  },
  "template_settings": {
    "custom_margins": {
      "top": 2.54,
      "bottom": 2.54
    },
    "suggested_margins": {
      "top": 2.54,
      "bottom": 2.54
    },
    "display_margin_guidelines": true,
    "enable_data_table_margin_autofix": false,
    "template_with_datatable": false,
    "enabled_template_settings_persistence": false,
    "misconfigured_margins": false,
    "file_entity_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
  }
}

`convertDocument`

Converts a document to a different format.

POST /v2/documents:convert

const { data } = await client.convertDocument(
  null,
  {
    language: 'de',
    input_document: {
      s3ref: {
        bucket: 'document-api-prod',
        key: 'uploads/my-template.pdf'
      }
    },
    output_format: 'pdf',
    output_filename: 'converted.pdf'
  },
)

Response

{
  "output_document": {
    "preview_url": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/converted.pdf",
    "s3ref": {
      "bucket": "document-api-prod",
      "key": "uploads/my-template.pdf"
    }
  }
}

Schemas

`S3Reference`

type S3Reference = {
  bucket: string
  key: string
}

`ErrorOutput`

type ErrorOutput = {
  error_message?: string
  error_code?: "PARSE_ERROR" | "DOC_TO_PDF_CONVERT_ERROR" | "INTERNAL_ERROR" | "INVALID_TEMPLATE_FORMAT"
  error_details?: Array<{
    explanation?: string
    context?: {
      invalid_variables?: { ... }
    }
  }> | Array<{
    items?: {
      name?: { ... }
      message?: { ... }
      stack?: { ... }
      cause?: { ... }
    }
  }> | Array<{
    id?: string
    context?: string
    explanation?: string
  }>
}

`InvalidCustomVariableErrorDetails`

Error details for invalid custom variables. This error will appear under 'PARSE_ERROR' error code.

type InvalidCustomVariableErrorDetails = Array<{
  explanation?: string
  context?: {
    invalid_variables?: Array<{
      variable?: { ... }
      error?: { ... }
    }>
  }
}>

`InvalidCustomVariableErrorDetail`

type InvalidCustomVariableErrorDetail = {
  explanation?: string
  context?: {
    invalid_variables?: Array<{
      variable?: { ... }
      error?: { ... }
    }>
  }
}

`InternalErrorDetails`

Error details for internal error. This error will appear under 'INTERNAL_ERROR' error code.

type InternalErrorDetails = Array<{
  items?: {
    name?: string
    message?: string
    stack?: string
    cause?: string
  }
}>

`InternalErrorDetail`

Internal error detail

type InternalErrorDetail = {
  name?: string
  message?: string
  stack?: string
  cause?: string
}

`DocxTemplaterErrorDetails`

Error details for DocxTemplater error. This error will appear under 'PARSE_ERROR' error code. See https://docxtemplater.com/docs/errors/#error-schema for more details.

type DocxTemplaterErrorDetails = Array<{
  id?: string
  context?: string
  explanation?: string
}>

`DocxTemplaterErrorDetail`

DocxTemplater error detail

type DocxTemplaterErrorDetail = {
  id?: string
  context?: string
  explanation?: string
}

`ErrorCode`

Error codes for document generation:

PARSE_ERROR - Error while parsing the document. Normally related with a bad template using the wrong DocxTemplater syntax.
DOC_TO_PDF_CONVERT_ERROR - Error while converting the document to PDF. Normally related with a ConvertAPI failure.
INTERNAL_ERROR - In

type ErrorCode = "PARSE_ERROR" | "DOC_TO_PDF_CONVERT_ERROR" | "INTERNAL_ERROR" | "INVALID_TEMPLATE_FORMAT"

`TemplateSettings`

Template Settings for document generation

type TemplateSettings = {
  custom_margins?: {
    top?: number
    bottom?: number
  }
  suggested_margins?: {
    top?: number
    bottom?: number
  }
  display_margin_guidelines?: boolean
  enable_data_table_margin_autofix?: boolean
  template_with_datatable?: boolean
  enabled_template_settings_persistence?: boolean
  misconfigured_margins?: boolean
  file_entity_id?: string // uuid
}

`DocumentMetaRequest`

type DocumentMetaRequest = {
  template_document?: {
    s3ref?: {
      bucket: { ... }
      key: { ... }
    }
  }
}

`DocumentMetaResponse`

type DocumentMetaResponse = {
  page_margins?: {
    top?: number
    bottom?: number
    left?: number
    right?: number
    header?: number
    footer?: number
  }
  variables?: string[]
}

`DocumentGenerationV2Request`

type DocumentGenerationV2Request = {
  template_document: {
    filename?: string
    s3ref?: {
      bucket: { ... }
      key: { ... }
    }
  }
  context_entity_id?: string // uuid
  user_id?: string
  language?: string
  variable_payload?: {
    additionalProperties?: string
  }
  context_data?: {
    additionalProperties?: string
  }
  template_settings?: {
    custom_margins?: {
      top?: { ... }
      bottom?: { ... }
    }
    suggested_margins?: {
      top?: { ... }
      bottom?: { ... }
    }
    display_margin_guidelines?: boolean
    enable_data_table_margin_autofix?: boolean
    template_with_datatable?: boolean
    enabled_template_settings_persistence?: boolean
    misconfigured_margins?: boolean
    file_entity_id?: string // uuid
  }
}

`DocumentGenerationV2Response`

type DocumentGenerationV2Response = {
  job_id?: string // uuid
  job_status?: "STARTED" | "PROCESSING" | "SUCCESS" | "FAILED"
  message?: string
  ics_output?: {
    output_document?: {
      filename?: { ... }
      s3ref?: { ... }
    }
  }
  pdf_output?: {
    preview_url?: string
    output_document?: {
      filename?: { ... }
      s3ref?: { ... }
    }
  }
  docx_output?: {
    preview_url?: string
    output_document?: {
      filename?: { ... }
      s3ref?: { ... }
    }
  }
  xlsx_output?: {
    preview_url?: string
    output_document?: {
      filename?: { ... }
      s3ref?: { ... }
    }
  }
  error_output?: {
    error_message?: string
    error_code?: "PARSE_ERROR" | "DOC_TO_PDF_CONVERT_ERROR" | "INTERNAL_ERROR" | "INVALID_TEMPLATE_FORMAT"
    error_details?: Array<{
      explanation?: { ... }
      context?: { ... }
    }> | Array<{
      items?: { ... }
    }> | Array<{
      id?: { ... }
      context?: { ... }
      explanation?: { ... }
    }>
  }
  variable_payload?: {
    additionalProperties?: string
  }
  template_settings?: {
    custom_margins?: {
      top?: { ... }
      bottom?: { ... }
    }
    suggested_margins?: {
      top?: { ... }
      bottom?: { ... }
    }
    display_margin_guidelines?: boolean
    enable_data_table_margin_autofix?: boolean
    template_with_datatable?: boolean
    enabled_template_settings_persistence?: boolean
    misconfigured_margins?: boolean
    file_entity_id?: string // uuid
  }
}

`ConvertDocumentRequest`

type ConvertDocumentRequest = {
  language?: string
  input_document: {
    s3ref: {
      bucket: { ... }
      key: { ... }
    }
  }
  output_format: "pdf"
  output_filename?: string
}

`ConvertDocumentResponse`

type ConvertDocumentResponse = {
  output_document?: {
    preview_url?: string
    s3ref?: {
      bucket: { ... }
      key: { ... }
    }
  }
}

Document API

Usage​

Tree-shakeable import​

Operations​

getTemplateMeta​

generateDocumentV2​

convertDocument​

Schemas​

S3Reference​

ErrorOutput​

InvalidCustomVariableErrorDetails​

InvalidCustomVariableErrorDetail​

InternalErrorDetails​

InternalErrorDetail​

DocxTemplaterErrorDetails​

DocxTemplaterErrorDetail​

ErrorCode​

TemplateSettings​

DocumentMetaRequest​

DocumentMetaResponse​

DocumentGenerationV2Request​

DocumentGenerationV2Response​

ConvertDocumentRequest​

ConvertDocumentResponse​

Usage

Tree-shakeable import

Operations

`getTemplateMeta`

`generateDocumentV2`

`convertDocument`

Schemas

`S3Reference`

`ErrorOutput`

`InvalidCustomVariableErrorDetails`

`InvalidCustomVariableErrorDetail`

`InternalErrorDetails`

`InternalErrorDetail`

`DocxTemplaterErrorDetails`

`DocxTemplaterErrorDetail`

`ErrorCode`

`TemplateSettings`

`DocumentMetaRequest`

`DocumentMetaResponse`

`DocumentGenerationV2Request`

`DocumentGenerationV2Response`

`ConvertDocumentRequest`

`ConvertDocumentResponse`