@celigo/api-specs 0.2.158 → 0.2.160

package/dist/editransaction.yml

@@ -561,6 +561,145 @@ paths:
                     errors:
                       - code: invalid_ref
                         message: EdiTransaction not found.
+  /v1/ediTransactions/{_ediTransactionId}/ediFile:
+    get:
+      x-internal: false
+      operationId: getEdiTransactionFileSignedUrl
+      tags:
+        - EDI Transactions
+      summary: Get a signed URL to download an EDI transaction file
+      description: |-
+        Returns a short-lived pre-signed S3 URL for the primary EDI document
+        (`type=nonFa`) or the functional-acknowledgement file (`type=fa`) of
+        one EDI transaction record. Fetch the URL with a plain GET right away
+        and never store it — request a new URL for a later download.
+
+        Get `_id` from a record returned by `POST /v1/ediTransactions/query`.
+        The id alone identifies the record for both X12 and EDIFACT; `type` is
+        the only query parameter.
+
+        The acknowledgement file exists only once the trading partner's 997
+        (X12) or CONTRL (EDIFACT) was ingested — a record whose `faStatus` is
+        `notReceived`, `inProgress` or `notApplicable` has none. Files are kept
+        for the account's data retention period; afterwards the record is still
+        listed but the download answers `edi_transaction_file_unavailable`.
+
+        This is the only file-download route that an application acting for a
+        signed-in user can also reach; the document-number downloads under
+        `/v1/edi/documents` are public-API only.
+
+        Downloads are rate limited per user.
+      parameters:
+        - name: _ediTransactionId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a0377fcbfecf34a362e9be2
+          description: The EDI transaction ID.
+        - name: type
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - nonFa
+              - fa
+            x-enumDescriptions:
+              nonFa: Primary business document (850, 810, ORDERS, etc.)
+              fa: Functional acknowledgement file (997 for X12, CONTRL for EDIFACT)
+          description: |-
+            Which file to download — the original EDI business document or the
+            functional acknowledgement the trading partner returned for it.
+      responses:
+        '200':
+          description: Pre-signed download URL for the requested file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDITransactionFileSignedUrlResponse'
+              examples:
+                non_fa:
+                  summary: Signed URL for a primary business document
+                  value:
+                    signedURL: https://integrator-files.s3.us-east-1.amazonaws.com/26338886c17c45e1840e0a7ec81a1a2d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAEXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T165300Z&X-Amz-Security-Token=EXAMPLE-STS-TOKEN&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
+                fa:
+                  summary: Signed URL for a functional-acknowledgement file
+                  value:
+                    signedURL: https://integrator-files.s3.us-east-1.amazonaws.com/9a7c3e14b2af45d8bc0e6090c5be6afa?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAEXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T165300Z&X-Amz-Security-Token=EXAMPLE-STS-TOKEN&X-Amz-SignedHeaders=host&X-Amz-Signature=7d0e5a9d2f4b6c8e1a3f7b0c5e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a
+        '400':
+          description: The request failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_type:
+                  summary: type query parameter missing
+                  value:
+                    errors:
+                      - code: invalid_type
+                        message: The "type" query parameter must be either "nonFa" or "fa".
+                invalid_type:
+                  summary: Invalid type value
+                  value:
+                    errors:
+                      - code: invalid_type
+                        message: The "type" query parameter must be either "nonFa" or "fa".
+                invalid_id:
+                  summary: Invalid transaction ID
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _transactionId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The EDI transaction was not found, or the requested file is not
+            available for it — no acknowledgement was ingested, the record
+            carries no file reference, or the object aged out of 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.
+        '422':
+          description: The account has no B2B Manager (EDI) license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                license:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+        '500':
+          description: An unexpected error occurred while generating the signed URL.
+          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/ediTransactions/{_ediTransactionId}/mdn:
     get:
       x-internal: false
@@ -683,22 +822,30 @@ paths:
       operationId: downloadEdiFile
       tags:
         - EDI Transactions
