@celigo/api-specs 0.2.201 → 0.2.203

package/dist/filedefinition.yml

@@ -13,8 +13,9 @@ info:
       They define how rows, columns, segments, and elements are parsed or generated,
       including delimiters, padding, and hierarchical rule structures.
 
-      EDI file definitions (X12 and EDIFACT formats) require a valid `globalId` that
-      maps to a known standard document definition, and may require an EDI license.
+      EDI file definitions (X12 and EDIFACT formats) carry a `globalId` that maps to a
+      known standard document definition; on an EDI-licensed account the server assigns
+      one when a create omits it.
 servers:
   - url: https://api.integrator.io
     description: Production (US / default region)
@@ -36,7 +37,7 @@ tags:
 
       Four formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),
       `delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats
-      require a `globalId` linking to a standard document definition.
+      carry a `globalId` linking to a standard document definition.
 
       ## File definition schema
 
@@ -204,9 +205,10 @@ paths:
           $ref: '#/components/responses/422-unprocessable-entity'
       x-celigo-ai-guidance:
         - |-
-          For EDI formats (`delimited/x12` or `delimited/edifact`), a valid `globalId`
-          is required when the account has an EDI license enabled. The `globalId` must
-          reference a known standard document definition.
+          For EDI formats (`delimited/x12` or `delimited/edifact`) on an EDI-licensed
+          account, the server assigns a `globalId` when the body omits one; a supplied
+          `globalId` must reference a known standard document definition, or the create
+          fails with 422 `invalid_global_id`.
         - |-
           For `format: fixed`, send `version`, `fixed.rowDelimiter` and `fixed.paddingChar`;
           without them the create fails with 422 and nothing is saved. Columns are read in
@@ -274,7 +276,8 @@ paths:
         Replaces the file definition with the provided configuration. This
         is a full replace -- include all fields you want to keep. `format`
         cannot be changed between `fixed` and `delimited` families after
-        creation, and `globalId` is immutable for EDI formats.
+        creation, and `globalId` is immutable for EDI formats: a PUT that sends a
+        different value, or omits it, keeps the stored id.
       operationId: updateFileDefinition
       tags:
         - File Definitions
@@ -1025,8 +1028,8 @@ components:
             - fixed
           x-enumDescriptions:
             delimited: Standard delimited files (CSV, TSV, etc.).
-            delimited/x12: EDI X12 format. Requires `globalId` when EDI license is enabled.
-            delimited/edifact: EDI EDIFACT format. Requires `globalId` when EDI license is enabled.
+            delimited/x12: EDI X12 format. Carries a `globalId`, assigned by the server when a create on an EDI-licensed account omits it.
+            delimited/edifact: EDI EDIFACT format. Carries a `globalId`, assigned by the server when a create on an EDI-licensed account omits it.
             fixed: Fixed-width positional format.
         documentType:
           type: string
@@ -1039,15 +1042,21 @@ components:
           description: EDI document type for acknowledgement documents.
         globalId:
           type: string
-          description: |-
-            Entry in the platform's registry of standard EDI document definitions that this
-            definition is built from. On an EDI-licensed account an X12 or EDIFACT create without
-            it fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't
-            have fails with 422 `invalid_global_id`. No public route lists the registry, so copy the
-            `globalId` of an existing definition for the same standard document. Immutable after
-            creation.
+          description: |
+            Global identifier mapping to a known EDI standard document definition.
+
+            For EDI formats (`delimited/x12` or `delimited/edifact`) on an account
+            with an EDI license, a create that omits it gets one assigned from the
+            EDI catalog, and a supplied value must be a catalog entry (an unknown one
+            fails the create with 422 `invalid_global_id`). Immutable after creation:
+            a PUT that sends a different value, or none, keeps the stored id.
           examples:
-            - Generic-4010-850-PurchaseOrder
+            - 3c7a8f2e-1234-5678-9abc-def012345678
+          x-celigo-ai-guidance:
+            - |-
+              Send the catalog globalId of the document when you know it. When it is omitted the
+              server picks the id, and a description naming another document type did not change
+              the pick — an X12 create described as an 856 got the same id as a bare X12 create.
         rules:
           type: array
           x-celigo-agent:

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: