Documentation

What is EDI API

Article author
Admin
  • Updated

EDI API is organized around REST and hosted in the cloud, which makes it straightforward to translate, view, edit, create, verify, document, import SEF, and acknowledge EDI files in seconds.

To use EDI API you need to create an account.

EDI API has predictable resource-oriented URLs, accepts either multipart/form-data or JSON-encoded request bodies, returns either JSON-encoded or application/octet-stream responses, and uses standard HTTP response codes, authentication, and verbs.

 

EDI API Base URL

https://api.edination.com/v2

 

Authentication

EDI API uses API keys to authenticate requests. You can obtain, view, and manage your API keys in the developer portal

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

The API key must be set as an HTTP header parameter:

Ocp-Apim-Subscription-Key: {your-api-key}

For JavaScript usage, EdiNation supports Cross-Origin Resource Sharing (CORS), so that you can use these headers in conjunction with XMLHttpRequest.

 

Hosts

The REST API lets you interact directly with EdiNation from anything that can send an HTTP request. All API access must use HTTPS. The primary host is:

api.edination.com

Enterprise plan users with dedicated hosts will have the host in the following format, where the id will be assigned individually:

api-{id}.edination.com

 

Versioning

When we make backward-incompatible changes to the API, we release new versions. The latest version is v2. The version number must be added as a postfix to the base URL to identify the correct endpoint for that version.

The endpoint for v2 is:

api.edination.com/v2

 

Format

The API uses the following formats:

  1. JSON encoded as UTF-8 for all resources and errors
  2. Content-Type form-data when uploading EDI files for translation
  3. Content-Type application/octet-stream when downloading generate EDI files or acknowledgments

 

Parameters

Unless otherwise stated, parameters must be passed in the URL's query string for all requests (GET, DELETE, and POST). Parameters must be properly URL-encoded, using the UTF-8 encoding for non-ASCII characters.

 

Endpoints

Verb Operation Description
POST /x12/read Translate X12 file to X12 JSON
POST /edifact/read Translate EDIFACT file to EDIFACT JSON
POST /x12/write Translate X12 JSON to X12 file
POST /edifact/write Translate EDIFACT JSON to EDIFACT file
POST /x12/validate Validate X12 JSON
POST /edifact/validate Validate EDIFACT JSON
POST /x12/ack Generate X12 997, 999 and/or TA1
POST /edifact/ack Generate EDIFACT CONTRL

All API endpoints are relative to the base URL. For example, assuming the base URL of https://api.edination.com/v2, the /x12/read endpoint refers to https://api.edination.com/v2/x12/read.

 

Models Casing

The API is case insensitive, and you can use your preferred casing convention, camel case, or other, to consume the API.

 

Errors

EdiNation uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with EdiNation's servers (these are rare).

When a request fails, the response body is still JSON, but always contains a code field with the error id and details field with an array of error descriptions, which you can inspect for debugging.

{
  "Code": 0,
  "Details": [
    "string"
  ]
}

When the quota limit is reached, the caller will receive a 403 Forbidden response status code.

 

API Status

API Status watches our infrastructure and tells you if it's running as expected.

The health of a resource is displayed as one of the following statuses:

  1. Available

    Available means that there are no events detected that affect the health of the API.

  2. Unavailable

    Unavailable means that the API detected an ongoing platform or non-platform event that affects the health of all underlying services.

  3. Degraded

    Degraded means that the API detected a loss in performance, although it's still available for use.

Go to API Status page

 

API SDKs

SDKs make it easy for you to use EdiNation's REST APIs and do other common programming tasks. These helper libraries are available in a variety of popular programming languages.

To generate a client or server SDK in your preferred language, download the full OpenAPI 3/Swagger of the API.

Download API Swagger

Use the API Swagger either with your favorite SDK generation tool or generate an SDK directly from SwaggerHub.

swagger-sdk.png

 

API Tutorials

To learn more about how to translate and validate EDI files with EDI API try these tutorials:

Share this:

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.