Skip to content

document.md

Latest commit

 

History

History
403 lines (330 loc) · 8.99 KB

document.md

File metadata and controls

403 lines (330 loc) · 8.99 KB
Raw

Document API

A document generation API that allows you to generate documents from templates with variables.

Quick Start

# List available operations
epilot document

# Call an operation
epilot document getTemplateMeta

Common Flags

Flag Description
-p key=value Set a named parameter
-d '{...}' Request body JSON
-H 'Key: Value' Custom header
-t, --token <token> Bearer token for authentication
--profile <name> Use a named profile
-s, --server <url> Override server base URL
-i, --include Include response headers in output
--json Output raw JSON (no formatting)
-v, --verbose Verbose output (show request details)
--jsonata <expr> JSONata expression to transform response
--definition <file> Override OpenAPI spec file/URL
--guided Prompt for all parameters interactively
--no-interactive Disable interactive prompts

Operations

Documents

getTemplateMeta

Get metadata for a document template

POST /v2/documents:meta

Request Body (required)

Sample Call

epilot document getTemplateMeta \
  -d '{"template_document":{"s3ref":{"bucket":"document-api-prod","key":"uploads/my-template.pdf"}}}'

Using stdin pipe:

cat body.json | epilot document getTemplateMeta

With JSONata filter:

epilot document getTemplateMeta --jsonata 'page_margins'
Sample 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

Parameters

Name In Type Required Description
job_id query string No Job ID for tracking the status of document generation action
mode query "partial_generation" | "full_generation" No Type of mode used for document generation flow:
  • partial_generation will have a intermediate step for users to validate and replace the variable values before generating the final document.
  • full_ge | | preview_mode | query | "open" | "download" | No | Type of mode used for document generation preview:
  • open - preview_url provides a link to open the file in a browser
  • download - preview_url provides a link to download the file |

Request Body (required)

Sample Call

epilot document generateDocumentV2

With request body:

epilot document generateDocumentV2 \
  -d '{
  "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": "123e4567-e89b-12d3-a456-426614174000"
  }
}'

Using stdin pipe:

cat body.json | epilot document generateDocumentV2

With JSONata filter:

epilot document generateDocumentV2 --jsonata 'job_id'
Sample 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": "123e4567-e89b-12d3-a456-426614174000"
  }
}

convertDocument

Converts a document to a different format.

POST /v2/documents:convert

Request Body (required)

Sample Call

epilot document convertDocument

With request body:

epilot document convertDocument \
  -d '{
  "language": "de",
  "input_document": {
    "s3ref": {
      "bucket": "document-api-prod",
      "key": "uploads/my-template.pdf"
    }
  },
  "output_format": "pdf",
  "output_filename": "converted.pdf"
}'

Using stdin pipe:

cat body.json | epilot document convertDocument

With JSONata filter:

epilot document convertDocument --jsonata 'output_document'
Sample 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"
    }
  }
}

validateTemplate

Validates a document template's variable syntax and, optionally, proposes a hotfixed copy of it.

POST /v2/templates:validate

Request Body (required)

Sample Call

epilot document validateTemplate

With request body:

epilot document validateTemplate \
  -d '{
  "template_document": {
    "filename": "Umzugsmeldung.xlsx",
    "s3ref": {
      "bucket": "document-api-prod",
      "key": "uploads/my-template.pdf"
    }
  },
  "fix": true,
  "fix_level": "safe"
}'

Using stdin pipe:

cat body.json | epilot document validateTemplate

With JSONata filter:

epilot document validateTemplate --jsonata 'valid'
Sample Response 
{
  "valid": false,
  "fixed": true,
  "issues": [
    {
      "id": "unopened_tag",
      "file": "xl/sharedStrings.xml",
      "location": "Tabelle1!N4",
      "context": "…Datum: {system.date}} Unterschrift…",
      "explanation": "The tag is missing an opening brace.",
      "fixable": true,
      "confidence": "high",
      "rule": "balance_opening_delimiter",
      "before": "{system.date}}",
      "after": "{{system.date}}"
    }
  ],
  "unresolved_errors": [
    {
      "id": "string",
      "context": "string",
      "explanation": "string"
    }
  ],
  "fixed_document": {
    "s3ref": {
      "bucket": "document-api-prod",
      "key": "uploads/my-template.pdf"
    },
    "filename": "Umzugsmeldung (fixed).xlsx",
    "preview_url": "https://example.com/path"
  }
}