@celigo/api-specs 0.2.1

package/dist/editransaction.yml

@@ -0,0 +1,1210 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: EDI Transactions
+  description: API for querying the Celigo EDI transaction log — per-document records surfaced by the B2B Manager dashboard.
+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: EDI Transactions
+    description: |-
+      Query the EDI transaction log surfaced by the B2B Manager dashboard.
+
+      Each record represents a single EDI document (one X12 transaction set or
+      one EDIFACT message) that was processed through a Celigo flow. The envelope
+      metadata (sender/receiver IDs, control numbers, document type, functional
+      acknowledgement status) is extracted during flow execution and indexed so
+      the B2B dashboard can render filterable activity lists.
+
+      Requires a B2B / EDI license on the account.
+
+      ## EDI transaction schema
+
+      {% openapi-schemas spec="editransaction" schemas="EDITransaction" grouped="true" %}
+paths:
+  /v1/ediTransactions:
+    patch:
+      x-internal: false
+      operationId: patchEdiTransactions
+      tags:
+        - EDI Transactions
+      summary: Update part of an EDI transaction
+      description: |-
+        Partially updates one or more EDI transaction records. Commonly used
+        to update the `faStatus` field (functional acknowledgment status).
+
+        The endpoint is lenient — when the `ediTransactions` array is empty,
+        missing, or contains IDs that don't match any existing records, the
+        response is `200` with `{"ediTransactions": []}` rather than a 400.
+        Callers should always supply `fileType` and a non-empty
+        `ediTransactions` array for meaningful results.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - ediTransactions
+                - fileType
+              properties:
+                ediTransactions:
+                  type: array
+                  items:
+                    type: object
+                    required:
+                      - _id
+                    properties:
+                      _id:
+                        type: string
+                        description: EDI transaction ID to update.
+                        examples:
+                          - 69ca6b7a42f275a91eab88bd
+                      faStatus:
+                        type: string
+                        description: |-
+                          Functional acknowledgment status to set. Only `accepted`
+                          and `rejected` are valid via PATCH — other values
+                          (`inProgress`, `notApplicable`, etc.) are system-managed
+                          and cause the record to be silently skipped.
+                        enum:
+                          - accepted
+                          - rejected
+                        x-enumDescriptions:
+                          accepted: Mark the transaction as accepted by the trading partner's FA.
+                          rejected: Mark the transaction as rejected by the trading partner's FA.
+                  description: Array of partial transaction updates.
+                fileType:
+                  type: string
+                  enum:
+                    - X12
+                    - EDIFACT
+                  x-enumDescriptions:
+                    X12: ANSI X12 EDI standard.
+                    EDIFACT: UN/EDIFACT EDI standard.
+                  description: EDI file type.
+            examples:
+              update_fa_status:
+                summary: Mark a transaction as FA received
+                value:
+                  fileType: X12
+                  ediTransactions:
+                    - _id: 69ca6b7a42f275a91eab88bd
+                      faStatus: accepted
+              batch_update:
+                summary: Update multiple transactions
+                value:
+                  fileType: X12
+                  ediTransactions:
+                    - _id: 69ca6b7a42f275a91eab88bd
+                      faStatus: accepted
+                    - _id: 69ca6b7a42f275a91eab88be
+                      faStatus: rejected
+      responses:
+        '200':
+          description: Updated transaction records.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ediTransactions:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/EDITransaction'
+              examples:
+                no_matches:
+                  summary: No records matched the supplied ids — empty echo envelope
+                  value:
+                    ediTransactions: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/ediTransactions/query:
+    post:
+      x-internal: false
+      operationId: queryEDITransactions
+      tags:
+        - EDI Transactions
+      summary: Query the EDI transaction log
+      description: |-
+        Returns EDI documents processed through B2B Manager flows, with envelope
+        metadata (sender/receiver IDs, control numbers), document type, direction,
+        and functional acknowledgement status. This is the data source behind the
+        B2B Manager "Transactions" dashboard.
+
+        Results are cursor-paginated — when more records exist beyond `limit`,
+        the response includes `pageToken.next`. Pass it back as `pageToken` in
+        the next request to get the next page. The server caps `limit` at 1000.
+
+        Use `fileType` with a dated window (`startDate`/`endDate`) to keep
+        result sets bounded. `faStatus` must be passed as an array when
+        filtering. Unknown filter fields are silently ignored. To fetch the
+        raw EDI file for a returned record, use
+        `POST /v1/jobs/{_flowJobId}/files/signedURL` with the record's
+        `s3Key`.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EDITransactionsQueryRequest'
+            examples:
+              default_last_30d:
+                summary: Last 30 days of X12 transactions
+                value:
+                  fileType: X12
+                  limit: 100
+                  startDate: 1742774400000
+              by_trading_partner:
+                summary: X12 transactions from one trading partner (by interchange sender ID)
+                value:
+                  fileType: X12
+                  interchangeSenderId: '1234567890'
+                  limit: 100
+                  startDate: 1742774400000
+              rejected_transactions:
+                summary: Rejected or failed transactions
+                value:
+                  fileType: X12
+                  faStatus:
+                    - rejected
+                    - failed
+                  limit: 100
+                  startDate: 1742774400000
+      responses:
+        '200':
+          description: |-
+            One page of EDI transaction records. When more records exist beyond
+            `limit`, `pageToken.next` is included for the next page.
+            `ediTransactions` is `[]` when no records match — the endpoint does
+            **not** return 204 on empty results.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDITransactionsQueryResponse'
+              examples:
+                empty:
+                  summary: No matching transactions
+                  value:
+                    ediTransactions: []
+                x12_record:
+                  summary: X12 850 inbound
+                  value:
+                    ediTransactions:
+                      - _id: 6a0377fcbfecf34a362e9be2
+                        _userId: 5e58483b68b52e5827d56a86
+                        _integrationId: 66cc9b31f2be816bf9377036
+                        _flowJobId: 6a05fe1675bab7047b42f047
+                        fileType: X12
+                        documentType: '850'
+                        documentNumber: PO03302026A
+                        direction: Inbound
+                        faStatus: inProgress
+                        sandbox: false
+                        s3Key: 7588296c08f440698d9d601792aebba5
+                        isaSenderId: '1234567890     '
+                        isaReceiverId: 'CELIGOLABZ     '
+                        gsSenderId: '1234567890'
+                        gsReceiverId: CELIGOLABZ
+                        controlNumber:
+                          interchange: '000000005'
+                          group: '1'
+                          transactionSet: '0004'
+                        lastModified: '2026-05-14T16:53:44.624Z'
+                edifact_record:
+                  summary: EDIFACT ORDERS inbound
+                  value:
+                    ediTransactions:
+                      - _id: 69f628898c43da1347a1ca2d
+                        _userId: 5e58483b68b52e5827d56a86
+                        _integrationId: 66cc9b31f2be816bf9377036
+                        _flowJobId: 6a05fdbf0f139ef519238dd7
+                        fileType: EDIFACT
+                        documentType: ORDERS
+                        documentNumber: '0032560422'
+                        direction: Inbound
+                        faStatus: notApplicable
+                        sandbox: false
+                        s3Key: 873e11b6fedd42c88498dc8ed59692d5
+                        unbSenderId: '3017581483'
+                        unbReceiverId: '7177587895'
+                        controlNumber:
+                          unb: '1'
+                          unh: '100001'
+                        lastModified: '2026-05-14T16:52:19.677Z'
+        '400':
+          description: The request body failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_filetype:
+                  value:
+                    errors:
+                      - code: invalid_filetype
+                        message: 'fileType is invalid. fileType should be one of the following: X12, EDIFACT'
+                invalid_limit_value:
+                  value:
+                    errors:
+                      - code: invalid_limit_value
+                        message: limit should be between 1 & 1000 inclusive
+                invalid_date_range:
+                  value:
+                    errors:
+                      - code: invalid_date_range
+                        message: please provide a valid date range
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/ediTransactions/{_ediTransactionId}/faDetails:
+    get:
+      x-internal: false
+      operationId: getEdiTransactionFaDetails
+      tags:
+        - EDI Transactions
+      summary: Get FA details for an EDI transaction
+      description: |-
+        Returns functional acknowledgment (FA) details for a specific EDI
+        transaction. FA details are only available for transactions with a
+        "Rejected" status in B2B Manager.
+      parameters:
+        - name: _ediTransactionId
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - 6a0377fcbfecf34a362e9be2
+          description: The EDI transaction ID.
+        - name: fileType
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - X12
+              - EDIFACT
+            x-enumDescriptions:
+              X12: ANSI X12 EDI standard.
+              EDIFACT: UN/EDIFACT EDI standard.
+          description: EDI file type.
+      responses:
+        '200':
+          description: FA detail envelope.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  faDetails:
+                    type: object
+                    properties:
+                      Interchange Control Number:
+                        type: string
+                        examples:
+                          - '000000005'
+                      Group:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            Group Control Number:
+                              type: string
+                              examples:
+                                - '1'
+                            Identifier Code:
+                              type: string
+                              examples:
+                                - FA
+                            Transaction:
+                              type: array
+                              items:
+                                type: object
+                                properties:
+                                  Transaction set Control Number:
+                                    type: string
+                                    examples:
+                                      - '0004'
+                                  Document Type:
+                                    type: string
+                                    examples:
+                                      - '850'
+                                  Errors:
+                                    type: array
+                                    items:
+                                      type: object
+                                      properties:
+                                        Segment ID:
+                                          type: string
+                                          examples:
+                                            - BEG
+                                        Element ID:
+                                          type: string
+                                          examples:
+                                            - BEG03
+                                        Error message:
+                                          type: string
+                                          examples:
+                                            - Mandatory data element missing
+                                        Data in error:
+                                          type: string
+                                          examples:
+                                            - REF*PO*
+                                        Segment error:
+                                          type: string
+                                          examples:
+                                            - '4'
+              examples:
+                rejected_997:
+                  summary: 997 rejection with segment-level errors
+                  value:
+                    faDetails:
+                      Interchange Control Number: '000000005'
+                      Group:
+                        - Group Control Number: '1'
+                          Identifier Code: FA
+                          Transaction:
+                            - Transaction set Control Number: '0004'
+                              Document Type: '850'
+                              Errors:
+                                - Segment ID: BEG
+                                  Element ID: BEG03
+                                  Error message: Mandatory data element missing
+                                  Data in error: ''
+                                  Segment error: '4'
+        '400':
+          description: |-
+            The `fileType` query parameter is present but not a valid value, or the
+            transaction's FA status is not `rejected` (FA details are only available
+            for rejected transactions).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_filetype:
+                  summary: fileType is not X12 or EDIFACT
+                  value:
+                    errors:
+                      - code: invalid_filetype
+                        message: 'fileType is invalid. fileType should be one of the following: X12, EDIFACT'
+                not_rejected:
+                  summary: Transaction is not in a rejected FA status
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Functional Acknowledgement Details can only be retrieved for a transaction with "FA Status" as "Rejected".
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The EDI transaction was not found, or the `fileType` query
+            parameter was omitted entirely (the server treats a missing
+            `fileType` as a lookup failure rather than a validation error).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: EdiTransaction not found.
+  /v1/ediTransactions/{_ediTransactionId}/mdn:
+    get:
+      x-internal: false
+      operationId: getEdiTransactionMdn
+      tags:
+        - EDI Transactions
+      summary: Get MDN details for an EDI transaction
+      description: |-
+        Returns AS2 Message Disposition Notification (MDN) metadata for a specific
+        EDI transaction record from the B2B Manager dashboard. The server reads the
+        stored MDN artifact associated with the transaction and returns its raw body
+        text together with a parsed disposition classification.
+
+        Get `_id` from a record returned by `POST /v1/ediTransactions/query`.
+      parameters:
+        - name: _ediTransactionId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a0377fcbfecf34a362e9be2
+          description: The EDI transaction ID.
+      responses:
+        '200':
+          description: MDN metadata for the transaction.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDITransactionMdnResponse'
+              examples:
+                processed:
+                  summary: MDN reporting successful processing
+                  value:
+                    mdnStatusMessage: |-
+                      ------70B008BC93BAB50F580B205FC5CEF948
+                      Content-Type: multipart/report;Report-Type=disposition-notification;boundary=yFK5DJ9f
+
+                      --yFK5DJ9f
+                      Content-Type: text/plain
+                      Content-Transfer-Encoding: 7bit
+
+                      The EDI message has been received successfully.
+                      --yFK5DJ9f
+                      Content-Type: message/disposition-notification
+                      Content-Transfer-Encoding: 7bit
+
+                      Reporting-UA: integrator.io
+                      Original-Recipient: rfc822; partner-as2-id
+                      Final-Recipient: rfc822; partner-as2-id
+                      Original-Message-ID: <message-id@integrator.io>
+                      Disposition: automatic-action/MDN-sent-automatically;processed
+                      Received-Content-MIC: jVA1LAPZqJjQBEs/yBmHe/T3wwqMlJlh4gpLSdjO9U8=, sha256
+
+                      --yFK5DJ9f--
+                    mdnTimestamp: '2026-05-21T21:32:52.000Z'
+                    mdnDisposition: processed
+                error:
+                  summary: MDN reporting a processing error
+                  value:
+                    mdnStatusMessage: |-
+                      ------A8EE28C63B41510F2EA6087D3B35403E
+                      Content-Type: multipart/report;Report-Type=disposition-notification;boundary=lEeEqSs1
+
+                      --lEeEqSs1
+                      Content-Type: text/plain
+                      Content-Transfer-Encoding: 7bit
+
+                      There was an error receiving the EDI message. Error: AS2 decryption failed.
+                      --lEeEqSs1
+                      Content-Type: message/disposition-notification
+                      Content-Transfer-Encoding: 7bit
+
+                      Reporting-UA: integrator.io
+                      Original-Recipient: rfc822; partner-as2-id
+                      Final-Recipient: rfc822; partner-as2-id
+                      Original-Message-ID: <message-id@integrator.io>
+                      Disposition: automatic-action/MDN-sent-automatically;processed/error: decryption-failed
+
+                      --lEeEqSs1--
+                    mdnTimestamp: '2026-05-21T21:32:52.000Z'
+                    mdnDisposition: error
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The EDI transaction was not found, has no associated MDN artifact, or
+            the MDN artifact is no longer available in storage.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                transaction_not_found:
+                  value:
+                    errors:
+                      - code: transaction_not_found_for_id
+                        message: No transaction found for the given ID.
+                file_unavailable:
+                  value:
+                    errors:
+                      - code: edi_transaction_file_unavailable
+                        message: The requested file for this transaction is not available or has expired.
+        '500':
+          description: An unexpected error occurred while retrieving the MDN.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                download_error:
+                  value:
+                    errors:
+                      - code: edi_file_download_error
+                        message: An error occurred while retrieving the EDI file. Please try again later.
+  /v1/edi/documents/{documentNumber}/ediFile:
+    get:
+      x-internal: false
+      operationId: downloadEdiFile
+      tags:
+        - EDI Transactions
+      summary: Download an EDI file
+      description: |-
+        Downloads the raw EDI file content for a specific document number.
+
+        The `documentType` query parameter is required and must be the EDI
+        document type code — for X12, the numeric transaction-set ID as a
+        string (e.g. `850`, `810`, `856`, `997`); for EDIFACT, the UNH01
+        message type (e.g. `ORDERS`, `INVOIC`, `DESADV`, `CONTRL`).
+
+        The server uses `documentType` + `documentNumber` together to locate
+        the transaction record and return the associated raw EDI file.
+
+        Get `documentNumber` and `documentType` from a transaction record
+        returned by `POST /v1/ediTransactions/query`. Alternatively,
+        download via `POST /v1/jobs/{_flowJobId}/files/signedURL` using
+        the `s3Key` from the transaction record.
+      parameters:
+        - name: documentNumber
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - PO03302026A
+          description: |-
+            The business document number that identifies the EDI transaction
+            (e.g. a purchase-order number from an 850's BEG03). Matches the
+            `documentNumber` field on an EDI transaction record.
+        - name: documentType
+          in: query
+          required: true
+          schema:
+            type: string
+          description: |-
+            The EDI document type code. For X12, this is the numeric
+            transaction-set ID as a string (e.g. `850`, `810`, `856`, `997`).
+            For EDIFACT, this is the UNH01 message type (e.g. `ORDERS`,
+            `INVOIC`, `DESADV`, `CONTRL`).
+
+            Values like `X12` or `EDIFACT` are **not** valid here — those
+            identify the EDI standard family, not the document type.
+          examples:
+            x12_850:
+              value: '850'
+              summary: X12 Purchase Order
+            x12_810:
+              value: '810'
+              summary: X12 Invoice
+            edifact_orders:
+              value: ORDERS
+              summary: EDIFACT Purchase Order
+      responses:
+        '200':
+          description: Raw EDI file content.
+          content:
+            text/plain:
+              schema:
+                type: string
+        '400':
+          description: The request failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing:
+                  summary: documentType query parameter missing
+                  value:
+                    errors:
+                      - code: document_type_required
+                        message: The "documentType" query parameter is required to process this request.
+                invalid:
+                  summary: Invalid document type value
+                  value:
+                    errors:
+                      - code: edi_invalid_document_type
+                        message: X12 is not a valid document type. Please verify the value and try again.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No transaction was found matching the provided document type and
+            document number combination.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: edi_transaction_not_found
+                        message: No transaction was found matching the provided document type and document number.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    EDITransaction:
+      type: object
+      required:
+        - _id
+        - _userId
+        - fileType
+        - documentType
+        - direction
+        - faStatus
+        - s3Key
+        - lastModified
+        - controlNumber
+      description: |-
+        A single EDI transaction record indexed by the B2B Manager dashboard.
+
+        Represents one EDI document — one X12 transaction set (e.g. a single 850
+        purchase order) or one EDIFACT message (e.g. a single ORDERS message) —
+        processed through a Celigo flow. Envelope metadata is extracted from the
+        ISA/GS (X12) or UNB/UNG (EDIFACT) segments at flow execution time.
+        X12 and EDIFACT records share common fields (`_id`, `documentType`,
+        `direction`, `faStatus`, etc.) but use different field names for
+        sender/receiver IDs and control numbers — see individual field
+        descriptions.
+
+        Transaction records are retained for a license-dependent window (30, 60,
+        or 180 days after last modification) and then expire; expired transactions
+        no longer appear in query results. Unlike most resources, these records
+        are not soft-deleted into the recycle bin, and `createdAt` / `deletedAt`
+        are not returned.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the transaction record.
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: |-
+            Timestamp when the record was last updated (e.g. by an faStatus
+            change). Also restarts the retention window.
+          examples:
+            - '2026-04-15T14:30:15.123Z'
+        _userId:
+          type: string
+          format: objectId
+          description: Owning account user ID.
+          x-celigo-refModel: users
+          examples:
+            - 5e58483b68b52e5827d56a86
+        _integrationId:
+          type: string
+          format: objectId
+          description: |-
+            Integration that processed this transaction. Omitted on records whose
+            flow ran outside an integration context.
+          x-celigo-refModel: integrations
+          examples:
+            - 66cc9b31f2be816bf9377036
+        _flowJobId:
+          type: string
+          format: objectId
+          description: |-
+            Flow-run Job ID that produced this record. Combine with `s3Key` and
+            `POST /v1/jobs/{_flowJobId}/files/signedURL` (body
+            `{ "fileIds": ["<s3Key>"] }`) to download the raw EDI file.
+          x-celigo-refModel: jobs
+          examples:
+            - 6a05fe1675bab7047b42f047
+        _faFlowJobId:
+          type: string
+          format: objectId
+          description: |-
+            Job ID of the flow run that processed the functional acknowledgement
+            (997 / CONTRL) for this transaction. Present only once an FA has been
+            received and processed.
+          x-celigo-refModel: jobs
+          examples:
+            - 6a05fdbf0f139ef519238dd7
+        fileType:
+          type: string
+          enum:
+            - X12
+            - EDIFACT
+          x-enumDescriptions:
+            X12: ANSI X12 EDI standard.
+            EDIFACT: UN/EDIFACT EDI standard.
+          description: EDI standard family of this transaction.
+        documentType:
+          type: string
+          description: |-
+            EDI document type. X12: usually the numeric transaction-set ID as a
+            string (`"850"`, `"810"`, `"856"`, `"997"`). EDIFACT: UNH01 message
+            type (`"ORDERS"`, `"INVOIC"`, `"DESADV"`, `"CONTRL"`). Not a closed
+            set — file definitions can supply partner-specific document codes
+            instead (e.g. `"PO"`, `"SH"`, `"IB"`, `"OSTRPT"`), so treat this as a
+            free-form label.
+          examples:
+            - '850'
+        documentNumber:
+          type: string
+          description: |-
+            Business document number extracted from the transaction set
+            (e.g. purchase-order number from BEG03 in an 850 / BGM02 in an
+            ORDERS). Omitted when the document carries no business number or the
+            file definition does not extract one — most functional
+            acknowledgements (997 / CONTRL / FA) and many status or inventory
+            documents. May also be an empty string.
+          examples:
+            - PO03302026A
+        direction:
+          type: string
+          enum:
+            - Inbound
+            - Outbound
+          x-enumDescriptions:
+            Inbound: Document received from a trading partner.
+            Outbound: Document sent to a trading partner.
+          description: Whether the document was received from or sent to a trading partner.
+        faStatus:
+          type: string
+          enum:
+            - inProgress
+            - notApplicable
+            - notReceived
+            - accepted
+            - acceptedWithErrors
+            - rejected
+            - failed
+          x-enumDescriptions:
+            inProgress: Awaiting functional acknowledgment from the trading partner.
+            notApplicable: No functional acknowledgment expected — the document is itself an FA, or the trading partner does not require one.
+            notReceived: Functional acknowledgment expected but not yet received.
+            accepted: Functional acknowledgment received and transaction was accepted.
+            acceptedWithErrors: Functional acknowledgment received with errors but transaction was accepted.
+            rejected: Functional acknowledgment received and transaction was rejected.
+            failed: Functional acknowledgment processing failed.
+          description: |-
+            Latest known functional-acknowledgement status for the transaction set.
+            Updates asynchronously as 997 (X12) / CONTRL (EDIFACT) acknowledgements
+            arrive from the trading partner, so this value may change without a
+            new flow run.
+        s3Key:
+          type: string
+          description: |-
+            Opaque file identifier for the raw EDI document in object storage.
+            The value may be a hex token or an EDI file name — treat it as
+            opaque, not as an S3 path or a fixed format. Combine with
+            `_flowJobId` and call
+            `POST /v1/jobs/{_flowJobId}/files/signedURL` with body
+            `{ "fileIds": ["<s3Key>"] }` to obtain a short-lived signed
+            download URL.
+          examples:
+            - 7588296c08f440698d9d601792aebba5
+        faS3Key:
+          type: string
+          description: |-
+            Opaque file identifier for the stored functional-acknowledgement
+            (997 / CONTRL) file. Present only once an FA has been received.
+            One acknowledgement file can cover many transactions, which then
+            share the same `faS3Key`. Download it via
+            `GET /v1/ediTransactions/{_ediTransactionId}/ediFile?type=fa`.
+          examples:
+            - 9a7c3e14b2af45d8bc0e6090c5be6afa
+        mdnStatus:
+          type: string
+          enum:
+            - received
+            - sent
+          x-enumDescriptions:
+            received: An MDN was received from the trading partner, confirming an outbound transmission.
+            sent: An MDN was sent to the trading partner, acknowledging an inbound transmission.
+          description: |-
+            AS2 Message Disposition Notification status. Present only on AS2
+            transactions. `received` appears on outbound transactions (the partner
+            returned an MDN); `sent` appears on inbound transactions (Celigo
+            returned an MDN to the partner).
+        mdnS3Key:
+          type: string
+          description: |-
+            Opaque file identifier for the stored AS2 MDN artifact. Received MDNs
+            (`mdnStatus: received`) use a UUID; sent MDNs store the MDN file name
+            or a hex token — treat the value as opaque. Present only on AS2
+            transactions that have an MDN. Retrieve the parsed MDN via
+            `GET /v1/ediTransactions/{_ediTransactionId}/mdn`.
+          examples:
+            - 70b008bc-93ba-b50f-580b-205fc5cef948
+        isaSenderId:
+          type: string
+          description: |-
+            X12 only. ISA06 Interchange Sender ID. On inbound records this is the
+            fixed-width 15-character value as received (space-padded); outbound
+            records store the configured ID unpadded. Absent on EDIFACT records
+            (see `unbSenderId`).
+          examples:
+            - '1234567890     '
+        isaReceiverId:
+          type: string
+          description: |-
+            X12 only. ISA08 Interchange Receiver ID. On inbound records this is
+            the fixed-width 15-character value as received (space-padded);
+            outbound records store the configured ID unpadded. Absent on EDIFACT
+            records (see `unbReceiverId`).
+          examples:
+            - 'CELIGOLABZ     '
+        gsSenderId:
+          type: string
+          description: X12 only. GS02 Application Sender's Code.
+          examples:
+            - '1234567890'
+        gsReceiverId:
+          type: string
+          description: X12 only. GS03 Application Receiver's Code.
+          examples:
+            - CELIGOLABZ
+        unbSenderId:
+          type: string
+          description: |-
+            EDIFACT only. UNB02 sender identification. Absent on X12 records
+            (see `isaSenderId`).
+          examples:
+            - '3017581483'
+        unbReceiverId:
+          type: string
+          description: |-
+            EDIFACT only. UNB03 receiver identification. Absent on X12 records
+            (see `isaReceiverId`).
+          examples:
+            - '7177587895'
+        controlNumber:
+          type: object
+          description: |-
+            EDI control numbers extracted from the envelope. The property names
+            differ by `fileType`: X12 records use `interchange`, `group`, and
+            `transactionSet`; EDIFACT records use `unb` and `unh` (and `ung`
+            when a UNG group is present).
+          properties:
+            interchange:
+              type: string
+              description: X12 only. ISA13 interchange control number.
+              examples:
+                - '000000005'
+            group:
+              type: string
+              description: X12 only. GS06 group control number.
+              examples:
+                - '1'
+            transactionSet:
+              type: string
+              description: |-
+                X12 only. ST02 transaction-set control number. Occasionally
+                stored with a trailing segment terminator and/or CR (e.g.
+                `"0004~\r"` instead of `"0004"`) — strip trailing non-alphanumeric
+                characters when comparing.
+              examples:
+                - '0004'
+            unb:
+              type: string
+              description: EDIFACT only. UNB05 interchange control reference.
+              examples:
+                - '1'
+            ung:
+              type: string
+              description: |-
+                EDIFACT only. UNG05 group reference number. Absent when no UNG
+                group is present in the interchange.
+              examples:
+                - '1'
+            unh:
+              type: string
+              description: EDIFACT only. UNH01 message reference number.
+              examples:
+                - '100001'
+    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
+    EDITransactionsQueryRequest:
+      type: object
+      description: |-
+        Filter for `POST /v1/ediTransactions/query`. All fields are optional.
+        Results are narrowed by `fileType`, `interchangeSenderId`,
+        `interchangeReceiverId`, `documentNumber`, `faStatus`, and the
+        `startDate`/`endDate` window. `direction`, `documentType`, and
+        `_integrationId` are accepted but not applied server-side (filter on those
+        client-side). Records come back newest-first by `lastModified` and are
+        cursor-paginated via `pageToken`.
+      properties:
+        fileType:
+          type: string
+          enum:
+            - X12
+            - EDIFACT
+          x-enumDescriptions:
+            X12: ANSI X12 EDI standard.
+            EDIFACT: UN/EDIFACT EDI standard.
+          description: |-
+            EDI standard family. Defaults to `X12` when omitted — set
+            `fileType: EDIFACT` explicitly to query EDIFACT records.
+        interchangeSenderId:
+          type: string
+          description: |-
+            Filter by interchange sender ID — exact match against the record's
+            `isaSenderId` (X12 ISA06). Applied server-side.
+          examples:
+            - '1234567890'
+        interchangeReceiverId:
+          type: string
+          description: |-
+            Filter by interchange receiver ID — exact match against the record's
+            `isaReceiverId` (X12 ISA08). Applied server-side.
+          examples:
+            - CELIGOLABZ
+        direction:
+          type: string
+          enum:
+            - Inbound
+            - Outbound
+          x-enumDescriptions:
+            Inbound: Document received from a trading partner.
+            Outbound: Document sent to a trading partner.
+          description: |-
+            Transaction direction. Accepted by the endpoint but not applied as a
+            server-side filter — the result set is unaffected; filter client-side.
+        documentType:
+          type: string
+          description: |-
+            EDI document type code. For X12 this is the numeric transaction-set ID
+            as a string (e.g. `"850"`, `"810"`, `"856"`, `"997"`); for EDIFACT the
+            UNH01 message type (e.g. `"ORDERS"`, `"INVOIC"`, `"DESADV"`, `"CONTRL"`).
+            Accepted but not applied as a server-side filter — the result set is
+            unaffected; filter client-side.
+          examples:
+            - '850'
+        documentNumber:
+          type: string
+          description: |-
+            Business document number to filter on — matches the `documentNumber`
+            field extracted from the transaction set (e.g. a purchase-order number
+            from an 850's BEG03).
+          examples:
+            - PO03302026A
+        _integrationId:
+          type: string
+          format: objectId
+          description: |-
+            Integration the transaction was processed by. Accepted but not applied
+            as a server-side filter — the result set is unaffected; filter
+            client-side.
+          x-celigo-refModel: integrations
+          examples:
+            - 66cc9b31f2be816bf9377036
+        faStatus:
+          type: array
+          items:
+            type: string
+            enum:
+              - inProgress
+              - notApplicable
+              - notReceived
+              - accepted
+              - acceptedWithErrors
+              - rejected
+              - failed
+          x-enumDescriptions:
+            inProgress: Acknowledgment is pending from the trading partner
+            notApplicable: Transaction type does not require a functional acknowledgment
+            notReceived: Acknowledgment window expired without a response
+            accepted: Trading partner accepted the transaction without errors
+            acceptedWithErrors: Trading partner accepted but reported non-fatal errors
+            rejected: Trading partner rejected the transaction entirely
+            failed: Acknowledgment processing failed due to a system error
+          description: |-
+            Filter by functional acknowledgment status. Pass an array of one or
+            more values to match. Must be an array, not a bare string. Omit to
+            include all statuses.
+        startDate:
+          type: integer
+          format: int64
+          description: |-
+            Lower bound of the `lastModified` window, as epoch milliseconds.
+            The CLI converts ISO-8601 date strings to epoch-ms before calling.
+            When omitted, the server applies an internal default window.
+          examples:
+            - 1742774400000
+        endDate:
+          type: integer
+          format: int64
+          description: |-
+            Upper bound of the `lastModified` window, as epoch milliseconds.
+            Must be greater than `startDate`.
+          examples:
+            - 1745452800000
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 1000
+          description: |-
+            Maximum number of records to return per page. Server-enforced
+            range is 1–1000.
+            When more records exist beyond the limit, the response includes a
+            `pageToken.next` cursor for the next page.
+          examples:
+            - 100
+        pageToken:
+          type: string
+          description: |-
+            Opaque cursor from a previous response's `pageToken.next`. Pass
+            this value to retrieve the next page of results. Omit on the
+            first call.
+    EDITransactionsQueryResponse:
+      type: object
+      description: |-
+        One page of EDI transaction records matching the request filter. When
+        more records exist beyond the `limit`, `pageToken.next` contains an
+        opaque cursor to pass back on the next request for the next page.
+      properties:
+        ediTransactions:
+          type: array
+          description: |-
+            Matching EDI transaction records, newest first by `lastModified`.
+            Empty array when no records match — the endpoint does not switch to
+            204 for empty results.
+          items:
+            $ref: '#/components/schemas/EDITransaction'
+        pageToken:
+          type: object
+          description: |-
+            Pagination cursor. Present only when more records exist beyond
+            the current page. Absent on the last (or only) page.
+          properties:
+            next:
+              type: string
+              description: |-
+                Opaque cursor string. Pass as `pageToken` in the next request
+                body to retrieve the next page.
+    EDITransactionMdnResponse:
+      type: object
+      description: |-
+        AS2 Message Disposition Notification (MDN) metadata for an EDI transaction.
+        The server reads the stored MDN artifact and returns the raw status message
+        body together with a parsed disposition classification.
+      properties:
+        mdnStatusMessage:
+          type: string
+          description: |-
+            Full raw MDN body text, including the MIME headers and the `Disposition:`
+            line from the disposition-notification part.
+        mdnTimestamp:
+          type: string
+          format: date-time
+          description: |-
+            Timestamp of the stored MDN artifact — its last-modified time when
+            available, otherwise the transaction's `lastModified`.
+          examples:
+            - '2026-05-21T21:32:52.000Z'
+        mdnDisposition:
+          type: string
+          enum:
+            - processed
+            - warning
+            - error
+            - failure
+          x-enumDescriptions:
+            processed: MDN indicates the partner processed the message successfully.
+            warning: MDN reports processed with a warning modifier.
+            error: MDN reports an error modifier.
+            failure: MDN reports a failure modifier.
+          description: |-
+            Disposition classification parsed from the modifier on the `Disposition:`
+            header in `mdnStatusMessage` (the status token after the disposition
+            type, e.g. `processed` or `processed/error`).
+      required:
+        - mdnStatusMessage
+        - mdnTimestamp
+        - mdnDisposition
+  responses:
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    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