AEB Document Service API

openapi: 3.2.0
info:
  title: (DEMO1) HTTP Document Service API
  description: Thank you for using our HTTP API documentation.
  version: '1.0'
servers:
- url: https://rz3.aeb.de/demo1docs/rest
security:
- SWAGGER_AUTH_KEY: []
- BASIC_AUTH: []
tags:
- name: DocumentService
  description: REST API for the Document Service
paths:
  /DocumentService/workstation:
    get:
      tags:
      - DocumentService
      summary: getWorkstations
      description: <h3>Fetch all registered workstations</h3><p>Returns an information about all registered workstations as json or xml list.</p>
      operationId: getWorkstations
      responses:
        '200':
          description: The data was found and the required content has been sent in the response
          content:
            application/json: {}
            application/xml: {}
  /DocumentService/template/{fileName}/parse:
    get:
      tags:
      - DocumentService
      summary: parseDocumentTemplateContent
      description: <h3>Parse document</h3><p>Parses the referenced template data and returns the required information, as specified in the parse query parameters. The supported query parameters are individual to each document processor. The referenced template must already exist in the system.</p>
      operationId: parseDocumentTemplateContent
      parameters:
      - name: fileName
        in: path
        description: Relative file name of the document template in file system (without path). This name, together with the version, uniquely identifies a template resource.
        required: true
        schema:
          type: string
        example: DemoDoc10.pdf
      - name: processor
        in: query
        description: Document processor tag. It decides, which processor takes care of the document.
        schema:
          type: string
        example: PDF-XFA
      - name: query
        in: query
        description: Parse query. Defines, which part of the template is to be returned.
        schema:
          type: string
        examples:
          xmls:
            summary: List of predefined XML examples
            description: 'Return the predefined example XMLs of a document template (plain list of UTF8 strings, one page name per line). Each line, including the last one, is delimited by the system line separator. These example XMLs are resources of a bundle and must be manually added. To return a specific example XML from that list the XML can be extended by a ''?'' and the name of the XML: <code>query="XML?some-known-example.xml"</code> <br><br>To determine a generic empty example XML the parse commandXML can be used.'
            value: XMLs
          xml:
            summary: Empty document data example (XML format)
            description: Empty XML document data, generated from the document data schema
            value: XML
          xsd:
            summary: Schema in XSD format
            description: Return the data schema definition (XSD format http://www.w3.org/2001/XMLSchema).
            value: XSD
          SchemaDTO:
            summary: Schema in proprietary format (JSON)
            description: Return the data schema definition (proprietary format DocumentTemplateSchemaDTO).
            value: SchemaDTO
          pageNames:
            summary: Template page names
            description: Return the template page names (plain list of UTF8 strings, one page name per line). Each line, including the last one, is delimited by the system line separator.
            value: PageNames
          textPlaceholders:
            summary: List of template placeholders
            description: Return the template text placeholders (plain list of UTF8 string, one placeholder name per line). Each line, including the last one, is delimited by the system line separator.
            value: TextPlaceholders
          xml_example:
            summary: A predefined XML example
            description: Return XML example 'DemoDoc10.example.xml'. See query=XMLs to get a list of all predefined examples.
            value: XML?DemoDoc10.example.xml
      responses:
        '200':
          description: The data was found and the required content has been sent in the response
        '400':
          description: Document template doesn't have the requested external tag
        '404':
          description: Document template was not found
  /DocumentService/template:
    get:
      tags:
      - DocumentService
      summary: queryDocumentTemplates
      description: <h3>Query information on document templates</h3><p>Returns a list of available templates for the specified processor. The templates are resolved in the context of a session client. Processor parameter is optional; templates for all supported processors are returned when empty.</p>
      operationId: queryDocumentTemplates
      parameters:
      - name: processor
        in: query
        description: Document processor tag
        schema:
          type: string
        example: PDF-XFA
      responses:
        '200':
          description: The data was found and the required content has been sent in the response
          content:
            application/json: {}
            application/xml: {}
        '400':
          description: No processor registered and supported for specified tag
  /DocumentService/ui/printQueue:
    get:
      tags:
      - DocumentService
      summary: openPrintRequestQueue
      description: <h3>Get URL to print queue</h3><p>Returns print request queue in url.</p>
      operationId: openPrintRequestQueue
      parameters:
      - name: user
        in: query
        description: 'The user of the new session.<br> It is not required, that this user is a valid user name of the client. However: Such a user may have granted only the role "I_EVERYONE" unless XNSG is configured to use e.g. an LDAP server and the user can be found in the LDAP server with some roles granted to the user. <br> No password is required because other servers which contact over the business facade will be trusted to have checked the users access rights. This enables a kind of "single sign on" between different e.g. XNSG servers.'
        schema:
          type: string
        example: API_TEST
      - name: language
        in: query
        description: The two letter ISO code of the language of the new session. Currently "de" and "en" are supported.
        schema:
          type: string
        example: en
      - name: workstationId
        in: query
        description: The id of the workstation for which the print requests have to be shown.
        schema:
          type: string
      - name: redirect
        in: query
        description: If set to 'true', the generated URI is returned in the 'Location' header of a SEE OTHER (303) response.
        schema:
          type: boolean
      responses:
        '200':
          description: The data was found and the required content has been sent in the response
          content:
            application/internet-shortcut: {}
            application/json: {}
            application/xml: {}
          links:
            target page url:
              description: Alternative to response content, target page url is accessible via link header
        '303':
          description: Redirected to a URI generated in call response
  /DocumentService/ui/document/{documentId}:
    get:
      tags:
      - DocumentService
      summary: openStagedDocumentEditor
      description: <h3>Get URL to edit document</h3><p>Returns document editor url.</p>
      operationId: openStagedDocumentEditor
      parameters:
      - name: documentId
        in: path
        description: The documentId of the document to be edited.
        required: true
        schema:
          type: string
      - name: editorAction
        in: query
        description: The action to start with. Default initial action is PREVIEW
        schema:
          type: string
          enum:
          - EDIT
          - PREVIEW
          - PRINT_DIALOG
      - name: user
        in: query
        description: 'The user of the new session.<br> It is not required, that this user is a valid user name of the client. However: Such a user may have granted only the role "I_EVERYONE" unless XNSG is configured to use e.g. an LDAP server and the user can be found in the LDAP server with some roles granted to the user. <br> No password is required because other servers which contact over the business facade will be trusted to have checked the users access rights. This enables a kind of "single sign on" between different e.g. XNSG servers.'
        schema:
          type: string
        example: API_TEST
      - name: language
        in: query
        description: The two letter ISO code of the language of the new session. Currently "de" and "en" are supported.
        schema:
          type: string
        example: en
      - name: redirect
        in: query
        description: If set to 'true', the generated URI is returned in the 'Location' header of a SEE OTHER (303) response.
        schema:
          type: boolean
      responses:
        '200':
          description: The data was found and the required content has been sent in the response
          content:
            application/internet-shortcut: {}
            application/json: {}
            application/xml: {}
          links:
            target page url:
              description: Alternative to response content, target page url is accessible via link header
        '303':
          description: Redirected to a URI generated in call response
  /DocumentService/ui/document:
    get:
      tags:
      - DocumentService
      summary: openStagedDocumentSearch
      description: <h3>Get URL to search document</h3><p>Returns document search link.</p>
      operationId: openStagedDocumentSearch
      parameters:
      - name: user
        in: query
        description: 'The user of the new session.<br> It is not required, that this user is a valid user name of the client. However: Such a user may have granted only the role "I_EVERYONE" unless XNSG is configured to use e.g. an LDAP server and the user can be found in the LDAP server with some roles granted to the user. <br> No password is required because other servers which contact over the business facade will be trusted to have checked the users access rights. This enables a kind of "single sign on" between different e.g. XNSG servers.'
        schema:
          type: string
        example: API_TEST
      - name: language
        in: query
        description: The two letter ISO code of the language of the new session. Currently "de" and "en" are supported.
        schema:
          type: string
        example: en
      - name: documentId
        in: query
        description: Criteria for the document ID of the document. Only documents that exactly match the ID pattern will be returned.
        schema:
          type: string
      - name: referenceType
        in: query
        description: Criteria for the reference type of the documents. Only documents that exactly match the reference type pattern will be returned.
        schema:
          type: string
      - name: referenceNumber
        in: query
        description: Criteria for the reference number of the documents. The criteria can contain wildcards.
        schema:
          type: string
      - name: documentType
        in: query
        description: Criteria for the document type of the document. Only documents that exactly match the document type pattern will be returned.
        schema:
          type: string
      - name: relativeFromValue
        in: query
        description: Relative time range, from
        schema:
          type: integer
          format: int32
      - name: relativeFromUnit
        in: query
        description: Relative time range, from
        schema:
          type: string
          enum:
          - DAYS
          - WDAYS
          - WEEKS
          - MONTHS
          - YEARS
      - name: relativeToValue
        in: query
        description: Relative time range, to
        schema:
          type: integer
          format: int32
      - name: relativeToUnit
        in: query
        description: Relative time range, to
        schema:
          type: string
          enum:
          - DAYS
          - WDAYS
          - WEEKS
          - MONTHS
          - YEARS
      - name: absoluteFrom
        in: query
        description: Specific day/time for filtering, from
        schema:
          type: string
          format: date-time
        example: '2000-01-01 00:00:00'
      - name: absoluteTo
        in: query
        description: Specific day/time for filtering, to
        schema:
          type: string
          format: date-time
        example: '2099-12-31 23:59:59'
      - name: redirect
        in: query
        description: If set to 'true', the generated URI is returned in the 'Location' header of a SEE OTHER (303) response.
        schema:
          type: boolean
      responses:
        '200':
          description: The data was found and the required content has been sent in the response
          content:
            application/internet-shortcut: {}
            application/json: {}
            application/xml: {}
          links:
            target page url:
              description: Alternative to response content, target page url is accessible via link header
        '303':
          description: Redirected to a URI generated in call response
  /DocumentService/document:
    get:
      tags:
      - DocumentService
      summary: queryDocuments
      description: '<h3>Query information on existing documents</h3><p>Executes a search query on the documents stored in the document storage. Only the documents that are visible to the caller (session user and session client) are returned. The results can be sorted by predefined criteria, the limit of the number of results is configurable, too.</p><h4>Date time interval range filter</h4><p>Use one of the given attributes to pass the filter. If more than one attribute is filled attributes will be used in the following order: relative interval, absolute interval<ul><li>Filter relative to current day, e.g: from 6 moths ago to a week ago (relativeFrom = "-6 MONTHS", relativeTo = "-1 WEEKS")</li><li>Filter with absolute date-time values, see field examples</li></ul></p>'
      operationId: queryDocuments
      parameters:
      - name: referenceType
        in: query
        description: Document reference type (only exact match)
        schema:
          type: string
      - name: documentType
        in: query
        description: Document type (only exact match)
        schema:
          type: string
      - name: referenceNumberPattern
        in: query
        description: Document reference number pattern (can contain wildcards)
        schema:
          type: string
      - name: referenceNumber
        in: query
        description: List of document reference numbers (max. 1000 elements allowed). Only documents exactly matching these numbers will be returned.<p>Consider using `/documentByRef` instead.</p>
        deprecated: true
        schema:
          maxItems: 1000
          type: array
          items:
            type: string
            default: referenceNumber
      - name: documentId
        in: query
        description: List of document IDs (max. 1000 elements allowed). Only documents exactly matching these IDs will be returned.<p>Consider using `/documentById` instead.</p>
        deprecated: true
        schema:
          maxItems: 1000
          type: array
          items:
            type: string
            default: documentId
      - name: returnTotalCount
        in: query
        description: If `true`, total number of documents found is returned in field `totalCount`. Total number can be different from number of actually returned documents in case total document count exceeds value `maxResults`
        schema:
          type: boolean
      - name: maxResults
        in: query
        description: 'Defines how many documents will be returned. Default value: 30, maximum value: 100'
        schema:
          type: integer
          format: int32
      - name: skipFirst
        in: query
        description: If set, defines the number of documents that will be skipped before collecting results. Use this to retrieve further documents if a previous query did not return all required documents. The number must not exceed 10000
        schema:
          type: integer
          format: int32
      - name: orderBy
        in: query
        description: 'Defines how the requested documents are sorted.<ul><li>`CREATED_AT_ASC` : <i>Sorted by date/time of document creation, oldest first.</i></li><li>`CREATED_AT_DESC` : <i>Sorted by date/time of document creation, newest first.</i></li><li>`REFERENCE_NUMBER_ASC` : <i>Sorted by document reference number, alphabetically ascending.</i></li><li>`REFERENCE_NUMBER_DESC` : <i>Sorted by document reference number, alphabetically descending.</i></li><li>`REFERENCE_TYPE_ASC` : <i>Sorted by document reference type, alphabetically ascending.</i></li><li>`REFERENCE_TYPE_DESC` : <i>Sorted by document reference type, alphabetically descending.</i></li></ul>'
        schema:
          type: string
          enum:
          - CREATED_AT_ASC
          - CREATED_AT_DESC
          - REFERENCE_NUMBER_ASC
          - REFERENCE_NUMBER_DESC
          - REFERENCE_TYPE_ASC
          - REFERENCE_TYPE_DESC
      - name: relativeFromValue
        in: query
        description: Relative time range, from
        schema:
          type: integer
          format: int32
      - name: relativeFromUnit
        in: query
        description: Relative time range, from
        schema:
          type: string
          enum:
          - DAYS
          - WDAYS
          - WEEKS
          - MONTHS
          - YEARS
      - name: relativeToValue
        in: query
        description: Relative time range, to
        schema:
          type: integer
          format: int32
      - name: relativeToUnit
        in: query
        description: Relative time range, to
        schema:
          type: string
          enum:
          - DAYS
          - WDAYS
          - WEEKS
          - MONTHS
          - YEARS
      - name: absoluteFrom
        in: query
        description: Specific day/time for filtering, from
        schema:
          type: string
          format: date-time
        example: '2000-01-01 00:00:00'
      - name: absoluteTo
        in: query
        description: Specific day/time for filtering, to
        schema:
          type: string
          format: date-time
        example: '2099-12-31 23:59:59'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryDocumentsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/QueryDocumentsResponseDTO'
    put:
      tags:
      - DocumentService
      summary: createDocument
      description: <h3>Upload an external document</h3><p>Uploads an external document (which does not depend on any document templates). Like `POST /document`, the uploaded document can be queried, deleted and fetched by calling the corresponding method with the received `documentId`. The document also has a date to which it is at least stored in the document store.<br/>Currently only PDF documents up to a maximum size of 10MB are supported, without embedded links, scripts or attachments.</p>
      operationId: createDocument
      parameters:
      - name: fileName
        in: query
        description: Document file name
        schema:
          type: string
        example: INV_4711.pdf
      - name: referenceNumber
        in: query
        description: <b>Staging Options:</b> Document reference number
        schema:
          type: string
        example: 4711
      - name: referenceType
        in: query
        description: <b>Staging Options:</b> Document reference type
        schema:
          type: string
        example: SHIPMENT
      - name: documentType
        in: query
        description: <b>Staging Options:</b> Document type
        schema:
          type: string
        example: INVOICE
      - name: retentionDaysLimit
        in: query
        description: <b>Staging Options:</b> How long should the generated document be retained (max 90 days)
        schema:
          maximum: 90
          type: integer
          format: int32
        example: 3
      - name: tag
        in: query
        description: <b>Staging Options:</b> Additional tags that help to further describe the document (e.g. document source system, context, category...) and allows it to be found again by browsing and searching.<p>Tags <b>must</b> follow the <em>kebab case</em> naming convention (lowercase, words separated by hyphens)</p><p>Existing tags are retained if no value is defined. Defined values replace the existing tags. To delete all text without creating a tag, an empty tag has to be defined (e.g. `&tag=`)</p>
        schema:
          type: array
          items:
            type: string
        example:
        - foo
        - bar
      requestBody:
        description: Document to upload (only PDF supported)
        content:
          application/pdf:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Document was created.
          links:
            content:
              operationRef: document/{documentId}
              parameters:
                documentId: $documentId
              description: Download document content
        '400':
          description: Missing or invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
    post:
      tags:
      - DocumentService
      summary: createDocument
      description: <h3>Generate a new document either synchronously (wait for the result) or asynchronously (enqueue document creation and get the result later with the provided documentId).</h3><p>Creates a document from the referenced template and document data. The template is resolved in the context of the session client. If any of the <b>Staging options</b> is filled the created document contents will be retained for later reuse.<br/>An existing document can be updated in `POST /document/{documentId}` and stored as a new revision in the archive in case it was previously archived.<br/>The update can be done in different ways, see the description for `POST /document/{documentId}`
      operationId: createDocument_1
      parameters:
      - name: async
        in: query
        description: Asynchronous document creation. If `true`, the request returns immediately, whereas the document is being prepared in the background.
        schema:
          type: boolean
          default: false
      - name: processor
        in: query
        description: <b>Processing Options:</b> Document processor tag
        schema:
          type: string
        example: PDF-XFA
      - name: templateName
        in: query
        description: <b>Processing Options:</b> Document template name
        schema:
          type: string
        example: DemoDoc10.pdf
      - name: format
        in: query
        description: <b>Processing Options:</b> Format of the generated document (one of the formats supported by the processor)
        schema:
          type: string
        examples:
          pdf:
            description: PDF version 1.5 including layout and data (standard for e-distribution)
            value: PDF
          pdf_data:
            description: PDF version 1.5, only data - no layout
            value: PDF data
          pdfa:
            description: PDF/a including layout and data
            value: PDFa
          pdfa_data:
            description: PDF/a, only data - no layout
            value: PDFa data
      - name: documentLocale
        in: query
        description: <b>Processing Options:</b> Language of the generated document (if applicable)
        schema:
          type: string
      - name: documentName
        in: query
        description: <b>Processing Options:</b> Suggested base file name of the generated document (without extension)
        schema:
          type: string
        example: DEMO_4711
      - name: referenceNumber
        in: query
        description: <b>Staging Options:</b> Document reference number
        schema:
          type: string
        example: 4711
      - name: referenceType
        in: query
        description: <b>Staging Options:</b> Document reference type
        schema:
          type: string
        example: SHIPMENT
      - name: documentType
        in: query
        description: <b>Staging Options:</b> Document type
        schema:
          type: string
        example: DEMODOC
      - name: retentionDaysLimit
        in: query
        description: <b>Staging Options:</b> How long should the generated document be retained (max 90 days)
        schema:
          maximum: 90
          type: integer
          format: int32
        example: 3
      - name: tag
        in: query
        description: <b>Staging Options:</b> Additional tags that help to further describe the document (e.g. document source system, context, category...) and allows it to be found again by browsing and searching.<p>Tags <b>must</b> follow the <em>kebab case</em> naming convention (lowercase, words separated by hyphens)</p><p>Existing tags are retained if no value is defined. Defined values replace the existing tags. To delete all text without creating a tag, an empty tag has to be defined (e.g. `&tag=`)</p>
        schema:
          type: array
          items:
            type: string
        example:
        - foo
        - bar
      requestBody:
        description: Document data (XML or JSON format - must match the provided 'ContentType' header)
        content:
          application/xml:
            schema:
              type: string
              description: XML document data
              format: binary
          application/json:
            schema:
              type: string
              description: JSON document data
              format: binary
      responses:
        '200':
          description: Request has been successfully processed, document created and result link has been sent in response header.
          content:
            '*/*':
              schema:
                type: string
                description: Generated document content
                format: binary
                example: '...'
          links:
            content:
              operationRef: document/{documentId}
              parameters:
                documentId: $documentId
              description: Download document content
        '202':
          description: Request is being processed asynchronously and result link has been sent in response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrepareDocumentResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/PrepareDocumentResponseDTO'
          links:
            content:
              operationRef: document/{documentId}
              parameters:
                documentId: $documentId
              description: Download document content
        '400':
          description: Missing or invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
  /DocumentService/documentTrusted:
    put:
      tags:
      - DocumentService
      summary: createDocumentTrusted
      description: <h3>Upload an external document</h3>Access is restricted to the `I_DOCUMENTSERVICEBF_TRUSTED` role.<p>Like `PUT /document` but with less limitations to the uploaded contents.</p>
      operationId: createDocumentTrusted
      parameters:
      - name: fileName
        in: query
        description: Document file name
        schema:
          type: string
        example: INV_4711.pdf
      - name: referenceNumber
        in: query
        description: <b>Staging Options:</b> Document reference number
        schema:
          type: string
        example: 4711
      - name: referenceType
        in: query
        description: <b>Staging Options:</b> Document reference type
        schema:
          type: string
        example: SHIPMENT
      - name: documentType
        in: query
        description: <b>Staging Options:</b> Document type
        schema:
          type: string
        example: INVOICE
      - name: retentionDaysLimit
        in: query
        description: <b>Staging Options:</b> How long should the generated document be retained (max 90 days)
        schema:
          maximum: 90
          type: integer
          format: int32
        example: 3
      - name: tag
        in: query
        description: <b>Staging Options:</b> Additional tags that help to further describe the document (e.g. document source system, context, category...) and allows it to be found again by browsing and searching.<p>Tags <b>must</b> follow the <em>kebab case</em> naming convention (lowercase, words separated by hyphens)</p><p>Existing tags are retained if no value is defined. Defined values replace the existing tags. To delete all text without creating a tag, an empty tag has to be defined (e.g. `&tag=`)</p>
        schema:
          type: array
          items:
            type: string
        example:
        - foo
        - bar
      requestBody:
        description: Document to upload
        content:
          '*/*':
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Document was created.
          links:
            content:
              operationRef: document/{documentId}
              parameters:
                documentId: $documentId
              description: Download document content
        '400':
          description: Missing or invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
        '403':
          description: Access denied, restricted to I_DOCUMENTSERVICEBF_TRUSTED role.
  /DocumentService/document/{documentId}:
    get:
      tags:
      - DocumentService
      summary: getDocument
      description: <h3>Download an existing document content</h3><p>Returns the requested document content if it is available for the user. A document may contain several contents, so the user has to define which content to return by the documentId and the variant.</p>
      operationId: getDocument
      parameters:
      - name: documentId
        in: path
        description: Unique document id (as returned from POST/PUT/GET document)
        required: true
        schema:
          type: string
        example: 012345678-abcd-4eff-9876-543210fedcba
      - name: contentVariant
        in: query
        description: Document content variant (optional)
        schema:
          type: string
      - name: searchInArchive
        in: query
        description: Search archives if not found in common storage
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: The data was found and the required content has been sent in the response.
          content:
            '*/*':
              schema:
                type: string
                description: Downloadable document content
                format: binary
                example: '...'
        '400':
          description: Requested or default content has not been found. Check the `contentVariant` parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
        '404':
          description: The requested document was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
        '410':
          description: The content of the requested document has expired and is no more available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
        '422':
          description: Asynchronous creation of requested content failed.
          content:
            application/json:
              schema:
           

# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aeb/refs/heads/main/openapi/aeb-documentservice-api-openapi.yml