Create a Transaction

Pre-requisites

Before you can create a Transaction you must have:

Create a Transaction

In most instances, EDI transactions will be created by your System of Record (SOR) and then passed on to Orderful. However there are situations where you may want to enter a transaction directly into Orderful, for example for testing purposes.

The transaction must correspond to an existing, configured Relationship in Orderful. This means that, in order to send a test transaction, you must have at least one inbound Relationship configured.

To create a Transaction you can:

Upload a file

To upload a transaction in a file:

  1. Go to the Transactions page
  2. Click on Create Transaction
  3. Select Upload transaction
  4. Choose the file you want to upload.

Transaction files in X12 format can use .txt or .x12 extensions, files in JSON format can use the .json extension. For more information about how the file contents must be structured see format information below.

File format for JSON

Files containing JSON must use the following structure. The contents of your transaction should be entered into the message object.

To see the possible Transaction Type values, see Available Transaction Types.

{
    "type": {
        "name": "TRANSACTION_TYPE_NAME"
    },
    "stream": "test",
    "message": {
        [...] // Enter your data here
    },
    "sender": {
        "isaId": "ISA_ID_SENDER"
    },
    "receiver": {
        "isaId": "ISA_ID_RECEIVER"
    }
}
File format for X12

For files in the X12 format must:

  • Start with an ISA segment.
  • Have at least one interchange envelope (ISA/IEA segments).
  • Have at least one functional group inside each interchange envelope (GS/GE segments).
  • Have at least one transaction set inside each functional group (ST/SE segments).
  • Respect the presence and order of loops, segments, and elements defined by the X12 standards for each transaction type inside each transaction set.

Make an API call

You can create a Transaction by sending an HTTP POST to the Orderful API's /transactions endpoint.

📘

You can send the Transaction data in either JSON or X12 format.

For help generating the content of the transaction, see Generating an example payload below. For a full description of this endpoint, please see Create a Transaction.

curl --location --request POST 'https://api.orderful.com/v3/transactions' \
--header 'Content-Type: application/json' \
--header 'orderful-api-key: YOUR_API_KEY' \
--data-raw '{
    "stream": "test",
    "sender": {
        "isaId": "YOUR ISA ID HERE"
    },
    "receiver": {
        "isaId": "AMAZONIADEMO"
    },
    "type": {
        "name": "850_PURCHASE_ORDER"
    },
    "message": {
  "transactionSets": [
    {
      "transactionSetHeader": [
        {
          "transactionSetIdentifierCode": "850",
          "transactionSetControlNumber": "0001"
        }
      ],
      "beginningSegmentForPurchaseOrder": [
        {
          "transactionSetPurposeCode": "00",
          "purchaseOrderTypeCode": "SA",
          "purchaseOrderNumber": "PO123456789",
          "date": "20200828"
        }
      ],
      "referenceInformation": [
        {
          "referenceIdentificationQualifier": "DP",
          "referenceIdentification": "210"
        }
      ],
      "dateTimeReference": [
        {
          "dateTimeQualifier": "002",
          "date": "20200910"
        },
        {
          "dateTimeQualifier": "010",
          "date": "20200905"
        }
      ],
      "N1_loop": [
        {
          "partyIdentification": [
            {
              "entityIdentifierCode": "BT",
              "name": "ODF Buyer HQ"
            }
          ],
          "partyLocation": [
            {
              "addressInformation": "1119 BUSH STREET"
            }
          ],
          "geographicLocation": [
            {
              "cityName": "SAN FRANCISCO",
              "stateOrProvinceCode": "CA",
              "postalCode": "94101"
            }
          ]
        },
        {
          "partyIdentification": [
            {
              "entityIdentifierCode": "ST",
              "name": "ODF BUYER MAIN STORE"
            }
          ],
          "partyLocation": [
            {
              "addressInformation": "1207 WASHINGTON RD"
            }
          ],
          "geographicLocation": [
            {
              "cityName": "SEATTLE",
              "stateOrProvinceCode": "WA",
              "postalCode": "98101"
            }
          ]
        }
      ],
      "PO1_loop": [
        {
          "baselineItemData": [
            {
              "assignedIdentification": "1",
              "quantity": "48",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "26.25",
              "productServiceIDQualifier": "UP",
              "productServiceID": "711719100246",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009"
            }
          ],
          "PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES VERMILLION (E16249)"
                }
              ]
            }
          ]
        },
        {
          "baselineItemData": [
            {
              "assignedIdentification": "2",
              "quantity": "120",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "27.45",
              "productServiceIDQualifier": "UP",
              "productServiceID": "611719100245",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009A"
            }
          ],
          "PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES YELLOW (F8C729)"
                }
              ]
            }
          ]
        }
      ],
      "CTT_loop": [
        {
          "transactionTotals": [
            {
              "numberOfLineItems": "2"
            }
          ]
        }
      ],
      "transactionSetTrailer": [
        {
          "numberOfIncludedSegments": "17",
          "transactionSetControlNumber": "0001"
        }
      ]
    }
  ]
}
}
'

Make an API call using our API Explorer

Orderful's API Explorer is integrated into our REST API reference.

You can create a Transaction using our Create a Transaction API reference page.

  1. Go to the Get your organization details page
  2. Get your API key from your Org's API Credentials page and enter it into the "Authentication" at the top right of the page.
  3. You can test that you've inputted your API key correctly by retrieving your Org details.
    1. On the right side of the page, under the payload, click on "Try It!"
    2. You should receive an HTTP 200 response with your Org details in it.
  4. Go to the Create a Transaction page.
  5. On the “Create a Transaction” page, make sure that the “Language” on the right side is “Shell” and in the “Request” section click on Examples > Request Example. This will create an example JSON payload with the correct structure and placeholder values.
  6. Get your (sender) isaId and the receiver’s isaId. These can be found on your Org’s Relationship’s page
  7. Get the contents of your document in JSON format. These contents must begin and end with curly braces: {}
  8. Now you should fill out the “Body Params” section of the page:
    1. Add a type object with a name. The value of the name should be from our list of available Transaction types. For example: 850_PURCHASE_ORDER
    2. Indicate which stream you’d like to create this Transaction in. This will probably be test.
    3. Next, copy the contents of your document into the message box.
    4. Add a sender object, then your isaId.
    5. Add a receiver object, then the receiver’s isaId.
  9. Once everything is filled out, click on Try It! You should receive a 201 response, with a Transaction id in the response.
This is what the completed form should look like.This is what the completed form should look like.

This is what the completed form should look like.

Send a file to your outbound Communication Channel

If you are using an outbound Communication Channel like AS2, FTP, or VAN, you can send the file using this system. The details of how this is done will depend on your implementation.

Transaction validation

After you have sent your transaction, you can check its transaction status by going to your Transactions page.

If there are any issues, please refer to the Transaction Statuses Overview.


Did this page help you?