@celigo/api-specs 0.2.25 → 0.2.27

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