@celigo/api-specs 0.2.202 → 0.2.203

package/dist/filedefinitionrules.yml

@@ -21,8 +21,10 @@ tags:
     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`.
+      Submit endpoints take the PDF as a `multipart/form-data` file part
+      (or the legacy base64 JSON body) and 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.
@@ -32,7 +34,7 @@ tags:
 
       ## File definition rules schemas
 
-      {% openapi-schemas spec="filedefinitionrules" schemas="FdrSubmitRequest,FileDefinitionGenerationJob,FileDefinitionParsingJob" grouped="true" %}
+      {% openapi-schemas spec="filedefinitionrules" schemas="FdrSubmitUpload,FdrSubmitRequest,FileDefinitionGenerationJob,FileDefinitionParsingJob" grouped="true" %}
 paths:
   /v1/filedefinitionrules/generate:
     post:
@@ -46,11 +48,18 @@ paths:
         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).
+        results. Upload the PDF as a `multipart/form-data` file part; the
+        base64 JSON body is still accepted. Rate-limited to 10 submissions per
+        caller per hour (administrators bypass the limit).
       requestBody:
         required: true
         content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/FdrSubmitUpload'
+            encoding:
+              pdf:
+                contentType: application/pdf
           application/json:
             schema:
               $ref: '#/components/schemas/FdrSubmitRequest'
@@ -179,11 +188,18 @@ paths:
         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).
+        results. Upload the PDF as a `multipart/form-data` file part; the
+        base64 JSON body is still accepted. Rate-limited to 10 submissions per
+        caller per hour (administrators bypass the limit).
       requestBody:
         required: true
         content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/FdrSubmitUpload'
+            encoding:
+              pdf:
+                contentType: application/pdf
           application/json:
             schema:
               $ref: '#/components/schemas/FdrSubmitRequest'
@@ -349,20 +365,52 @@ components:
       type: http
       scheme: bearer
   schemas:
+    FdrSubmitUpload:
+      type: object
+      additionalProperties: false
+      required:
+        - pdf
+        - documentType
+      description: |-
+        Multipart form for submitting an EDI specification PDF. Send exactly
+        these two parts; any other part fails with `400 INVALID_REQUEST`.
+      properties:
+        pdf:
+          type: string
+          format: binary
+          contentMediaType: application/pdf
+          description: |-
+            EDI specification PDF, sent as a file part. Bytes that don't start
+            with `%PDF` fail with `422 PDF_EXTRACTION_FAILED`, and files over
+            50 MB with `413 PAYLOAD_TOO_LARGE`. A scanned or image-only PDF is
+            accepted, and the job then fails with `DETECTION_FAILED`.
+        documentType:
+          type: integer
+          description: |-
+            X12 transaction set number (e.g. 850), or 0 to auto-detect an
+            EDIFACT specification from the PDF contents. Same rules as the
+            JSON body's `documentType`.
+          examples:
+            - 850
     FdrSubmitRequest:
       type: object
+      additionalProperties: false
       required:
         - pdf
         - documentType
+      description: |-
+        JSON body carrying the PDF as base64. The service still accepts it,
+        but a multipart upload avoids the base64 size overhead. Any other
+        field fails with `400 INVALID_REQUEST`.
       properties:
         pdf:
           type: string
           description: |-
-            Base64-encoded EDI specification PDF. Must decode to a text-bearing
-            PDF: a scanned or image-only document is accepted, and the job then
-            fails with `DETECTION_FAILED`. A value that isn't base64 or doesn't
-            decode to a PDF is rejected with `422 PDF_EXTRACTION_FAILED`, and
-            encoded payloads over 50 MB with `413 PAYLOAD_TOO_LARGE`.
+            Base64-encoded EDI specification PDF; a `data:application/pdf;base64,`
+            prefix is stripped. A value that isn't base64 or doesn't decode to a
+            PDF fails with `422 PDF_EXTRACTION_FAILED`, and a decoded PDF over
+            50 MB with `413 PAYLOAD_TOO_LARGE`. A scanned or image-only PDF is
+            accepted, and the job then fails with `DETECTION_FAILED`.
         documentType:
           type: integer
           description: |-
@@ -393,13 +441,13 @@ components:
         - SERVICE_UNAVAILABLE
       x-enumDescriptions:
         INVALID_DOCUMENT_TYPE: documentType is not 0 and not a supported X12 set (400), or a failed job's PDF is not the submitted documentType
-        INVALID_REQUEST: Request body failed schema validation
+        INVALID_REQUEST: Request body failed validation — wrong Content-Type, malformed JSON, a missing pdf or documentType, or an unexpected field
         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
+        PAYLOAD_TOO_LARGE: The PDF, or the multipart body carrying it, 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
+        PDF_EXTRACTION_FAILED: pdf is not valid base64 or its bytes do not start with %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, including a PDF with no text (a scanned or image-only one)
         GENERATION_FAILED: Unexpected pipeline or server failure
@@ -419,7 +467,7 @@ components:
           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`).
