@celigo/api-specs 0.2.26 → 0.2.28

package/dist/bartendertemplate.yml

@@ -0,0 +1,508 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: BarTender Templates
+  description: API for listing and downloading Celigo-published BarTender label templates used by EDI label-printing flows.
+  x-celigo-ai-guidance:
+    - |-
+      Call `GET /v1/bartenderTemplates` first — that returns unique published
+      `names` only. Then call `GET /v1/bartenderTemplates?name=<selected>` to
+      load `s3Key` values and `fieldMappings` for the chosen templates. Download
+      a `.btw` with `GET /v1/bartenderTemplates/{name}/download`. Requires EDI
+      and EDI label-printing entitlements; returns 422
+      `edi_subscription_required` when either is missing and a bare 404 (empty
+      body) when the global label-printing kill switch is active.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: BarTender Templates
+    description: |-
+      Celigo-published BarTender (`.btw`) label templates synced daily from
+      BarTender Cloud. List unique names, load selected template details and
+      lookup-cache field mappings, or download a published `.btw`.
+
+      Requires a standard integrator.io JWT with manage or monitor role, plus
+      EDI and EDI label-printing entitlements on the account.
+
+      ## BarTender template schemas
+
+      {% openapi-schemas spec="bartendertemplate" schemas="BarTenderTemplateCatalog,BarTenderTemplate,BarTenderFieldMapping" grouped="true" %}
+paths:
+  /v1/bartenderTemplates:
+    get:
+      x-internal: false
+      operationId: listBarTenderTemplates
+      tags:
+        - BarTender Templates
+      summary: List BarTender label templates
+      description: |-
+        Returns Celigo-published BarTender catalog data. The catalog is read from
+        S3 (`catalog.json`, written by the daily sync cron) and cached in-process.
+
+        Omit `name` to get unique published template names (sorted). Pass one or
+        more `name` values to get matching templates and lookup-cache field
+        mappings plus the catalog `syncedAt`.
+
+        `name` accepts a comma-separated list or repeated query parameters.
+        Matching is case-sensitive and also treats pipe-separated tokens as
+        aliases (`amazon | 133` matches `amazon` or `133`). Unknown names return
+        empty `templates` and `fieldMappings` — not 404. `limit`, `page`, and
+        `search` are ignored.
+      parameters:
+        - name: name
+          in: query
+          required: false
+          description: |-
+            Filter to these published template names. Comma-separated or
+            repeated (`?name=amazon&name=walmart`). When omitted or empty, the
+            response is `{ names }` only.
+          schema:
+            type: string
+            examples:
+              - amazon
+              - amazon,walmart
+      responses:
+        '200':
+          description: |-
+            Unique names when `name` is omitted; filtered catalog details when
+            `name` is provided.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BarTenderTemplateCatalog'
+              examples:
+                names:
+                  summary: Unique published names (no name query)
+                  value:
+                    names:
+                      - amazon
+                      - walmart
+                details:
+                  summary: Filtered templates and field mappings
+                  value:
+                    syncedAt: '2026-07-10T02:15:00.000Z'
+                    templates:
+                      - name: amazon
+                        s3Key: EDI_BarTender_Templates/templates/FI!1.0!1!0f1c545d-1b36-49af-8e1f-5ce7e8ba43ec.btw
+                    fieldMappings:
+                      - key: amazon
+                        value:
+                          configurations:
+                            PACK|*:
+                              templateName: AMAZON_US_RETAIL_CARTON
+                      - key: amazon | 133
+                        value:
+                          configurations:
+                            PALLET|*:
+                              templateName: AMAZON_US_RETAIL_PALLET
+                empty_names:
+                  summary: Catalog has no published templates
+                  value:
+                    names: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The global BarTender label-printing kill switch
+            (`BARTENDER_LABEL_PRINTING_DISABLED`) is active. The route responds
+            with a bare `404` and an empty body so the feature appears unavailable.
+        '422':
+          description: |-
+            The account lacks a required EDI entitlement. Missing `edi.enabled` or
+            `edi.labelPrinting.enabled` both return the same
+            `edi_subscription_required` error — the route reuses the standard EDI
+            license gate used by other B2B Manager endpoints.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                edi_not_enabled:
+                  summary: EDI is not enabled on the account
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+                label_printing_not_enabled:
+                  summary: EDI label printing is not enabled on the account
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+        '502':
+          description: |-
+            The catalog could not be read from S3 or the stored `catalog.json` is
+            malformed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_unavailable:
+                  summary: S3 read or parse failure
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_UNAVAILABLE
+                        message: The BarTender template catalog is temporarily unavailable. Please try again later.
+        '503':
+          description: |-
+            The catalog has never been published for this environment, or the
+            EDI license check could not be completed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_not_initialized:
+                  summary: Catalog not yet synced
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_NOT_INITIALIZED
+                        message: The BarTender template catalog has not been published yet. Please try again later.
+                license_check_failed:
+                  summary: EDI license lookup failed
+                  value:
+                    errors:
+                      - code: edi_license_check_failed
+                        message: We're unable to verify your EDI license at the moment. Please contact support if the issue persists.
+  /v1/bartenderTemplates/{name}/download:
+    get:
+      x-internal: false
+      operationId: downloadBarTenderTemplate
+      tags:
+        - BarTender Templates
+      summary: Download a BarTender label template
+      description: |-
+        Returns the published `.btw` binary for the named template.
+
+        `name` must match a published catalog entry exactly — pipe-token alias
+        matching from the list route is not applied here. The file is streamed
+        as `application/octet-stream` with `Content-Disposition: attachment`.
+      x-celigo-ai-guidance:
+        - |-
+          The name check runs before the catalog lookup, so a published name that
+          contains characters outside `[A-Za-z0-9._ -]` (parentheses, for example)
+          appears in the list response but answers 400
+          BARTENDER_TEMPLATE_INVALID_NAME here and cannot be downloaded through this
+          route. Live-verified 2026-09-18.
+      parameters:
+        - name: name
+          in: path
+          required: true
+          description: |-
+            Published template name from `GET /v1/bartenderTemplates`. Allowed
+            characters are letters, digits, period, underscore, space, and
+            hyphen; `..` is rejected.
+          schema:
+            type: string
+            pattern: ^[A-Za-z0-9._ -]+$
+            examples:
+              - amazon
+      responses:
+        '200':
+          description: Published `.btw` binary.
+          headers:
+            Content-Disposition:
+              description: |-
+                Attachment filename taken from the template object's basename
+                (the `.btw` file name).
+              schema:
+                type: string
+                examples:
+                  - attachment; filename="FI!1.0!1!0f1c545d-1b36-49af-8e1f-5ce7e8ba43ec.btw"
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          description: |-
+            `name` is empty or contains characters outside
+            `[A-Za-z0-9._ -]`, or includes `..`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_name:
+                  value:
+                    errors:
+                      - code: BARTENDER_TEMPLATE_INVALID_NAME
+                        message: The BarTender template name is invalid.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The template is not in the published catalog, or the global
+            label-printing kill switch is active (bare `404`, empty body).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Name is not a published template
+                  value:
+                    errors:
+                      - code: BARTENDER_TEMPLATE_NOT_FOUND
+                        message: The requested BarTender template was not found in the published catalog.
+        '422':
+          description: |-
+            The account lacks a required EDI entitlement. Missing `edi.enabled` or
+            `edi.labelPrinting.enabled` both return `edi_subscription_required`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                edi_subscription_required:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+        '502':
+          description: |-
+            The catalog could not be read, or the `.btw` object could not be
+            fetched from S3.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_unavailable:
+                  summary: Catalog read or parse failure
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_UNAVAILABLE
+                        message: The BarTender template catalog is temporarily unavailable. Please try again later.
+                download_failed:
+                  summary: Template object read failure
+                  value:
+                    errors:
+                      - code: BARTENDER_TEMPLATE_DOWNLOAD_FAILED
+                        message: The BarTender template file is temporarily unavailable. Please try again later.
+        '503':
+          description: |-
+            The catalog has never been published for this environment, or the
+            EDI license check could not be completed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                catalog_not_initialized:
+                  summary: Catalog not yet synced
+                  value:
+                    errors:
+                      - code: BARTENDER_CATALOG_NOT_INITIALIZED
+                        message: The BarTender template catalog has not been published yet. Please try again later.
+                license_check_failed:
+                  summary: EDI license lookup failed
+                  value:
+                    errors:
+                      - code: edi_license_check_failed
+                        message: We're unable to verify your EDI license at the moment. Please contact support if the issue persists.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    BarTenderTemplate:
+      type: object
+      description: |-
+        One published BarTender label template. Internal catalog fields (`id`,
+        `btChecksum`, `modifiedDateTime`, `version`) are not exposed — only `name`
+        and `s3Key` are returned.
+      required:
+        - name
+        - s3Key
+      properties:
+        name:
+          type: string
+          description: |-
+            Published display name, derived from the `.btw` file stem
+            (`amazon.btw` → `"amazon"`). Use this value in the `name` query
+            parameter and in `GET /v1/bartenderTemplates/{name}/download`.
+          examples:
+            - amazon
+        s3Key:
+          type: string
+          description: |-
+            Object key for the `.btw` binary in the UI-resources bucket. Pass this
+            to the downstream S3 export step that pushes the template to the
+            customer's BarTender environment.
+          examples:
+            - EDI_BarTender_Templates/templates/FI!1.0!1!0f1c545d-1b36-49af-8e1f-5ce7e8ba43ec.btw
+    BarTenderFieldMapping:
+      type: object
+      description: |-
+        One lookup-cache field mapping from the published catalog. Keys often
+        name a template (or a pipe-separated alias such as `amazon | 133`);
+        values keep whatever JSON shape the master cache stored.
+      required:
+        - key
+        - value
+      properties:
+        key:
+          type: string
+          description: |-
+            Mapping key. Filtered with the same case-sensitive exact / pipe-token
+            match as template `name` when `name` is supplied on the list route.
+          examples:
+            - amazon
+            - amazon | 133
+            - carrier
+        value:
+          description: |-
+            Mapping value from the master lookup cache. May be a string or an
+            object; consumers should check the runtime type before use.
+          oneOf:
+            - title: String value
+              type: string
+            - title: Object value
+              type: object
+              additionalProperties: true
+          examples:
+            - UPS
+            - configurations:
+                PACK|*:
+                  templateName: AMAZON_US_RETAIL_CARTON
+    BarTenderTemplateCatalog:
+      type: object
+      description: |-
+        Response from `GET /v1/bartenderTemplates`. When `name` is omitted the
+        body is `{ names }`. When `name` is provided the body is
+        `{ syncedAt, templates, fieldMappings }` for the matching entries.
+      properties:
+        names:
+          type: array
+          description: |-
+            Unique published template names, sorted. Present when `name` is
+            omitted. An empty catalog returns `[]`.
+          items:
+            type: string
+          examples:
+            - - amazon
+              - walmart
+        syncedAt:
+          type: string
+          format: date-time
+          description: |-
+            UTC timestamp of the last successful catalog sync. Present when
+            `name` is provided.
+          examples:
+            - '2026-07-10T02:15:00.000Z'
+        templates:
+          type: array
+          description: |-
+            Published templates whose `name` matches any requested `name` value.
+            Present when `name` is provided. Unknown names yield an empty array,
+            not a 404.
+          items:
+            $ref: '#/components/schemas/BarTenderTemplate'
+        fieldMappings:
+          type: array
+          description: |-
+            Published lookup-cache mappings whose `key` matches any requested
+            `name` value. Present when `name` is provided. A catalog that predates
+            field-mapping sync returns `[]`.
+          items:
+            $ref: '#/components/schemas/BarTenderFieldMapping'
+      if:
+        required:
+          - names
+      then:
+        required:
+          - names
+      else:
+        required:
+          - syncedAt
+          - templates
+          - fieldMappings
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+x-enable-proxy: true
+x-internal: false

package/dist/filedefinitionrules.yml

@@ -0,0 +1,722 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: File Definition Rules
+  description: |-
+    Async AI generation of EDI File Definition Rules (FDR) from specification PDFs.
+    Produces parsing and generation rules JSON; persists nothing.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: File Definition Rules
+    description: |-
+      Submit an EDI specification PDF (X12 or EDIFACT) and receive parsing
+      and/or generation File Definition Rules JSON, generated asynchronously.
+      Submit endpoints return a `requestId` immediately (202); poll the
+      matching GET endpoint until the job reaches `completed` or `failed`.
+      Job records expire 24 hours after submission. Submissions are
+      rate-limited per caller (10 per hour, with an administrator bypass);
+      the document-types catalog allows 100 per hour and 10 per 60 seconds.
+      The API only produces rules — it persists nothing. The Ora agent in
+      integrator.io drives these endpoints for interactive onboarding; call
+      them directly to script partner onboarding in bulk.
+
+      ## File definition rules schemas
+
+      {% openapi-schemas spec="filedefinitionrules" schemas="FdrSubmitRequest,FileDefinitionGenerationJob,FileDefinitionParsingJob" grouped="true" %}
+paths:
+  /v1/filedefinitionrules/generate:
+    post:
+      x-internal: false
+      operationId: submitFdrGeneration
+      tags:
+        - File Definition Rules
+      summary: Submit an FDR generation job
+      description: |-
+        Submits an async job that produces both parsing and generation FDR
+        artifacts from the supplied EDI specification PDF. Returns a
+        `requestId` immediately; poll
+        `GET /v1/filedefinitionrules/generate/{requestId}` for status and
+        results. Rate-limited to 10 submissions per caller per hour
+        (administrators bypass the limit).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FdrSubmitRequest'
+            examples:
+              x12:
+                summary: X12 850 specification
+                value:
+                  pdf: <base64-encoded PDF>
+                  documentType: 850
+      responses:
+        '202':
+          description: Job accepted.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - fileDefinitionGenerationJob
+                properties:
+                  fileDefinitionGenerationJob:
+                    type: object
+                    required:
+                      - requestId
+                    properties:
+                      requestId:
+                        type: string
+                        format: uuid
+                        description: Poll handle for the job.
+              examples:
+                accepted:
+                  value:
+                    fileDefinitionGenerationJob:
+                      requestId: 550e8400-e29b-41d4-a716-446655440000
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '413':
+          $ref: '#/components/responses/413-payload-too-large'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+        '429':
+          $ref: '#/components/responses/429-rate-limit'
+        '500':
+          $ref: '#/components/responses/500-internal'
+        '503':
+          $ref: '#/components/responses/503-unavailable'
+  /v1/filedefinitionrules/generate/{requestId}:
+    get:
+      x-internal: false
+      operationId: pollFdrGeneration
+      tags:
+        - File Definition Rules
+      summary: Poll an FDR generation job
+      description: |-
+        Returns the job's current state. When `status` is `completed`,
+        `result` carries `parsingFdr` and `generationFdr`; when `failed`,
+        `error` carries the code and message. Non-administrators can only
+        poll their own jobs. Job records expire after 24 hours
+        (`404 REQUEST_NOT_FOUND`).
+      parameters:
+        - name: requestId
+          in: path
+          required: true
+          description: Request id returned by the submit endpoint.
+          schema:
+            type: string
+            format: uuid
+            examples:
+              - 550e8400-e29b-41d4-a716-446655440000
+      responses:
+        '200':
+          description: Current job state.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - fileDefinitionGenerationJob
+                properties:
+                  fileDefinitionGenerationJob:
+                    $ref: '#/components/schemas/FileDefinitionGenerationJob'
+              examples:
+                completed:
+                  summary: Job completed
+                  value:
+                    fileDefinitionGenerationJob:
+                      requestId: 550e8400-e29b-41d4-a716-446655440000
+                      status: completed
+                      createdAt: '2026-06-24T10:30:00Z'
+                      startedAt: '2026-06-24T10:30:05Z'
+                      completedAt: '2026-06-24T10:31:45Z'
+                      result:
+                        parsingFdr: {}
+                        generationFdr: {}
+                failed:
+                  summary: Job failed
+                  value:
+                    fileDefinitionGenerationJob:
+                      requestId: 550e8400-e29b-41d4-a716-446655440000
+                      status: failed
+                      createdAt: '2026-06-24T10:30:00Z'
+                      completedAt: '2026-06-24T10:30:15Z'
+                      error:
+                        code: UNSUPPORTED_TYPE
+                        message: X12 transaction set 999 is not supported
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '500':
+          $ref: '#/components/responses/500-internal'
+  /v1/filedefinitionrules/parse:
+    post:
+      x-internal: false
+      operationId: submitFdrParsing
+      tags:
+        - File Definition Rules
+      summary: Submit an FDR parsing job
+      description: |-
+        Submits an async job that produces a parsing FDR only (no generation
+        artifact) from the supplied EDI specification PDF. Returns a
+        `requestId` immediately; poll
+        `GET /v1/filedefinitionrules/parse/{requestId}` for status and
+        results. Rate-limited to 10 submissions per caller per hour
+        (administrators bypass the limit).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FdrSubmitRequest'
+            examples:
+              x12:
+                summary: X12 850 specification
+                value:
+                  pdf: <base64-encoded PDF>
+                  documentType: 850
+      responses:
+        '202':
+          description: Job accepted.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - fileDefinitionParsingJob
+                properties:
+                  fileDefinitionParsingJob:
+                    type: object
+                    required:
+                      - requestId
+                    properties:
+                      requestId:
+                        type: string
+                        format: uuid
+                        description: Poll handle for the job.
+              examples:
+                accepted:
+                  value:
+                    fileDefinitionParsingJob:
+                      requestId: 550e8400-e29b-41d4-a716-446655440000
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '413':
+          $ref: '#/components/responses/413-payload-too-large'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+        '429':
+          $ref: '#/components/responses/429-rate-limit'
+        '500':
+          $ref: '#/components/responses/500-internal'
+        '503':
+          $ref: '#/components/responses/503-unavailable'
+  /v1/filedefinitionrules/parse/{requestId}:
+    get:
+      x-internal: false
+      operationId: pollFdrParsing
+      tags:
+        - File Definition Rules
+      summary: Poll an FDR parsing job
+      description: |-
+        Returns the job's current state. When `status` is `completed`,
+        `result` carries `parsingFdr` only; when `failed`, `error` carries
+        the code and message. Non-administrators can only poll their own
+        jobs. Job records expire after 24 hours (`404 REQUEST_NOT_FOUND`).
+      parameters:
+        - name: requestId
+          in: path
+          required: true
+          description: Request id returned by the submit endpoint.
+          schema:
+            type: string
+            format: uuid
+            examples:
+              - 550e8400-e29b-41d4-a716-446655440000
+      responses:
+        '200':
+          description: Current job state.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - fileDefinitionParsingJob
+                properties:
+                  fileDefinitionParsingJob:
+                    $ref: '#/components/schemas/FileDefinitionParsingJob'
+              examples:
+                completed:
+                  summary: Job completed
+                  value:
+                    fileDefinitionParsingJob:
+                      requestId: 550e8400-e29b-41d4-a716-446655440000
+                      status: completed
+                      createdAt: '2026-06-24T10:30:00Z'
+                      completedAt: '2026-06-24T10:31:45Z'
+                      result:
+                        parsingFdr: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '500':
+          $ref: '#/components/responses/500-internal'
+  /v1/filedefinitionrules/document-types:
+    get:
+      x-internal: false
+      operationId: listFdrDocumentTypes
+      tags:
+        - File Definition Rules
+      summary: List supported document types
+      description: |-
+        Returns the X12 transaction set numbers the generator supports (24 sets
+        as of v1.2.0) and whether EDIFACT auto-detection is available
+        (`documentType: 0`). Rate-limited to 100 requests per hour and 10 per
+        60 seconds per caller.
+      responses:
+        '200':
+          description: Supported document types.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentTypesResponse'
+              examples:
+                default:
+                  value:
+                    fileDefinitionDocumentTypes:
+                      supportedTypes:
+                        - 180
+                        - 204
+                        - 210
+                        - 214
+                        - 810
+                        - 812
+                        - 820
+                        - 824
+                        - 832
+                        - 835
+                        - 846
+                        - 850
+                        - 852
+                        - 855
+                        - 856
+                        - 860
+                        - 864
+                        - 870
+                        - 875
+                        - 880
+                        - 940
+                        - 943
+                        - 944
+                        - 945
+                      edifactSupported: true
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '429':
+          $ref: '#/components/responses/429-rate-limit'
+        '500':
+          $ref: '#/components/responses/500-internal'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    FdrSubmitRequest:
+      type: object
+      required:
+        - pdf
+        - documentType
+      properties:
+        pdf:
+          type: string
+          description: |-
+            Base64-encoded EDI specification PDF. Must decode to a text-bearing
+            PDF — scanned/image-only documents fail the job with
+            `PDF_EXTRACTION_FAILED`. Encoded payloads over 50 MB are rejected
+            with `413 PAYLOAD_TOO_LARGE`.
+        documentType:
+          type: integer
+          description: |-
+            X12 transaction set number (e.g. 850), or 0 to auto-detect an
+            EDIFACT specification from the PDF contents. Values outside the
+            supported set fail with `400 INVALID_DOCUMENT_TYPE`; discover the
+            supported set via `GET /v1/filedefinitionrules/document-types`.
+          examples:
+            - 850
+    ErrorCode:
+      type: string
+      description: Machine-readable failure code returned by the FDR service.
+      enum:
+        - INVALID_DOCUMENT_TYPE
+        - INVALID_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - REQUEST_NOT_FOUND
+        - PAYLOAD_TOO_LARGE
+        - RATE_LIMIT_EXCEEDED
+        - PDF_EXTRACTION_FAILED
+        - UNSUPPORTED_TYPE
+        - DETECTION_FAILED
+        - GENERATION_FAILED
+        - SERVICE_UNAVAILABLE
+      x-enumDescriptions:
+        INVALID_DOCUMENT_TYPE: documentType is not 0 and not a supported X12 set
+        INVALID_REQUEST: Request body failed schema validation
+        UNAUTHORIZED: Missing or non-Bearer Authorization header
+        FORBIDDEN: Invalid, expired, or insufficient token or AShare
+        REQUEST_NOT_FOUND: Job id missing, wrong operation, or expired
+        PAYLOAD_TOO_LARGE: Encoded pdf exceeds the size limit
+        RATE_LIMIT_EXCEEDED: Caller exceeded the endpoint token bucket
+        PDF_EXTRACTION_FAILED: pdf is not valid base64 or not a PDF
+        UNSUPPORTED_TYPE: Worker could not generate an FDR for the detected type
+        DETECTION_FAILED: Worker could not classify the PDF as X12 or EDIFACT
+        GENERATION_FAILED: Unexpected pipeline or server failure
+        SERVICE_UNAVAILABLE: Job store or PDF storage is unavailable
+    ErrorItem:
+      type: object
+      additionalProperties: false
+      required:
+        - code
+        - message
+        - source
+      properties:
+        code:
+          $ref: '#/components/schemas/ErrorCode'
+        message:
+          type: string
+          description: Human-readable description of this error.
+        source:
+          type: string
+          description: Field or component that produced the error (`pdf`, `documentType`, `Authorization`, `requestId`, `rate_limiter`, `generation`).
+    Error:
+      type: object
+      additionalProperties: false
+      required:
+        - errors
+      properties:
+        errors:
+          type: array
+          description: One or more errors from this request.
+          items:
+            $ref: '#/components/schemas/ErrorItem'
+        correlationId:
+          type: string
+          description: Matches the X-Correlation-ID response header when the service set one.
+          examples:
+            - 550e8400-e29b-41d4-a716-446655440000
+    FileDefinitionGenerationJob:
+      type: object
+      required:
+        - requestId
+      description: |-
+        State of an async FDR generation job. `startedAt` appears once
+        processing begins; `completedAt`, and either `result` or `error`,
+        appear when the job finishes. Job records expire 24 hours after
+        submission — polling after that returns `404 REQUEST_NOT_FOUND`.
+      properties:
+        requestId:
+          type: string
+          format: uuid
+          description: Identifier returned by the submit endpoint; use it to poll.
+          examples:
+            - 550e8400-e29b-41d4-a716-446655440000
+        status:
+          type: string
+          enum:
+            - queued
+            - processing
+            - completed
+            - failed
+          x-enumDescriptions:
+            queued: Accepted, waiting for a worker.
+            processing: A worker is generating the FDR artifacts.
+            completed: Finished — `result` carries the artifacts.
+            failed: Finished with an error — see `error`.
+          description: Job lifecycle state. Keep polling until `completed` or `failed`.
+        createdAt:
+          type: string
+          format: date-time
+          description: When the job was submitted.
+        startedAt:
+          type: string
+          format: date-time
+          description: When processing began. Absent while queued.
+        completedAt:
+          type: string
+          format: date-time
+          description: When the job finished (either outcome). Absent until then.
+        result:
+          type: object
+          description: Present when `status` is `completed`.
+          properties:
+            parsingFdr:
+              type:
+                - object
+                - 'null'
+              additionalProperties: true
+              description: Opaque parsing FDR JSON artifact.
+            generationFdr:
+              type:
+                - object
+                - 'null'
+              additionalProperties: true
+              description: Opaque generation FDR JSON artifact.
+        error:
+          type: object
+          description: Present when `status` is `failed`.
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: string
+              description: |-
+                Failure code — typically UNSUPPORTED_TYPE, DETECTION_FAILED,
+                PDF_EXTRACTION_FAILED, or GENERATION_FAILED.
+              examples:
+                - UNSUPPORTED_TYPE
+            message:
+              type: string
+              description: Human-readable failure reason.
+              examples:
+                - X12 transaction set 999 is not supported
+    FileDefinitionParsingJob:
+      type: object
+      required:
+        - requestId
+      description: |-
+        State of an async FDR parsing job — identical lifecycle to the
+        generation job, but `result` carries only `parsingFdr`.
+      properties:
+        requestId:
+          type: string
+          format: uuid
+          description: Identifier returned by the submit endpoint; use it to poll.
+          examples:
+            - 550e8400-e29b-41d4-a716-446655440000
+        status:
+          type: string
+          enum:
+            - queued
+            - processing
+            - completed
+            - failed
+          x-enumDescriptions:
+            queued: Accepted, waiting for a worker.
+            processing: A worker is generating the parsing FDR.
+            completed: Finished — `result` carries the artifact.
+            failed: Finished with an error — see `error`.
+          description: Job lifecycle state. Keep polling until `completed` or `failed`.
+        createdAt:
+          type: string
+          format: date-time
+          description: When the job was submitted.
+        startedAt:
+          type: string
+          format: date-time
+          description: When processing began. Absent while queued.
+        completedAt:
+          type: string
+          format: date-time
+          description: When the job finished (either outcome). Absent until then.
+        result:
+          type: object
+          description: Present when `status` is `completed`.
+          properties:
+            parsingFdr:
+              type:
+                - object
+                - 'null'
+              additionalProperties: true
+              description: Opaque parsing FDR JSON artifact.
+        error:
+          type: object
+          description: Present when `status` is `failed`.
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: string
+              description: |-
+                Failure code — typically UNSUPPORTED_TYPE, DETECTION_FAILED,
+                PDF_EXTRACTION_FAILED, or GENERATION_FAILED.
+            message:
+              type: string
+              description: Human-readable failure reason.
+    FileDefinitionDocumentTypes:
+      type: object
+      additionalProperties: false
+      required:
+        - supportedTypes
+        - edifactSupported
+      properties:
+        supportedTypes:
+          type: array
+          description: Sorted X12 transaction set numbers this service can generate.
+          items:
+            type: integer
+        edifactSupported:
+          type: boolean
+          description: When true, submit documentType 0 to auto-detect EDIFACT from the PDF.
+    DocumentTypesResponse:
+      type: object
+      additionalProperties: false
+      required:
+        - fileDefinitionDocumentTypes
+      properties:
+        fileDefinitionDocumentTypes:
+          $ref: '#/components/schemas/FileDefinitionDocumentTypes'
+  responses:
+    400-bad-request:
+      description: Invalid documentType or request body failed validation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            invalidDocumentType:
+              value:
+                errors:
+                  - code: INVALID_DOCUMENT_TYPE
+                    message: Document type must be a valid X12 transaction set number (e.g. 850) or 0 for EDIFACT; got 999
+                    source: documentType
+    401-unauthorized:
+      description: Missing Authorization header or scheme is not Bearer JWT.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            missing:
+              value:
+                errors:
+                  - code: UNAUTHORIZED
+                    message: Missing bearer token
+                    source: Authorization
+    403-forbidden:
+      description: Token is invalid or expired, or the caller lacks permission or a valid AShare.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            expired:
+              value:
+                errors:
+                  - code: FORBIDDEN
+                    message: Bearer token has expired
+                    source: Authorization
+    413-payload-too-large:
+      description: Encoded pdf exceeds the 50 MB limit.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            tooLarge:
+              value:
+                errors:
+                  - code: PAYLOAD_TOO_LARGE
+                    message: Base64-encoded PDF exceeds 50 MB limit
+                    source: pdf
+    422-unprocessable-entity:
+      description: pdf is not valid base64 or decoded bytes do not start with %PDF.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            notPdf:
+              value:
+                errors:
+                  - code: PDF_EXTRACTION_FAILED
+                    message: Decoded content is not a PDF
+                    source: pdf
+    429-rate-limit:
+      description: Caller exceeded the endpoint's rate limit.
+      headers:
+        Retry-After:
+          description: Seconds to wait before retrying.
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            exceeded:
+              value:
+                errors:
+                  - code: RATE_LIMIT_EXCEEDED
+                    message: Rate limit exceeded. Retry after 1200 seconds.
+                    source: rate_limiter
+    500-internal:
+      description: Unexpected FDR service failure.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            failed:
+              value:
+                errors:
+                  - code: GENERATION_FAILED
+                    message: 'FDR generation failed. Reference: 550e8400-e29b-41d4-a716-446655440000'
+                    source: generation
+    503-unavailable:
+      description: Job store or PDF storage is unavailable.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            store:
+              value:
+                errors:
+                  - code: SERVICE_UNAVAILABLE
+                    message: Unable to persist job. Retry later.
+                    source: ''
+    404-not-found:
+      description: Job id is unknown, belongs to the other operation, is not visible to the caller, or expired after 24 hours.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            expired:
+              value:
+                errors:
+                  - code: REQUEST_NOT_FOUND
+                    message: Request ID not found or expired (24h TTL)
+                    source: requestId
+x-internal: false
+x-enable-proxy: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "641fc30",
+		"iasCommit": "dd3c0db",
 		"generatedAt": "2026-09-18"
 	},
 	"roots": {