
## Frequently asked questions

Below is a list of frequently asked questions about the EDI Translate API. If you have any questions not listed here, please [contact us](https://www.stedi.com/contact).

## Data & Privacy

### How does the EDI Translate API use my data?

In short, we don’t. The payloads sent to the `translate` API are not stored – temporarily or permanently. The contents of your file are encrypted in transit.

### Is data sent to the EDI Translate API stored?

The `translate` API is a stateless system that executes a transformation on your data. The transformation happens during the duration of the request; we do not retain the payload once a response is returned.

### What does Stedi log when I hit the EDI Translate API?

We log only request meta information such as the size of the request, latency, transaction sets, and release.

These data points allow our engineers to monitor the health of the system and drive improvements to the service. They help the team answer questions like:

- How many requests did the API receive over the past week?
- What percentage of the responses returned a 4XX/5XX status code?
- Why did latency increase after the most recent deployment?

If a request fails with a 500 status code, an engineer on the team is notified (yes, we investigate every single one).


How your data is handled when using Stedi’s EDI Translate API

Data and privacy

EDI Translate Data and Privacy


The EDI Translate API has several limits on how you can use the service. If you are impacted or blocked by any of these restrictions, please [contact support](https://www.stedi.com/docs/support), and we can help solve your issue.

| Resource or operation       | Limit           | Can be increased |
| --------------------------- | --------------- | ---------------- |
| Requests per second         | 25              | Yes              |
| Maximum concurrent requests | 100             | Yes              |
| Maximum request size        | 6 megabytes[^1] | No[^2]           |
| Maximum response size       | 6 megabytes[^1] | No[^2]           |

[^1]: The request and response sizes are limited by the size of the HTTP request. You can receive more data when you use gzip compression on your request. Most HTTP clients support compression, and you can enable it by setting the `Accept-Encoding` header to `gzip`. When translating EDI to JSON with compression enabled, the maximum response size limit applies to the size of the compressed JSON response.
[^2]: [Stedi Core](https://www.stedi.com/docs/core) supports parsing large files. For more information, visit [Limits](https://www.stedi.com/docs/core/limits) in the Core documentation.


Request and response limits for Stedi’s EDI Translate API

Limits

EDI Translate Limits


The EDI Translate API is billed based on usage. There are no minimum fees, monthly commitments, or upfront costs to use this product.

Usage is calculated based on request count and MB processed.

A request is defined as a single call to the EDI Translate API, regardless of how many transactions (e.g. ST segments) are in the payload.

## Pricing tiers

### API request count pricing

The first 1,000 requests per month are free. Each API request includes a 10 KB data allowance.

| **Request Count per Month** | **Price**             |
| --------------------------- | --------------------- |
| First 1,000                 | Free                  |
| 1,000 to 250,000            | $0.007500 per request |
| 250,000 to 500,000          | $0.006750 per request |
| 500,000 to 1,000,000        | $0.006375 per request |
| Above 1,000,000             | $0.006000 per request |

### API bytes processed per request pricing

Each API request includes a 10 KB data allowance, and you're only charged for bytes processed above the 10 KB allowance per request. The first 5 MB of data processed per month are free.

| **Data Processed per Month** | **Price**                         |
| ---------------------------- | --------------------------------- |
| Up to 5 MB\*                 | Free                              |
| Above 5 MB                   | $0.0075 for each additional 50 KB |

[Contact us](https://www.stedi.com/contact) if you have a question on pricing.

\*1 MB = 1024 KB or 1,048,576 bytes


Pricing information for Stedi’s EDI Translate API

Pricing

EDI Translate Pricing

EDI Translate takes a JSON document that’s already structured like EDI and turns it into an X12 EDI document. You need a Stedi guide that describes the structure. If you have a JSON document that’s not structured like EDI, you have to map it first.

- See also: [Create a Stedi guide](/docs/guides)
- See also: [Map a JSON document](/docs/mappings)



## JSON structure

The Stedi guide determines how the input JSON should be structured. If you need an example of the JSON structure, you can [open your Stedi guide](https://www.stedi.com/app/guides/) and go to the _EDI Inspector_ tab. It will show you an example of both the EDI and the JSON.

## Envelope

EDI documents have envelopes that contain metadata. That metadata is typically not included in the JSON document, so you need to provide it separately.

There are three types of envelopes.

- The interchange ([ISA](https://www.stedi.com/edi/x12/segment/ISA)) tells you who the message is for on an organization level. It identifies you as the sender and your trading partner as the receiver.
- The functional ([GS](https://www.stedi.com/edi/x12/segment/GS)) group tells you who the message is for on a department level. Invoices go to the Finance department, ship notices go to the Shipping department, that sort of thing.
- The transaction set ([ST](https://www.stedi.com/edi/x12/segment/ST)) represents a single document. An EDI message can contain multiple documents and the transaction set envelope helps keep them apart.

Each envelope has a start segment and an end segment. EDI Translate will generate these segments based on the data you provide.

```json
{
  "interchangeHeader": {
    "senderQualifier": "ZZ",
    "senderId": "ME",
    "receiverQualifier": "ZZ",
    "receiverId": "YOU",
    "date": "2022-08-15",
    "time": "13:20",
    "usageIndicatorCode": "P",
    "controlNumber": "12"
  },
  "groupHeader": {
    "functionalIdentifierCode": "PO",
    "applicationSenderCode": "ME",
    "applicationReceiverCode": "YOUR DEPT",
    "date": "2022-08-15",
    "time": "13:20:52",
    "controlNumber": "1"
  }
}
```

| Interchange field  | Description                                                                                                                                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| senderId           | Identifies the sender of the message.                                                                                                                                                                                                                      |
| senderQualifier    | Indicates the type of identifier used in `senderId`. For example, `01` means Duns, `20` means Health Industry Number, `ZZ` whatever you agree on. The implementation guide should tell you which values are valid. If not, contact your trading partner.   |
| receiverId         | Identifies the receiver of the message.                                                                                                                                                                                                                    |
| receiverQualifier  | Indicates the type of identifier used in `receiverId`. For example, `01` means Duns, `20` means Health Industry Number, `ZZ` whatever you agree on. The implementation guide should tell you which values are valid. If not, contact your trading partner. |
| date               | The date this message was sent, e.g. `2022-08-15`.                                                                                                                                                                                                         |
| time               | The time this message was sent, e.g. `13:20`.                                                                                                                                                                                                              |
| usageIndicatorCode | `P` if this is a production message, `T` if it’s a test message, `I` if the message is informational.                                                                                                                                                      |
| controlNumber      | A unique identifier for this interchange.                                                                                                                                                                                                                  |

| Functional group field   | Description                                                                                                                                                                                                            |
| ------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| functionalIdentifierCode | Indicates the type the message. Must be one of the [standardized functional identifier code](https://www.stedi.com/edi/x12/element/479).                                                                               |
| applicationSenderCode    | Indicates where the message came from. There are no standardized codes; you need to agree on valid values with your trading partner. If you can’t find this in the implementation guide, contact your trading partner. |
| applicationReceiverCode  | Indicates where the message should go. There are no standardized codes; you need to agree on valid values with your trading partner. If you can’t find this in the implementation guide, contact your trading partner. |
| date                     | The date this message was sent, e.g. `2022-08-15`.                                                                                                                                                                     |
| time                     | The time this message was sent, e.g. `13:20:52`.                                                                                                                                                                       |
| controlNumber            | A unique identifier for this functional group.                                                                                                                                                                         |

If you want to specify the transaction set envelope, you should do so in the JSON document, not in the `envelope` field.

Translate takes care of writing the transaction set trailer (SE segment) as long as the information for the transaction set header (ST) is provided in the JSON document. If the document does not include the transaction set header, translate will NOT write out the trailer.

At the moment, it isn’t possible to produce EDI documents with multiple functional groups.

## Delimiters

When writing EDI, EDI Translate uses the delimiters configured in the Stedi guide. When you create a guide, a default set of delimiters is assigned to the guide. You have the ability to change these values through the Stedi Guides UI. Just open your guide and click on _Overview_ in the top left. You’ll find the delimiters at the bottom.

## Calling the API

You translate a document by calling the API. First you need an [API key](https://www.stedi.com/app/settings/api-keys) and then you can call the EDI Translate endpoint: `https://edi-translate.us.stedi.com/2022-01-01/x12/from-json`.

```javascript
const axios = require("axios");

const apiKey = process.env.STEDI_API_KEY;

async function jsonToX12(guideId, document, envelope) {
  if (typeof document === "string") {
    document = JSON.parse(document);
  }

  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/from-json",
    data: {
      guideId: guideId,
      input: document,
      envelope: envelope,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

With EDI Translate, you can translate a JSON document into X12 EDI. You need a Stedi guide to describe the structure of the JSON.

Translate JSON to X12 EDI

EDI Translate takes X12 EDI and turns it into a JSON document.
You may use a Stedi guide to describes the structure of the document.
Guides ensure that EDI exchanged between trading partners meets their needs.
The shape of the JSON document resembles the original X12 EDI, but you can map it into any shape you need.

You may also translate X12 EDI without a guide for more flexibility.
Review calling the API [without a guide](#without-a-guide) for more details.

- See also: [Create a Stedi guide](/docs/guides)
- See also: [Map a JSON document](/docs/mappings)



## Envelopes

The interchange envelope ([ISA](https://www.stedi.com/edi/x12/segment/ISA)) and functional group envelope ([GS](https://www.stedi.com/edi/x12/segment/GS)) are optional, but if you provide either, you should provide both. The input EDI can optionally contain the transaction set envelope ([ST](https://www.stedi.com/edi/x12/segment/ST)).

At the moment, it isn’t possible to translate EDI documents with multiple functional groups. Multiple transaction sets within the same functional group works fine, though.

## Delimiters

The delimiters used during translation depend on the type of EDI document you submit.

- EDI document with ISA envelope.
  The delimiters specified in the ISA segment are used for parsing purposes.
  Delimiters specified in the guide or as request input options are ignore in this case.
- EDI document without ISA and GS envelopes.
  If EDI Translate is called with a guide, the delimiters specified in the guide will be used.
  If EDI Translate is called without a guide, the delimiters specified in `guidelessInputOptions` will be used.

The response of the [`to-json` endpoint](https://www.stedi.com/docs/api/edi-translate#TranslateJsonToX12) includes the delimiters used during processing of the EDI document.

## Calling the API

You translate a document by calling the API. First you need an [API key](/docs/accounts-and-billing/authentication) and then you can call the EDI Translate endpoint: `https://edi-translate.us.stedi.com/2022-01-01/x12/to-json`.

### With a Guide

```javascript
const axios = require("axios");

const apiKey = process.env.STEDI_API_KEY;

async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      guideId: guideId,
      input: document,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

### Without a Guide

Using EDI Translate without a Stedi guide lets you receive X12 EDI that might not conform to strict, partner-specific EDI requirements. Translation flexibility is useful for the following use cases:

- Developing and testing a new trading partner integration
- Troubleshooting EDI that doesn't meet your expectations
- Developing a guide to make sure EDI you receive meets your requirements

When you translate EDI without a Stedi guide, EDI Translate validates the incoming EDI with the generic X12 release specification and uses a default structure definition for the resulting JSON document. For example, the output will use default names for all properties.

Therefore, we do not recommend translating without a Stedi guide in production scenarios that require accurately processing partner-specific data. For example, updating an ERP system in response to incoming EDI may require specific fields for data consistency. In this case, you should use a guide to ensure these fields are present before the data is passed to the ERP system.

To translate without a guide, simply omit the `guideId` argument from the API call.

```javascript
async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      input: document,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

If your X12 EDI document does not have an ISA or GS envelope you will need to
specify an X12 release to use.

```javascript
async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      input: document,
      inputOptions: {
        guidelessInputOptions: {
          x12Release: "004010",
        },
      },
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

With EDI Translate, you can translate X12 EDI into a JSON document. You can use a Stedi guide to describe the structure of the document.

Translate X12 EDI to JSON


Stedi strives for backwards compatibility for all products in general availability.

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 a breaking change is made, a root-level, dated version is released.

For more information on the product lifecycle, please see the [Preview Program](/docs/getting-started/preview-program).


Upgrades


EDI Translate lets you translate documents between X12 EDI and JSON.

Many use cases require using EDI Translate with a [Stedi guide](/docs/guides) that describes the structure of the JSON. We provide recommendations about when you may want to [use EDI Translate without a guide](edi-translate/translate-x12-edi-to-json#calling-the-api-without-a-guide).

## Use cases

- **Writing EDI documents.** Generate X12 EDI documents based on a Stedi guide to ensure outgoing EDI documents adhere to your partner's specific requirements.
- **Reading EDI documents.** Read X12 EDI documents received from your trading partner with or without a guide, depending on your use case.

## Getting started

Before you can use EDI Translate, you need a Stedi account and an API key.

- [Create a Stedi account](/terminal/sign-up) (free and no credit card required)
- [Create an API key](/docs/accounts-and-billing/authentication)

After that, you can get started.

- [Translate JSON to X12 EDI](/docs/edi-translate/translate-json-to-x12-edi)
- [Translate X12 EDI to JSON](/docs/edi-translate/translate-x12-edi-to-json)


The server response for authorization failure.

A validation error found when processing EDI data.

A validation warning found when processing EDI data.

The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

The server response when an unexpected error occurred while processing request.

A validation error found when processing JSON data.

The location in the EDI document where the problem occurred. May be a single index or a range.

The server response when the requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.

The server either does not recognize the request method, or it lacks the ability to fulfil the request.

The server could not process the request because of conflict in the current state of the resource.

The server response for the request too large error.

The server cannot handle the request due to technical reasons.

The server response when usage plan or account-level throttling limits exceeded.

Options that tell EDI Translate how to format the output.

Input options specific to Guideless translation

The server response when the authorizer failed to authenticate the caller.

The server response when the operation specified could not be found.

The server response when a payload is of an unsupported media type.

The delimiters defined by the X12 standard to separate
elements, segments.

The EDI Translate product is responsible for translating data between JSON and EDI formats.
It uses a [Stedi guide](/docs/guides), which validates the data being translated, and is the
resource which enables the API to determine how the EDI output is structured and formatted.

Proprietary

EDI Translate

Converts a JSON document into X12 EDI, using the provided `guideId`.

Converts an X12 EDI string into a JSON document, using the provided `guideId`.

EDI Translate

Getting started

Feedback