+          description: Field or component that produced the error (`pdf`, `documentType`, `body`, `Content-Type`, `Authorization`, `requestId`, `rate_limiter`, `generation`), or the name of an unexpected field.
     Error:
       type: object
       additionalProperties: false
@@ -605,7 +653,12 @@ components:
           $ref: '#/components/schemas/FileDefinitionDocumentTypes'
   responses:
     400-bad-request:
-      description: Invalid documentType or request body failed validation.
+      description: |-
+        Invalid documentType, or the request body failed validation: a
+        Content-Type other than multipart/form-data or JSON, malformed JSON,
+        a missing `pdf` file part or `documentType`, or an unexpected
+        field. documentType is checked after the PDF bytes, so a
+        non-PDF upload fails with 422 even when documentType is also invalid.
       content:
         application/json:
           schema:
@@ -617,6 +670,26 @@ components:
                   - 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
+            missingPdfPart:
+              summary: Multipart body without a pdf file part
+              value:
+                errors:
+                  - code: INVALID_REQUEST
+                    message: Field is required
+                    source: pdf
+            unexpectedField:
+              summary: Multipart body with an extra field
+              value:
+                errors:
+                  - code: INVALID_REQUEST
+                    message: 'Unexpected field: foo'
+                    source: foo
+            unsupportedContentType:
+              value:
+                errors:
+                  - code: INVALID_REQUEST
+                    message: Content-Type must be multipart/form-data or JSON
+                    source: Content-Type
     401-unauthorized:
       description: Missing Authorization header or scheme is not Bearer JWT.
       content:
@@ -644,7 +717,10 @@ components:
                     message: Bearer token has expired
                     source: Authorization
     413-payload-too-large:
-      description: Encoded pdf exceeds the 50 MB limit.
+      description: |-
+        The PDF exceeds the 50 MB limit. A multipart body is rejected before
+        it is read when its Content-Length exceeds the limit plus a small
+        allowance for the form envelope.
       content:
         application/json:
           schema:
@@ -654,10 +730,10 @@ components:
               value:
                 errors:
                   - code: PAYLOAD_TOO_LARGE
-                    message: Base64-encoded PDF exceeds 50 MB limit
+                    message: PDF exceeds 50 MB limit
                     source: pdf
     422-unprocessable-entity:
-      description: pdf is not valid base64 or decoded bytes do not start with %PDF.
+      description: The base64 `pdf` does not decode, or the uploaded or decoded bytes do not start with %PDF.
       content:
         application/json:
           schema:
@@ -667,8 +743,9 @@ components:
               value:
                 errors:
                   - code: PDF_EXTRACTION_FAILED
-                    message: Decoded content is not a PDF
+                    message: uploaded bytes are not a valid PDF (missing %PDF header)
                     source: pdf
+                correlationId: 550e8400-e29b-41d4-a716-446655440000
     429-rate-limit:
       description: Caller exceeded the endpoint's rate limit.
       headers: