Generate EDI
This functionality is available on all plans.
Once you configure a trading partner with an outbound transaction setting and a connection, you can:
- Send test files from your browser
- Send test or production files programmatically using the Generate EDI API.
Stedi displays each successfully generated transaction in the Transactions tab.
Send test files in the browser
You can send outbound test files to your trading partner from within Stedi. This can be useful during the onboarding process with your partner.
Test files contain a T
in the Usage
element of the ISA header. This indicates that the file is a test file and should not be processed by your trading partner’s production system. Sometimes, your trading partner will provide you with a dedicated test FTP or AS2 connection. If they have done so, be sure to assign the test connection to your outbound transaction setting.
To generate and send an outbound file:
-
Do one of the following:
- Go to the File executions page.
- Go to the Trading partners page, click a partnership, go to its outbound transaction settings, and click the *(…) ellipses next to the transaction setting you want to use to generate the test file.
-
Click Send EDI.
-
Select a Partnership and a Transaction setting. These are autopopulated if you generate test data from within a partnership.
-
(Optional) Set Advanced settings. For example, you may want to set a Filename if your trading partner has specific requirements for the file name. If you do not specify a filename, Stedi generates a unique file name using a UUID.
-
Edit the Transaction payload to include realistic or actual data from your system. The payload editor validates your data as you change it.
- If the guide associated with this transaction setting has sample files, you can choose a Sample and load its data into the editor.
-
Click Continue and then click Send EDI.
You can review the test file in the File Executions page and all processed transactions on the Transactions page.
Outbound processing flow
EDI files are generated and delivered according to the partnership’s outbound transaction settings. This includes using the specified guide for validation and the associated connection for file delivery.
When you use call the Generate API, Stedi:
- Validates the JSON against the configured guide, and returns an error if validation is not successful
- Generates an EDI document that conforms to the specified guide
- Persists the JSON payload and resulting EDI file
- Delivers the EDI file to the specified connection
- Displays the transaction in your transactions list
- Emits a
file.delivered.v2
event and one or moretransaction.processed.v2
events, which can be used for advanced processing.
Generate EDI
You can use Stedi’s Generate EDI API to generate and deliver fully-formed EDI files to your trading partners.
Format transaction payloads
The transaction payload must match the JSON Schema of the guide associated with the outbound transaction setting for the partnership.
To find the JSON Schema for a guide:
- Navigate to the Trading partners page.
- Select the partnership for which you want to generate EDI.
- Click the name of the guide associated with the outbound transaction setting.
- Click the EDI Inspector tab and choose a sample.
- Click JSON in the upper left to show the JSON schema.
- Go to the
transactionSets
array and copy the first object, which includes theheading
,detail
, andsummary
objects. You do not need to include thetransaction_set_trailer_SE
object because the Generate API populates this information automatically. - Save this as a
.json
file. This file contains the schema you must use when sending payloads to the Generate EDI API.
If you need a way to transform your internal format to Stedi’s JSON format, we recommend Stedi Mappings. You can create mappings directly from any Stedi guide.
Making an API call
The Generate API uses the following runtime data to generate and deliver an EDI file:
Data | Required | Dscription |
---|---|---|
Partnership ID | Yes | Used within the API route (partnerships/<PARTNERSHIP_ID>/generate-edi ) to identify the associated partnership. You can find this on the Trading partners page under Partnership identifier. |
transactionSettingId | Yes | Specifies the outbound transaction setting Stedi should use to determine the correct guide for validation and generation, as well as the connection to use for delivery. To find this ID, go to partnership, click the outbound transaction setting, and use the Identifier field on its details page. |
transactions | Yes | This payload contains the transaction data and must conform to the guide associated with each transaction setting. The Generate API accepts multiple arrays of transactions in a single API call, allowing you to send multiple transactions or even multiple functional groups in a single file. |
filename | Optional | You can use this parameter to specify the name of the generated EDI file. Stedi overwrites files with the same name, so we recommend making the filename unique by including a timestamp or other identifier. If you do not specify a filename, Stedi autogenerates a unique name using a UUID. |
Visit the Generate EDI API documentation for full details.
Example request
The following example shows a cURL request with the transactions
array abbreviated for readability.
curl --location 'https://core.us.stedi.com/2023-08-01/x12/partnerships/<PARTNERSHIP_ID>/generate-edi' \
--header 'Content-Type: application/json' --header 'Authorization: Key YOUR_STEDI_API_KEY' \
--data-raw '{
"filename": "my-output-file.edi",
"transactionGroups": [
{
"transactionSettingId": "<TRANSACTION_SETTING_ID>",
"transactions": [
{
"heading": {},
"detail": {},
"summary": {}
}
]
}
]
}'
Both the API and SDK return the full X12 EDI file in the response. The response also includes an artifactId
(equivalent to the file name) and a globally unique fileExecutionID
that you can use to locate the generated file.
These generated files appear in the File executions list with the direction indicated as ↗ Sent. Each transaction within the generated file also appears in the Transactions list.
Advanced EDI generation: The Generate API can automatically generate multiple Functional Groups in a single Interchange. The Generate API groups transactions into the correct Functional Group, based on Functional Identifier Code for a given transaction set.
997 Functional Acknowledgments
Stedi can automatically generate 997 Functional Acknowledgments for every inbound transaction associated with a partnership, so you should not need to use the Generate API to send 997s. Visit Profiles and partnerships for details on how to enable this functionality.
API upgrades
We strive to maintain backwards compatibility. The following changes are considered backwards compatible:
- New API resources
- Additional optional parameters to API requests
- Additional fields in API responses
- Changes in the order of properties in API responses
- Changes in human-readable error messages
- Downgrading mandatory parameters to optional parameters.
When we introduce a breaking change, we release a root-level, dated version.