-      summary: Download an EDI file
+      summary: Download an EDI file by document number
       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`).
+        Streams the raw EDI document whose business document number and
+        document type match — the file an export parsed or an import
+        generated. Acknowledgement files are not served here; use
+        `GET /v1/ediTransactions/{_ediTransactionId}/ediFile?type=fa`.
 
-        The server uses `documentType` + `documentNumber` together to locate
-        the transaction record and return the associated raw EDI file.
+        A document number is not unique: the same purchase-order number can
+        exist for several trading partners, in both directions, in sandbox and
+        production, or across integrations. Add lookup filters to pick one —
+        they AND together — and when several records still match, the latest
+        by `lastModified` is returned. Partner ids use the same names as
+        `POST /v1/ediTransactions/query`: `interchangeSenderId` /
+        `interchangeReceiverId` for X12, `unbSenderId` / `unbReceiverId` for
+        EDIFACT. When no document number is known, use
+        `GET /v1/edi/documents/ediFile` with filters alone.
 
         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.
+        returned by `POST /v1/ediTransactions/query`; a record's `_id` is the
+        unambiguous alternative through
+        `GET /v1/ediTransactions/{_ediTransactionId}/ediFile`.
+
+        Public-API route only: there is no equivalent for applications acting
+        with a signed-in user's session. Downloads are rate limited per user.
       parameters:
         - name: documentNumber
           in: path
@@ -710,20 +857,20 @@ paths:
           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.
+            `documentNumber` field on an EDI transaction record; letters are
+            uppercased.
         - 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.
+            EDI document type code — for X12 the numeric transaction-set ID as
+            a string (`850`, `810`, `856`, `997`); for EDIFACT the UNH01 message
+            type (`ORDERS`, `INVOIC`, `DESADV`, `CONTRL`). Case-insensitive. It
+            also selects the EDI standard the lookup runs against. `X12` and
+            `EDIFACT` name the standard, not a document type, and are rejected
+            here.
           examples:
             x12_850:
               value: '850'
@@ -734,13 +881,25 @@ paths:
             edifact_orders:
               value: ORDERS
               summary: EDIFACT Purchase Order
+        - $ref: '#/components/parameters/FileType'
+        - $ref: '#/components/parameters/Direction'
+        - $ref: '#/components/parameters/Sandbox'
+        - $ref: '#/components/parameters/FaStatus'
+        - $ref: '#/components/parameters/StartDate'
+        - $ref: '#/components/parameters/EndDate'
+        - $ref: '#/components/parameters/IntegrationId'
+        - $ref: '#/components/parameters/InterchangeSenderId'
+        - $ref: '#/components/parameters/InterchangeReceiverId'
+        - $ref: '#/components/parameters/UnbSenderId'
+        - $ref: '#/components/parameters/UnbReceiverId'
       responses:
         '200':
-          description: Raw EDI file content.
+          description: The raw EDI file, streamed as the response body.
           content:
-            text/plain:
+            application/octet-stream:
               schema:
                 type: string
+                format: binary
         '400':
           description: The request failed validation.
           content:
@@ -755,17 +914,42 @@ paths:
                       - code: document_type_required
                         message: The "documentType" query parameter is required to process this request.
                 invalid:
-                  summary: Invalid document type value
+                  summary: documentType names the standard (`X12` here; `EDIFACT` answers the same way), or fileType disagrees with documentType
                   value:
                     errors:
                       - code: edi_invalid_document_type
                         message: X12 is not a valid document type. Please verify the value and try again.
+                partner_id_for_other_standard:
+                  summary: EDIFACT partner id on an X12 lookup
+                  value:
+                    errors:
+                      - code: invalid_search_param_for_X12
+                        message: invalid search param unbSenderId for filetype X12
+                half_window:
+                  summary: Only one of startDate / endDate sent
+                  value:
+                    errors:
+                      - code: start_time_or_end_time_missing
+                        message: start time or end time missing
+                invalid_direction:
+                  summary: direction outside inbound / outbound
+                  value:
+                    errors:
+                      - code: invalid_direction
+                        message: 'direction is invalid. direction should be one of the following: inbound, outbound'
+                invalid_fa_status:
+                  summary: faStatus outside the status set
+                  value:
+                    errors:
+                      - code: invalid_fa_status
+                        message: 'Invalid fa status, only accepted values: notReceived,accepted,acceptedWithErrors,rejected,failed,notApplicable,inProgress'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
           description: |-
-            No transaction was found matching the provided document type and
-            document number combination.
+            No transaction matched the document number, type and filters — or
+            one did, but its file is no longer in storage (it aged out of the
+            account's data retention period, or was never captured).
           content:
             application/json:
               schema:
@@ -776,6 +960,159 @@ paths:
                     errors:
                       - code: edi_transaction_not_found
                         message: No transaction was found matching the provided document type and document number.
+                file_unavailable:
+                  value:
+                    errors:
+                      - code: edi_file_unavailable
+                        message: The EDI file for this transaction is not available.
+        '422':
+          description: The account has no B2B Manager (EDI) license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                license:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+  /v1/edi/documents/ediFile:
+    get:
+      x-internal: false
+      operationId: downloadEdiFileByLookup
+      tags:
+        - EDI Transactions
+      summary: Download the latest EDI file matching filters
+      description: |-
+        Streams the raw EDI document of the latest transaction (by
+        `lastModified`) that matches the lookup filters — for callers that
+        hold trading-partner context but no document number. The filters AND
+        together and at least one must be sent. Acknowledgement files are not
+        served here; use `GET /v1/ediTransactions/{_ediTransactionId}/ediFile?type=fa`.
+
+        `documentNumber` may be passed as a query parameter here; when it is,
+        `documentType` becomes required — the same contract as
+        `GET /v1/edi/documents/{documentNumber}/ediFile`. When `documentNumber`
+        and `documentType` are both omitted, the lookup runs against X12 unless
+        `fileType` says `EDIFACT` — `unbSenderId` sent on its own is refused
+        with `invalid_search_param_for_X12`. Partner ids
+        use the same names as `POST /v1/ediTransactions/query`:
+        `interchangeSenderId` / `interchangeReceiverId` for X12,
+        `unbSenderId` / `unbReceiverId` for EDIFACT.
+
+        Public-API route only: there is no equivalent for applications acting
+        with a signed-in user's session. Downloads are rate limited per user.
+      parameters:
+        - name: documentNumber
+          in: query
+          required: false
+          schema:
+            type: string
+            examples:
+              - PO03302026A
+          description: |-
+            Business document number to match (e.g. a purchase-order number from
+            an 850's BEG03); letters are uppercased. Requires `documentType`.
+        - $ref: '#/components/parameters/DocumentType'
+        - $ref: '#/components/parameters/FileType'
+        - $ref: '#/components/parameters/Direction'
+        - $ref: '#/components/parameters/Sandbox'
+        - $ref: '#/components/parameters/FaStatus'
+        - $ref: '#/components/parameters/StartDate'
+        - $ref: '#/components/parameters/EndDate'
+        - $ref: '#/components/parameters/IntegrationId'
+        - $ref: '#/components/parameters/InterchangeSenderId'
+        - $ref: '#/components/parameters/InterchangeReceiverId'
+        - $ref: '#/components/parameters/UnbSenderId'
+        - $ref: '#/components/parameters/UnbReceiverId'
+      responses:
+        '200':
+          description: |-
+            The raw EDI file of the latest matching transaction, streamed as the
+            response body.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          description: The request failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                no_filter:
+                  summary: No lookup filter at all
+                  value:
+                    errors:
+                      - code: lookup_filter_required
+                        message: At least one lookup parameter is required when documentNumber is not provided (documentType, partner IDs, direction, faStatus, dates, sandbox, or _integrationId).
+                missing_type:
+                  summary: documentNumber sent without documentType
+                  value:
+                    errors:
+                      - code: document_type_required
+                        message: The "documentType" query parameter is required to process this request.
+                partner_id_for_other_standard:
+                  summary: X12 partner id on an EDIFACT lookup
+                  value:
+                    errors:
+                      - code: invalid_search_param_for_EDIFACT
+                        message: invalid search param interchangeSenderId for filetype EDIFACT
+                partner_id_without_a_standard:
+                  summary: unbSenderId with neither documentType nor fileType — the lookup ran against X12
+                  value:
+                    errors:
+                      - code: invalid_search_param_for_X12
+                        message: invalid search param unbSenderId for filetype X12
+                invalid_sandbox:
+                  summary: sandbox outside true / false
+                  value:
+                    errors:
+                      - code: invalid_sandbox
+                        message: sandbox is invalid. sandbox should be true or false
+                invalid_integration_id:
+                  summary: Malformed _integrationId
+                  value:
+                    errors:
+                      - code: invalid_integration_id
+                        message: _integrationId is not a valid identifier.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No transaction matched the filters — or one did, but its file is no
+            longer in storage (it aged out of the account's data retention
+            period, or was never captured).
+          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 lookup filters.
+                file_unavailable:
+                  value:
+                    errors:
+                      - code: edi_file_unavailable
+                        message: The EDI file for this transaction is not available.
+        '422':
+          description: The account has no B2B Manager (EDI) license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                license:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
 components:
   securitySchemes:
     bearerAuth:
@@ -1351,6 +1688,23 @@ components:
             - https://integrator-userdata-delete-30.s3.us-east-1.amazonaws.com/ediTransactions/5e58483b68b52e5827d56a86/TransactionSummary_20260614_20260713_5e58483b68b52e5827d56a86.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
       required:
         - url
+    EDITransactionFileSignedUrlResponse:
+      type: object
+      description: |-
+        Pre-signed S3 URL for downloading an EDI transaction file. The URL is
+        short-lived — fetch it right away and request a new one for a later
+        download rather than storing it.
+      properties:
+        signedURL:
+          type: string
+          format: uri
+          description: |-
+            Pre-signed S3 URL that streams the EDI file when fetched with a plain
+            GET (no auth headers needed). Short-lived; never store it.
+          examples:
+            - https://integrator-files.s3.us-east-1.amazonaws.com/26338886c17c45e1840e0a7ec81a1a2d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
+      required:
+        - signedURL
     EDITransactionMdnResponse:
       type: object
       description: |-
@@ -1439,5 +1793,169 @@ components:
               summary: Bearer token invalid or revoked
               value:
                 message: Bearer Authentication Failed
+  parameters:
+    FileType:
+      name: fileType
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - X12
+          - EDIFACT
+        x-enumDescriptions:
+          X12: ANSI X12 EDI standard
+          EDIFACT: UN/EDIFACT EDI standard
+      description: |-
+        EDI standard the lookup runs against. Inferred from `documentType` when
+        one is sent, and must agree with it.
+    Direction:
+      name: direction
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - inbound
+          - outbound
+        x-enumDescriptions:
+          inbound: Document received from a trading partner
+          outbound: Document sent to a trading partner
+      description: Narrows the lookup to one transaction direction. Case-insensitive.
+    Sandbox:
+      name: sandbox
+      in: query
+      required: false
+      schema:
+        type: boolean
+      description: |-
+        When true, narrows the lookup to sandbox transactions; when false, to
+        production ones.
+    FaStatus:
+      name: faStatus
+      in: query
+      required: false
+      style: form
+      explode: false
+      schema:
+        type: array
+        items:
+          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
+          notReceived: Functional acknowledgment expected but not yet received
+          accepted: Acknowledged and accepted
+          acceptedWithErrors: Acknowledged with errors but accepted
+          rejected: Acknowledged and rejected
+          failed: Functional acknowledgment processing failed
+      description: |-
+        Narrows the lookup to records in any of the given functional-acknowledgment
+        statuses — one value, or several comma-separated (`faStatus=rejected,failed`).
+    StartDate:
+      name: startDate
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '2026-10-01T00:00:00Z'
+          - '1759276800000'
+      description: |-
+        Lower bound of the `lastModified` window, as an ISO-8601 timestamp or
+        epoch milliseconds. Must be sent together with `endDate` and lie before it.
+    EndDate:
+      name: endDate
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '2026-10-21T00:00:00Z'
+          - '1761004800000'
+      description: |-
+        Upper bound of the `lastModified` window, as an ISO-8601 timestamp or
+        epoch milliseconds. Must be sent together with `startDate`.
+    IntegrationId:
+      name: _integrationId
+      in: query
+      required: false
+      schema:
+        type: string
+        format: objectId
+        x-celigo-refModel: integrations
+        examples:
+          - 66cc9b31f2be816bf9377036
+      description: |-
+        Narrows the lookup to transactions processed by one integration. A
+        malformed id is rejected with 400 `invalid_integration_id`.
+    InterchangeSenderId:
+      name: interchangeSenderId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '1234567890'
+      description: |-
+        X12 only — the record's `isaSenderId` (ISA06), matched exactly or against
+        the stored value padded with trailing spaces; letters are uppercased.
+        Rejected when the lookup runs against EDIFACT.
+    InterchangeReceiverId:
+      name: interchangeReceiverId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - CELIGOLABZ
+      description: |-
+        X12 only — the record's `isaReceiverId` (ISA08), matched like
+        `interchangeSenderId`. Rejected when the lookup runs against EDIFACT.
+    UnbSenderId:
+      name: unbSenderId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - PARTNERGLN
+      description: |-
+        EDIFACT only — the record's `unbSenderId` (UNB02), matched exactly or
+        against the stored value padded with trailing spaces; letters are
+        uppercased. Rejected when the lookup runs against X12.
+    UnbReceiverId:
+      name: unbReceiverId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - CELIGOGLN
+      description: |-
+        EDIFACT only — the record's `unbReceiverId` (UNB04), matched like
+        `unbSenderId`. Rejected when the lookup runs against X12.
+    DocumentType:
+      name: documentType
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '850'
+      description: |-
+        EDI document type code — for X12 the numeric transaction-set ID as a
+        string (`850`, `810`, `856`, `997`); for EDIFACT the UNH01 message type
+        (`ORDERS`, `INVOIC`, `DESADV`, `CONTRL`). Case-insensitive. It also
+        selects the EDI standard the lookup runs against. `X12` and `EDIFACT`
+        name the standard, not a document type, and are rejected here.
 x-enable-proxy: true
 x-internal: false